Model virtual environment#

Adicionado na versão v1.5.0.

fundo#

Alguns modelos, após o lançamento, não recebem mais manutenção, e as versões das bibliotecas das quais dependem permanecem desatualizadas. Por exemplo, o modelo GOT-OCR2 ainda depende do transformers 4.37.2. Se essa biblioteca for atualizada para uma versão mais recente, o modelo não funcionará corretamente; no entanto, muitos modelos novos exigem a versão mais recente do transformers. Essa diferença de versões pode causar conflitos de dependência.

Solução#

Para resolver este problema, introduzimos o recurso de Ambiente Virtual de Modelo.

Instale as dependências necessárias para esta função através do seguinte comando:

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

Ative esse recurso configurando a variável de ambiente XINFERENCE_ENABLE_VIRTUAL_ENV=1.

Exemplo de uso:

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

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

Aviso

Essa funcionalidade requer conexão com a internet ou o uso de um serviço de espelho PyPI próprio.

Xinference herda a configuração atual do pip por padrão.

Nota

Nota: ao iniciar o modelo de engine vLLM/SgLang em um ambiente virtual, se encontrar um erro cuDNN, é possível 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

Alterado na versão v2.0.0: A partir do Xinference v2.0, a funcionalidade de ambiente virtual do modelo é habilitada por padrão (ou seja, o valor padrão de XINFERENCE_ENABLE_VIRTUAL_ENV é 1).

Para desabilitar globalmente essa funcionalidade, defina XINFERENCE_ENABLE_VIRTUAL_ENV=0 ao iniciar o Xinference.

Quando essa função é ativada, o Xinference cria automaticamente um ambiente virtual exclusivo para o modelo ao carregá-lo e instala as dependências correspondentes nesse ambiente. Isso evita conflitos de dependência entre modelos, garantindo que cada modelo seja executado de forma independente em ambientes isolados.

Gerenciamento de ambiente virtual (v2.0)#

Alternância global#

A partir da versão v2.0, o ambiente virtual está habilitado por padrão. Você ainda pode substituir esta opção através das configurações globais:

# 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

Substituir por modelo na inicialização#

Ao iniciar o modelo, você pode substituir as configurações globais:

# 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

Adicionar ou substituir pacotes na inicialização#

Na linha de comando, use --virtual-env-package ou -vp para especificar a versão de um único pacote.

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

Se o pacote especificado já existir na lista de pacotes do ambiente virtual padrão do modelo, a versão que você especificar substituirá a versão padrão, em vez de ser adicionada à lista.

Local de armazenamento#

Por padrão, o ambiente virtual do modelo é armazenado no seguinte caminho:

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

  • Da v1.6.0 à v1.13.0: XINFERENCE_HOME / virtualenv / v2 / {model_name}

  • A partir da v1.14.0: XINFERENCE_HOME / virtualenv / v3 / {model_name} / {python_version}

  • A partir da v2.0: XINFERENCE_HOME / virtualenv / v4 / {model_name} / {model_engine} / {python_version}

Pular bibliotecas já instaladas#

Adicionado na versão v1.8.1: Esta funcionalidade requer xoscar >= 0.7.12, que é a versão mínima do Xoscar necessária para o Xinference v1.8.1.

O xinference usa a ferramenta uv para criar um ambiente virtual e define o system site-packages do Python atual como ambiente base. Por padrão, o uv não verifica se pacotes já existem no ambiente do sistema, mas reinstala todas as dependências no ambiente virtual. Esse método permite um melhor isolamento dos pacotes do sistema, mas pode resultar em instalações duplicadas, aumento do tempo de inicialização e maior uso de disco.

A partir da v1.8.1, é fornecida uma funcionalidade experimental: ao definir a variável de ambiente XINFERENCE_VIRTUAL_ENV_SKIP_INSTALLED=1, o uv ignorará pacotes já existentes nos site-packages do sistema.

Alterado na versão v2.0: Esta funcionalidade está habilitada por padrão na versão v2.0. Para desabilitá-la, defina XINFERENCE_VIRTUAL_ENV_SKIP_INSTALLED=0.

vantagem#

  • Evite instalar dependências grandes repetidamente (por exemplo, torch + CUDA).

  • Acelere a velocidade de criação do ambiente virtual.

  • Reduza a ocupação de espaço em 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 ...

Comparação de desempenho#

Tomando o modelo CosyVoice 0.5B como exemplo:

Quando esta função não está ativada:

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

Após ativar esta função:

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

Carregamento de modelo: ativar ambiente virtual e personalizar dependências#

Adicionado na versão v1.8.1.

A partir da v1.8.1, oferecemos suporte para carregar um ambiente virtual de alternância para um único modelo e substituir as configurações padrão do modelo com dependências de pacotes personalizadas.

Comutador de espaço virtual do modelo#

Ao carregar o modelo, é possível especificar se o ambiente virtual do modelo deve ser ativado. Se não especificado, o comportamento padrão segue a configuração da variável de ambiente.

Na interface Web, é possível ativar ou desativar essa função por meio de uma chave de configuração opcional.

actor

Ao carregar pela linha de comando, use a opção --enable-virtual-env para habilitar o ambiente virtual e a opção --disable-virtual-env para desabilitar o ambiente virtual.

Exemplo de uso:

xinference launch xxx --enable-virtual-env

Defina as dependências de pacotes do ambiente virtual.#

Para modelos suportados, o Xinference já define as dependências de pacotes e requisitos de versão no ambiente virtual. No entanto, se for necessário especificar uma versão específica ou instalar dependências adicionais, isso pode ser feito manualmente ao carregar o modelo.

Na Web UI, é possível clicar no ícone de adição no mesmo local do interruptor do ambiente virtual para adicionar dependências personalizadas.

Na linha de comando, use --virtual-env-package ou -vp para especificar a versão de um único pacote.

Exemplo de uso:

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

Além da forma convencional de especificar dependências de pacotes (como transformers==xxx), o Xinference também suporta algumas sintaxes estendidas.

  • #system_xxx#: Use a versão idêntica à dos pacotes do sistema (site packages), por exemplo #system_numpy#, para garantir que a versão do pacote instalado corresponda à versão do numpy nos site packages do sistema, prevenindo conflitos de dependência.

Gerenciamento de ambiente virtual#

Adicionado na versão v1.14.0.

O Xinference oferece funcionalidades abrangentes de gerenciamento de ambientes virtuais, permitindo que você crie ambientes Python independentes para cada modelo, atendendo às necessidades específicas de dependências de pacotes.

actoractor

Funcionalidades principais#

Suporte a Múltiplas Versões do Python: Cada modelo pode ter ambientes virtuais com diferentes versões do Python (por exemplo, Python 3.10.18, 3.11.5), garantindo compatibilidade com os requisitos de diversos modelos.

Isolamento de dependências: Cada ambiente virtual contém seu próprio conjunto independente de pacotes, prevenindo conflitos de dependências entre diferentes modelos.

Operações de gerenciamento#

Listar Ambientes Virtuais: Exibe todos os ambientes virtuais no cluster, com suporte para filtragem por nome do modelo ou endereço IP do nó de trabalho.

Criação de ambiente: Criado automaticamente ao iniciar o modelo com enable_virtual_env=true. O sistema detectará a versão atual do Python e criará um ambiente isolado contendo os pacotes necessários.

Exclusão de ambiente : Permite remover um ambiente virtual específico pelo nome do modelo e opcionalmente pela versão do Python, ou remover todos os ambientes de um modelo.

Formato JSON do ModelHub (aplicável ao modelo Xinference)#

Se você planeja adicionar o modelo ao Model Hub do Xinference, defina um bloco virtualenv no JSON do modelo. A partir da v2.0 (fluxo v4), é recomendado o uso de marcação com reconhecimento de engine, permitindo que um único arquivo JSON cubra vários mecanismos.

Regra importante: se o novo modelo suportar um mecanismo específico, deve incluir pelo menos uma entrada de pacote desse mecanismo em virtualenv.packages, com uma tag adicional (por exemplo, #engine# == "vllm"). Quando o ambiente virtual estiver ativado, a verificação de disponibilidade do mecanismo depende dessas tags para validação.

{
  "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 (obrigatório): uma lista de strings de requisitos pip ou tokens.

  • inherit_pip_config (valor padrão true): se existir um arquivo de configuração do pip do sistema, herda suas configurações.

  • index_url / extra_index_url / find_links / trusted_host : controle de índice e espelho do pip.

  • index_strategy : passado para o instalador do ambiente virtual (usado por alguns mecanismos).

  • no_build_isolation: é uma chave de isolamento de build do pip usada para lidar com builds complexos.

Usar o placeholder injetado pelo mecanismo de valor padrão do pacote:

  • #vllm_dependencies#

  • #sglang_dependencies#

  • #mlx_dependencies#

  • #transformers_dependencies#

  • #llama_cpp_dependencies#

  • #diffusers_dependencies#

  • #sentence_transformers_dependencies#

Use #engine# ou #model_engine# para comparação (sensível a maiúsculas/minúsculas). Os valores do mecanismo são passados internamente em letras minúsculas, portanto recomenda-se usar valores em minúsculas, como #engine# == "vllm" ou #engine# == "transformers".