Model Virtual Environment#

Added in version v1.5.0.

Contexto#

Algunos modelos dejan de recibir mantenimiento tras su publicación, y las versiones de las bibliotecas de las que dependen se mantienen en un estado relativamente antiguo. Por ejemplo, el modelo GOT-OCR2 sigue dependiendo de transformers 4.37.2. Si se actualiza esta biblioteca a una versión nueva, el modelo no funcionará correctamente; mientras que muchos modelos nuevos requieren la versión más reciente de transformers. Esta diferencia de versiones puede provocar conflictos de dependencias.

Solución#

Para solucionar este problema, hemos introducido la función Entorno virtual del modelo.

Instale las dependencias necesarias para esta función mediante el siguiente comando:

# all
pip install 'xinference[all]'
# or virtualenv
pip install 'xinference[virtualenv]'

Habilite esta función configurando la variable de entorno XINFERENCE_ENABLE_VIRTUAL_ENV=1.

Ejemplo de uso:

# For command line
XINFERENCE_ENABLE_VIRTUAL_ENV=1 xinference-local ...

# For Docker
docker run -e XINFERENCE_ENABLE_VIRTUAL_ENV=1 ...

Advertencia

Esta función requiere conexión a internet, o utilizar un servicio de espejo PyPI autogestionado.

Xinference heredará la configuración actual de pip de forma predeterminada.

Nota

NOTA: Al iniciar el motor del modelo vLLM/SgLang en un entorno virtual, si se encuentra un error de cuDNN, se puede configurar:

export LD_LIBRARY_PATH=$CONDA_PREFIX/lib/python3.12/site-packages/nvidia/cudnn/lib:$LD_LIBRARY_PATH
export LD_LIBRARY_PATH=$CONDA_PREFIX/lib/python3.12/site-packages/nvidia/cusparselt/lib:$LD_LIBRARY_PATH
export LD_LIBRARY_PATH=$CONDA_PREFIX/lib/python3.12/site-packages/nvidia/nccl/lib:$LD_LIBRARY_PATH

Distinto en la versión v2.0.0: A partir de Xinference v2.0, la función de entorno virtual del modelo está habilitada de forma predeterminada (es decir, el valor predeterminado de XINFERENCE_ENABLE_VIRTUAL_ENV es 1).

Para deshabilitar globalmente esta función, configure XINFERENCE_ENABLE_VIRTUAL_ENV=0 al iniciar Xinference.

Una vez habilitada esta función, Xinference creará automáticamente un entorno virtual dedicado para cada modelo al cargarlo e instalará las dependencias correspondientes en dicho entorno. Esto evita conflictos de dependencias entre modelos y garantiza que cada modelo se ejecute de forma independiente en entornos aislados.

Gestión de entornos virtuales (v2.0)#

Cambio global#

A partir de la versión v2.0, el entorno virtual está habilitado de forma predeterminada. Aún puede anular esta opción mediante la configuración global:

# Enable globally (default)
XINFERENCE_ENABLE_VIRTUAL_ENV=1 xinference-local -H 0.0.0.0 -p 9997

# Disable globally
XINFERENCE_ENABLE_VIRTUAL_ENV=0 xinference-local -H 0.0.0.0 -p 9997

Anulación por modelo al iniciar#

Al iniciar el modelo, puede sobrescribir la configuración global:

# Force enable for this model
xinference launch -n qwen2.5-instruct --model-engine transformers --enable-virtual-env

# Force disable for this model
xinference launch -n qwen2.5-instruct --model-engine transformers --disable-virtual-env

Agregar o sobrescribir paquetes al inicio#

En la línea de comandos, use --virtual-env-package o -vp para especificar una sola versión de paquete.

xinference launch -n qwen2.5-instruct --model-engine transformers \
  --virtual-env-package transformers==4.46.3 \
  --virtual-env-package accelerate==0.33.0

Si el paquete especificado ya existe en la lista de paquetes del entorno virtual predeterminado del modelo, la versión que usted especifique sobrescribirá la versión predeterminada, en lugar de agregarse a la lista.

Ubicación de almacenamiento#

Por defecto, el entorno virtual del modelo se almacena en la siguiente ruta.

  • Antes de v1.6.0: XINFERENCE_HOME / virtualenv / {model_name}

  • De v1.6.0 a v1.13.0: XINFERENCE_HOME / virtualenv / v2 / {model_name}

  • Desde v1.14.0: XINFERENCE_HOME / virtualenv / v3 / {model_name} / {python_version}

  • Desde v2.0: XINFERENCE_HOME / virtualenv / v4 / {model_name} / {model_engine} / {python_version}

Saltar bibliotecas ya instaladas#

Added in version v1.8.1: Esta funcionalidad requiere xoscar >= 0.7.12, que es la versión mínima de Xoscar requerida por Xinference v1.8.1.

xinference utiliza la herramienta uv para crear un entorno virtual y establece system site-packages de Python actual como entorno base. Por defecto, uv no verifica si los paquetes ya existen en el entorno del sistema, sino que reinstala todas las dependencias en el entorno virtual. Este enfoque ofrece un mejor aislamiento de los paquetes del sistema, pero puede provocar instalaciones duplicadas, un mayor tiempo de inicialización y un mayor uso de disco.

A partir de v1.8.1, se proporciona una función experimental: al configurar la variable de entorno XINFERENCE_VIRTUAL_ENV_SKIP_INSTALLED=1, uv omitirá los paquetes ya existentes en los site-packages del sistema.

Distinto en la versión v2.0: Esta función está habilitada de forma predeterminada en la versión v2.0. Para deshabilitarla, configure XINFERENCE_VIRTUAL_ENV_SKIP_INSTALLED=0.

Ventaja#

  • Evite la instalación repetida de dependencias grandes (por ejemplo, torch + CUDA ).

  • Acelera la velocidad de creación del entorno virtual.

  • Reduzca el uso de espacio en disco.

Usar#

# Enable experimental feature

# For command line
XINFERENCE_ENABLE_VIRTUAL_ENV=1 XINFERENCE_VIRTUAL_ENV_SKIP_INSTALLED=1 xinference-local ...
# For docker
docker run -e XINFERENCE_ENABLE_VIRTUAL_ENV=1 -e XINFERENCE_VIRTUAL_ENV_SKIP_INSTALLED=1 ...

Comparación de rendimiento#

Con el modelo CosyVoice 0.5B como ejemplo:

Cuando esta función no está activada:

Installed 98 packages in 187ms
 + aiohappyeyeballs==2.6.1
 + aiohttp==3.12.13
 ...
 + torch==2.7.1
 ...
 + yarl==1.20.1
 + zipp==3.23.0

Después de activar esta función:

Installed 7 packages in 12ms
 + diffusers==0.29.0
 + hf-xet==1.1.5
 + huggingface-hub==0.33.2
 + importlib-metadata==8.7.0
 + pillow==11.3.0
 + typing-extensions==4.14.0
 + urllib3==2.5.0

Carga del modelo: activar el entorno virtual y personalizar dependencias#

Added in version v1.8.1.

A partir de v1.8.1, admitimos la carga de entornos virtuales para modelos individuales y la anulación de la configuración predeterminada del modelo con dependencias de paquetes personalizadas.

Modelo de espacio virtual del interruptor#

Al cargar el modelo, se puede especificar si se habilita el entorno virtual del modelo. Si no se especifica, por defecto se sigue la configuración de la variable de entorno.

En la interfaz web, se puede activar o desactivar esta función mediante un interruptor de configuración opcional.

actor

Al cargar desde la línea de comandos, use la opción --enable-virtual-env para habilitar el entorno virtual y la opción --disable-virtual-env para deshabilitar el entorno virtual.

Ejemplo de uso:

xinference launch xxx --enable-virtual-env

Configurar dependencias del paquete del entorno virtual#

Para los modelos compatibles, Xinference ya ha definido las dependencias de paquetes y los requisitos de versión en el entorno virtual. Sin embargo, si es necesario especificar una versión concreta o instalar dependencias adicionales, se pueden proporcionar manualmente al cargar el modelo.

En la interfaz web, se puede hacer clic en el icono de signo más en la misma ubicación que el interruptor del entorno virtual para agregar dependencias personalizadas.

En la línea de comandos, use --virtual-env-package o -vp para especificar una versión de paquete individual.

Ejemplo de uso:

xinference launch xxx --virtual-env-package transformers==4.54.0

Además de la forma convencional de especificar dependencias de paquetes (como transformers==xxx), Xinference también admite algunas sintaxis extendidas.

  • #system_xxx#: usa la misma versión que los paquetes del sistema, por ejemplo #system_numpy#, para asegurar que la versión del paquete instalado coincida con la versión de numpy en los paquetes del sistema y evitar conflictos de dependencias.

Gestión de entornos virtuales#

Added in version v1.14.0.

Xinference ofrece funciones completas de gestión de entornos virtuales, permitiéndole crear entornos Python independientes para cada modelo, satisfaciendo necesidades específicas de dependencias de paquetes.

actoractor

funcionalidades principales#

Soporte para múltiples versiones de Python: Cada modelo puede tener entornos virtuales con diferentes versiones de Python (por ejemplo, Python 3.10.18, 3.11.5), logrando compatibilidad con los requisitos de varios modelos.

Aislamiento de dependencias: Cada entorno virtual contiene su propio conjunto independiente de paquetes, evitando conflictos de dependencias entre diferentes modelos.

Operaciones de gestión#

Listar entornos virtuales: Ver todos los entornos virtuales en el clúster, compatible con filtrado por nombre de modelo o dirección IP del nodo de trabajo.

Crear entorno: Se crea automáticamente al iniciar el modelo con enable_virtual_env=true. El sistema detecta la versión actual de Python y crea un entorno independiente que contiene los paquetes necesarios.

Eliminar entorno: se puede eliminar un entorno virtual específico por nombre del modelo y versión opcional de Python, o eliminar todos los entornos de un modelo.

Formato JSON de ModelHub (aplicable a modelos Xinference)#

Si planeas agregar el modelo al Model Hub de Xinference, define un bloque virtualenv en el JSON del modelo. Desde v2.0 (flujo v4), se recomienda usar marcadores de detección de motor para que un solo archivo JSON cubra múltiples motores.

Regla importante: si el nuevo modelo es compatible con un motor específico, debe incluir al menos una entrada de paquete de ese motor en virtualenv.packages, con una marca adicional (por ejemplo, #engine# == "vllm"). Cuando el entorno virtual está activado, la verificación de disponibilidad del motor depende de estas marcas para su validación.

{
  "virtualenv": {
    "packages": [
      "#transformers_dependencies# ; #engine# == \"transformers\"",
      "#vllm_dependencies# ; #engine# == \"vllm\"",
      "#sglang_dependencies# ; #engine# == \"sglang\"",
      "#llama_cpp_dependencies# ; #engine# == \"llama.cpp\"",
      "#mlx_dependencies# ; #engine# == \"mlx\"",
      "#system_numpy# ; #engine# == \"vllm\""
    ]
  }
}

  • packages (obligatorio): Lista de cadenas o marcadores de requisitos de pip.

  • inherit_pip_config (valor predeterminado: true): Si existe un archivo de configuración de pip del sistema, hereda sus ajustes.

  • index_url / extra_index_url / find_links / trusted_host : control de índices y espejos de pip.

  • index_strategy ：pasado al instalador del entorno virtual (utilizado por algunos motores).

  • no_build_isolation ：Interruptor de aislamiento de construcción de pip para manejar construcciones complejas.

Usar inyección de valores predeterminados del motor con marcadores de posición de paquete:

  • #vllm_dependencies#

  • #sglang_dependencies#

  • #mlx_dependencies#

  • #transformers_dependencies#

  • #llama_cpp_dependencies#

  • #diffusers_dependencies#

  • #sentence_transformers_dependencies#

Utilice #engine# o #model_engine# para la comparación (distingue entre mayúsculas y minúsculas). Los valores del motor se pasan internamente en minúsculas, por lo que se recomienda usar valores en minúsculas, como #engine# == "vllm" o #engine# == "transformers".