Use

Ejecuta Xinference localmente.

Comencemos con un modelo clásico de lenguaje grande, qwen2.5-instruct, para demostrar cómo ejecutar un modelo grande localmente con Xinference.

Después de esta guía de inicio rápido, puedes continuar aprendiendo cómo implementar Xinference en un entorno de clúster distribuido.

Iniciar el servicio local

Primero, asegúrate de tener instalado Xinference localmente siguiendo las instrucciones en este documento. Inicia el servicio local de Xinference con el siguiente comando:

shelloutput

xinference-local --host 0.0.0.0 --port 9997

Nota

Por defecto, Xinference utiliza <HOME>/.xinference como directorio principal para almacenar información necesaria, como archivos de registro y archivos de modelo, donde <HOME> es el directorio principal del usuario actual.

Puedes modificar el directorio principal configurando la variable de entorno XINFERENCE_HOME, por ejemplo:

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

¡Felicidades! Ya has iniciado el servicio Xinference en tu entorno local. Una vez que el servicio Xinference esté en funcionamiento, puedes utilizarlo de varias maneras, incluyendo el uso de la página web, comandos cURL, línea de comandos o el SDK de Python de Xinference.

Se puede acceder a la interfaz de usuario visitando http://127.0.0.1:9997/ui, y a la documentación de la API visitando http://127.0.0.1:9997/docs.

Se puede instalar mediante el siguiente comando y luego utilizar la herramienta de línea de comandos de Xinference o el código Python para su uso:

pip install xinference

La herramienta de línea de comandos es xinference. Se pueden consultar los comandos disponibles mediante el siguiente comando:

shelloutput

xinference --help

Si solo necesita instalar el SDK de Python de Xinference, puede usar el siguiente comando para instalar las dependencias mínimas. Tenga en cuenta que la versión debe coincidir con la versión del servicio Xinference.

pip install xinference-client==${SERVER_VERSION}

Sobre el motor de inferencia del modelo.

A partir de la versión v0.11.0, antes de cargar el modelo LLM, debes especificar el motor de inferencia concreto. Actualmente, Xinference es compatible con los siguientes motores de inferencia:

• vllm

• sglang

• llama.cpp

• transformers

• MLX

Para más detalles sobre estos motores de inferencia, consulte aquí.

Nota: al cargar un modelo LLM, el motor que se puede ejecutar está estrechamente relacionado con los parámetros model_format y quantization.

Xinference proporciona el comando xinference engine para ayudarte a consultar las combinaciones de parámetros relevantes.

Por ejemplo:

1. Necesito consultar las combinaciones de parámetros relacionadas con el modelo qwen-chat para determinar cómo puede ejecutarse en varios motores de inferencia.

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

1. Quiero ejecutar qwen-chat en el motor de inferencia VLLM, pero no sé qué otros parámetros cumplen con este requisito.

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

1. Quiero cargar el modelo qwen-chat en formato GGUF, necesito conocer la combinación de los parámetros restantes.

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

En resumen, en comparación con la versión anterior, al cargar el modelo LLM, es necesario pasar adicionalmente el parámetro model_engine. Puedes consultar la relación entre el motor de inferencia que deseas ejecutar y otras combinaciones de parámetros mediante el comando xinference engine.

Nota

Acerca de cuándo usar qué motor, aquí hay algunas sugerencias:

• Linux

  • Cuando sea posible, prioriza el uso de vLLM o SGLang, ya que ofrecen un mejor rendimiento.

  • Si los recursos son limitados, se puede considerar usar llama.cpp, ya que ofrece más opciones de cuantización.

  • Otros consideran usar Transformers, que soporta casi todos los modelos.

• Windows

  • Se recomienda usar WSL, en este caso elija la misma opción que en Linux.

  • Otras veces se recomienda usar llama.cpp; para modelos no compatibles, se elige usar Transformers.

• Mac

  • Cuando el modelo lo admita, se recomienda utilizar el motor MLX, ya que ofrece el mejor rendimiento.

  • En otros casos se recomienda usar llama.cpp; para modelos no compatibles, opte por usar Transformers.

qwen2.5-instruct

Ejecutemos un modelo incorporado qwen2.5-instruct. Cuando necesites ejecutar un modelo, la primera vez deberás descargar los parámetros del modelo desde HuggingFace, lo que generalmente toma entre 10 y 30 minutos dependiendo del tamaño del modelo. Una vez completada la descarga, Xinference almacenará en caché localmente, por lo que no será necesario volver a descargar el modelo al ejecutarlo nuevamente en el futuro.

Nota

Xinference también permite descargar modelos desde otras plataformas de alojamiento de modelos. Se puede especificar una variable de entorno al iniciar Xinference, por ejemplo, si se desea descargar un modelo desde ModelScope, se puede usar el siguiente comando:

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

Puede especificar el UID del modelo usando el parámetro --model-uid o -u. Si no se especifica, Xinference generará un ID aleatorio. El ID predeterminado coincide con el nombre del modelo.

shellcURLPythonoutput

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

Nota

Para ciertos motores de inferencia, como vLLM, los usuarios deben especificar parámetros relacionados con el motor al ejecutar el modelo. En este caso, basta con indicar directamente el nombre y valor del parámetro correspondiente en la línea de comandos, por ejemplo:

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

Al ejecutar el modelo, gpu_memory_utilization=0.9 se pasa al backend de vllm.

Nota

Para más técnicas sobre la carga de modelos, consulte Guía de carga de modelos.

En este punto, felicitaciones, has logrado ejecutar correctamente qwen2.5-instruct a través de Xinference. Una vez que este modelo esté en funcionamiento, podemos interactuar con él mediante la línea de comandos, cURL o 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?"
        }
    ]
  }'

Xinference proporciona una API compatible con OpenAI, por lo que el modelo ejecutado por Xinference puede ser utilizado como un reemplazo local de OpenAI. Por ejemplo:

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)

Las siguientes son las API de OpenAI compatibles:

• Generación de diálogo：https://platform.openai.com/docs/api-reference/chat

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

• Generación de vectores: https://platform.openai.com/docs/api-reference/embeddings

Xinference también admite la llamada a la API de Anthropic a través de la URL base http://127.0.0.1:9997/anthropic, y puedes usar Xinference en entornos como Claude Code. Para más detalles, consulta cliente Anthropic.

Modelos de gestión

Además de iniciar modelos, Xinference proporciona la capacidad de gestionar todo el ciclo de vida de los modelos. De igual manera, puedes usar la línea de comandos, cURL y código Python para la gestión:

Puede enumerar todos los modelos del tipo especificado compatibles con Xinference:

shellcURLPython

xinference registrations -t LLM

El siguiente comando puede listar todos los modelos en ejecución:

shellcURLPython

xinference list

Cuando no necesites un modelo en ejecución, puedes detenerlo y liberar recursos de la siguiente manera:

shellcURLPython

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

Despliegue de Xinference en clúster

Para implementar Xinference en un entorno de clúster, es necesario iniciar un nodo supervisor en una máquina y nodos trabajadores en la misma u otras máquinas.

Primero, de acuerdo con la documentación, asegúrate de que Xinference esté instalado en todos los servidores. Luego sigue los pasos:

Iniciar Supervisor

Ejecuta el siguiente comando en el servidor para iniciar el nodo Supervisor:

xinference-supervisor -H "${supervisor_host}"

Reemplace ${supervisor_host} con la IP del nodo actual.

Se puede acceder a la interfaz web en http://${supervisor_host}:9997/ui y a la documentación de la API en http://${supervisor_host}:9997/docs.

Iniciar Worker

Ejecute el siguiente comando en la máquina donde necesita iniciar el worker de Xinference:

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

Nota

Ten en cuenta que debes utilizar la IP del nodo Worker actual para reemplazar ${worker_host}.

Nota

Es importante tener en cuenta que, si necesitas interactuar con el clúster a través de la línea de comandos, debes especificar la dirección del supervisor mediante el parámetro -e o --endpoint, por ejemplo:

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

Despliegue de Xinference usando Docker

Usa el siguiente comando para ejecutar Xinference en el contenedor:

Ejecutar en una máquina con una tarjeta gráfica 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:

Added in version v1.8.1: La versión CUDA 12.8 es experimental, agradecemos sus comentarios para mejorarla.

Distinto en la versión v1.16.0: La versión CUDA 12.8 se ha eliminado en 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:

Added in version v1.16.0: Tras el lanzamiento de Xinference v2.0.0, CUDA 12.9 se convertirá en la versión predeterminada.

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

Ejecutar en una máquina con solo 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

Reemplaza <your_version> por la versión de Xinference, por ejemplo v0.10.3. Puedes usar latest para la versión más reciente.

Para más información sobre el uso de Docker, consulte la imagen de Docker.

Más

¡Felicidades! ¡Ya has dominado inicialmente el uso de Xinference! Para ayudarte a utilizar mejor la herramienta, a continuación se presentan otros documentos y recursos de guía:

• Cómo usar Python para crear diferentes tipos de modelos

• Selección del motor de razonamiento correcto