usar

Executar o Xinference localmente

Vamos usar um modelo clássico de linguagem grande qwen2.5-instruct para demonstrar como executar modelos de linguagem grandes localmente com o Xinference.

Após este guia de início rápido, você pode continuar aprendendo como implantar o Xinference em um ambiente de cluster distribuído.

Levantar o serviço local.

Primeiro, siga as instruções neste documento para garantir que o Xinference está instalado localmente. Use o seguinte comando para iniciar o serviço Xinference local:

shelloutput

xinference-local --host 0.0.0.0 --port 9997

Nota

Por padrão, o Xinference usará <HOME>/.xinference como diretório principal para armazenar informações necessárias, como arquivos de log e arquivos de modelo, onde <HOME> é o diretório principal do usuário atual.

Você pode modificar o diretório principal configurando a variável de ambiente XINFERENCE_HOME, por exemplo:

XINFERENCE_HOME=/tmp/xinference xinference-local --host 0.0.0.0 --port 9997

Parabéns! Você já iniciou o serviço Xinference localmente. Assim que o serviço Xinference estiver em execução, há várias maneiras de utilizá-lo, incluindo por meio da interface web, comandos cURL, linha de comando ou o SDK Python do Xinference.

Você pode acessar a UI através de http://127.0.0.1:9997/ui e consultar a documentação da API em http://127.0.0.1:9997/docs.

Após a instalação através do comando a seguir, é possível utilizar a ferramenta de linha de comando Xinference ou código Python para uso:

pip install xinference

A ferramenta de linha de comando é xinference. Você pode verificar quais comandos estão disponíveis com o seguinte comando:

shelloutput

xinference --help

Se você precisar instalar apenas o SDK Python do Xinference, use o seguinte comando para instalar as dependências mínimas. Observe que a versão deve corresponder à versão do serviço Xinference.

pip install xinference-client==${SERVER_VERSION}

Sobre o motor de inferência do modelo

A partir da versão v0.11.0, antes de carregar um modelo LLM, você precisa especificar o mecanismo de inferência específico. Atualmente, o Xinference oferece suporte aos seguintes mecanismos de inferência:

• vllm

• sglang

• llama.cpp

• transformers

• MLX

Para obter informações detalhadas sobre esses mecanismos de inferência, consulte aqui.

Atenção: ao carregar um modelo LLM, o motor que pode ser executado está intimamente relacionado aos parâmetros model_format e quantization.

O Xinference oferece o comando xinference engine para ajudá-lo a consultar combinações de parâmetros relevantes.

Por exemplo:

1. Quero consultar as combinações de parâmetros relacionadas ao modelo qwen-chat para determinar como ele pode ser executado em vários mecanismos de inferência.

xinference engine -e <xinference_endpoint> --model-name qwen-chat

1. Eu quero executar qwen-chat no motor de inferência VLLM, mas não sei quais outros parâmetros se adequam a esse requisito.

xinference engine -e <xinference_endpoint> --model-name qwen-chat --model-engine vllm

1. Quero carregar o modelo qwen-chat no formato GGUF, preciso saber as outras combinações de parâmetros.

xinference engine -e <xinference_endpoint> --model-name qwen-chat -f ggufv2

Em resumo, em comparação com as versões anteriores, ao carregar o modelo LLM, é necessário passar o parâmetro adicional model_engine. Você pode usar o comando xinference engine para consultar a relação entre o mecanismo de inferência que deseja executar e outras combinações de parâmetros.

Nota

Aqui estão algumas recomendações sobre quando usar qual mecanismo:

• Linux

  • Quando disponível, priorize o uso de vLLM ou SGLang, pois eles oferecem melhor desempenho.

  • Se os recursos forem limitados, considere usar llama.cpp, pois ele oferece mais opções de quantização.

  • Outras considerações de uso Utilize Transformers, que é compatível com quase todos os modelos.

• Windows

  • Recomenda-se usar WSL, e neste caso, escolha a opção compatível com Linux.

  • Outras vezes, recomenda-se usar llama.cpp. Para modelos não suportados, opte por usar Transformers.

• Mac

  • Quando suportado pelo modelo, recomenda-se o uso do MLX Engine, que possui o melhor desempenho.

  • Outras vezes, recomenda-se usar llama.cpp; para modelos não suportados, opte por usar Transformers.

Executar qwen2.5-instruct

Vamos executar um modelo integrado qwen2.5-instruct. Quando você precisar executar um modelo, a primeira execução exigirá o download dos parâmetros do modelo do HuggingFace, geralmente levando de 10 a 30 minutos, dependendo do tamanho do modelo. Após o download, o Xinference armazenará o modelo em cache localmente, de modo que, ao executar o mesmo modelo novamente no futuro, não será necessário baixá-lo novamente.

Nota

O Xinference também permite baixar modelos de outras plataformas de hospedagem de modelos. É possível especificar variáveis de ambiente ao iniciar o Xinference. Por exemplo, se deseja baixar um modelo do ModelScope, use o seguinte comando:

XINFERENCE_MODEL_SRC=modelscope xinference-local --host 0.0.0.0 --port 9997

Você pode usar o parâmetro --model-uid ou -u para especificar o UID do modelo. Se não for especificado, o Xinference gerará um ID aleatório. O ID padrão é o mesmo que o nome do modelo.``:

shellcURLPythonoutput

xinference launch --model-engine <inference_engine> -n qwen2.5-instruct -s 0_5 -f pytorch

Nota

Para alguns mecanismos de inferência, como o vllm, o usuário precisa especificar parâmetros relacionados ao mecanismo ao executar o modelo. Nesse caso, basta especificar diretamente o nome do parâmetro e o valor na linha de comando, por exemplo:

xinference launch --model-engine vllm -n qwen2.5-instruct -s 0_5 -f pytorch --gpu_memory_utilization 0.9

Ao executar o modelo, gpu_memory_utilization=0.9 é passado para o backend do vllm.

Nota

Para mais dicas sobre carregamento de modelos, consulte Guia de Carregamento de Modelos.

Parabéns, você já conseguiu executar o qwen2.5-instruct com sucesso através do Xinference. Assim que este modelo estiver em execução, podemos interagir com ele via linha de comando, cURL ou código Python:

cURLPythonoutput

curl -X 'POST' \
  'http://127.0.0.1:9997/v1/chat/completions' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "qwen2.5-instruct",
    "messages": [
        {
            "role": "system",
            "content": "You are a helpful assistant."
        },
        {
            "role": "user",
            "content": "What is the largest animal?"
        }
    ]
  }'

O Xinference fornece uma API compatível com a OpenAI, portanto, é possível usar os modelos executados no Xinference como uma alternativa local à OpenAI. Por exemplo:

from openai import OpenAI
client = OpenAI(base_url="http://127.0.0.1:9997/v1", api_key="not used actually")

response = client.chat.completions.create(
    model="qwen2.5-instruct",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "What is the largest animal?"}
    ]
)
print(response)

Aqui estão as APIs suportadas da OpenAI:

• Geração de diálogo: https://platform.openai.com/docs/api-reference/chat

• https://platform.openai.com/docs/api-reference/completions

• Geração de vetores: https://platform.openai.com/docs/api-reference/embeddings

O Xinference também suporta chamadas à API Anthropic através da URL base http://127.0.0.1:9997/anthropic, permitindo usar o Xinference em ambientes como o Claude Code. Para mais detalhes, consulte anthropic client.

Gerenciar modelos

Além de iniciar modelos, o Xinference oferece a capacidade de gerenciar todo o ciclo de vida dos modelos. Da mesma forma, você pode gerenciá-los usando a linha de comando, cURL e código Python:

A lista de todos os modelos de tipo específico suportados pelo Xinference é:

shellcURLPython

xinference registrations -t LLM

O próximo comando pode listar todos os modelos em execução:

shellcURLPython

xinference list

Quando não precisar mais de um modelo em execução, você pode interrompê-lo e liberar recursos da seguinte forma:

shellcURLPython

xinference terminate --model-uid "qwen2.5-instruct"

Implantação do Xinference em cluster

Para implantar o Xinference em um ambiente de cluster, é necessário iniciar um nó supervisor em uma máquina e iniciar nós workers no mesmo nó ou em outros nós.

Primeiro, certifique-se de que o Xinference esteja instalado em todos os servidores de acordo com a documentação. Em seguida, siga os passos:

Iniciar o Supervisor

Execute o seguinte comando no servidor para iniciar o nó Supervisor:

xinference-supervisor -H "${supervisor_host}"

Use o IP do nó atual para substituir ${supervisor_host}.

A interface web pode ser acessada em http://${supervisor_host}:9997/ui, e a documentação da API em http://${supervisor_host}:9997/docs.

Iniciar o Worker

Execute o seguinte comando na máquina onde o worker do Xinference precisa ser iniciado:

xinference-worker -e "http://${supervisor_host}:9997" -H "${worker_host}"

Nota

É importante notar que você deve substituir ${worker_host} pelo IP do nó Worker atual.

Nota

É importante notar que, se você precisar interagir com o cluster via linha de comando, deve usar o parâmetro -e ou --endpoint para especificar o endereço do supervisor, por exemplo:

xinference launch -n qwen2.5-instruct -s 0_5 -f pytorch -e "http://${supervisor_host}:9997"

Use Docker para implantar o Xinference.

Execute o Xinference em um contêiner com o seguinte comando:

Em execução em uma máquina com placa de vídeo NVIDIA.

Para cuda 12.4:

docker run -e XINFERENCE_MODEL_SRC=modelscope -p 9998:9997 --gpus all xprobe/xinference:<your_version> xinference-local -H 0.0.0.0 --log-level debug

Para cuda 12.8:

Adicionado na versão v1.8.1: A versão CUDA 12.8 é experimental. Agradecemos seu feedback para melhorias.

Alterado na versão v1.16.0: A versão CUDA 12.8 foi removida na v1.16.0.

docker run -e XINFERENCE_MODEL_SRC=modelscope -p 9998:9997 --gpus all xprobe/xinference:<your_version>-cu128 xinference-local -H 0.0.0.0 --log-level debug

Para CUDA 12.9:

Adicionado na versão v1.16.0: Após o lançamento do Xinference v2.0.0, o CUDA 12.9 se tornará a versão padrão.

docker run -e XINFERENCE_MODEL_SRC=modelscope -p 9998:9997 --gpus all xprobe/xinference:<your_version>-cu129 xinference-local -H 0.0.0.0 --log-level debug

Execute em uma máquina com apenas CPU.

docker run -e XINFERENCE_MODEL_SRC=modelscope -p 9998:9997 xprobe/xinference:<your_version>-cpu xinference-local -H 0.0.0.0 --log-level debug

Substitua <your_version> pela versão do Xinference, por exemplo v0.10.3, e utilize latest para a versão mais recente.

Para mais usos do Docker, consulte uso de imagens Docker.

Mais

Parabéns! Você já dominou o uso básico do Xinference! Para ajudá-lo a usar melhor a ferramenta, abaixo estão alguns outros documentos e recursos de orientação:

• Como criar diferentes tipos de modelos com Python

• Selecionando o mecanismo de inferência correto