模型虚拟环境#

Added in version v1.5.0.

背景#

一些模型在发布后不再维护，其依赖的库版本也保持在较旧的状态。例如，GOT-OCR2 模型仍依赖于 transformers 4.37.2。如果将该库升级为新版本，模型将无法正常运行；而许多新模型又需要最新版本的 transformers。这种版本差异会导致依赖冲突。

解决方案#

为了解决这个问题，我们引入了 模型虚拟环境 功能。

通过以下命令安装该功能所需的依赖

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

通过设置环境变量 XINFERENCE_ENABLE_VIRTUAL_ENV=1 启用该功能。

使用示例：

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

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

警告

该功能需要联网，或使用自建的 PyPI 镜像服务。

Xinference 默认会继承当前 pip 的配置。

备注

注意：在虚拟环境中启动vLLM/SgLang引擎模型时，若遇到cuDNN错误，可设置：

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

在 v2.0.0 版本发生变更: 从 Xinference v2.0 开始，模型虚拟环境功能默认启用（即 XINFERENCE_ENABLE_VIRTUAL_ENV 默认值为 1 ）。

要全局禁用该功能，请在启动Xinference时设置 XINFERENCE_ENABLE_VIRTUAL_ENV=0 。

启用该功能后，Xinference 会在加载模型时自动为其创建专属的虚拟环境，并在其中安装对应依赖。这可避免模型之间的依赖冲突，确保各模型在相互隔离的环境中独立运行。

虚拟环境管理（v2.0）#

全局切换#

从v2.0版本开始，虚拟环境默认处于启用状态。您仍可通过全局设置覆盖此选项：

# 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

启动时按模型覆盖#

在启动模型时，您可以覆盖全局设置：

# 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

在启动时添加或覆盖包#

命令行中，使用 --virtual-env-package 或 -vp 来指定单个包版本。

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

若指定的软件包已在模型的默认虚拟环境软件包列表中存在，则您指定的版本将覆盖默认版本，而非追加至列表中。

存储位置#

默认情况下，模型的虚拟环境存储在以下路径

  • 在 v1.6.0 之前：XINFERENCE_HOME / virtualenv / {model_name}

  • 从 v1.6.0 到 v1.13.0：XINFERENCE_HOME / virtualenv / v2 / {model_name}

  • 从 v1.14.0 开始：XINFERENCE_HOME / virtualenv / v3 / {model_name} / {python_version}

  • 自 v2.0 起：XINFERENCE_HOME / virtualenv / v4 / {model_name} / {model_engine} / {python_version}

跳过已安装的库#

Added in version v1.8.1: 此功能要求 xoscar >= 0.7.12，这是 Xinference v1.8.1 需要的最低 Xoscar 版本。

xinference 使用 uv 工具创建虚拟环境，并将当前 Python 的 system site-packages 设置为基础环境。默认情况下，uv 不会检查系统环境中是否已有包，而是会在虚拟环境中重新安装所有依赖。这种方式可以更好地与系统包隔离，但可能导致重复安装、初始化时间变长以及磁盘占用增加。

从 v1.8.1 开始，提供了一个 实验功能：通过设置环境变量 XINFERENCE_VIRTUAL_ENV_SKIP_INSTALLED=1，uv 将会 跳过系统 site-packages 中已存在的包。

在 v2.0 版本发生变更: 此功能在 v2.0 版本中默认启用。若需禁用，请设置 XINFERENCE_VIRTUAL_ENV_SKIP_INSTALLED=0 。

优势#

  • 避免重复安装大型依赖（例如 torch + CUDA ）。

  • 加快虚拟环境创建速度。

  • 减少磁盘空间占用。

使用#

# 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 ...

性能对比#

以 CosyVoice 0.5B 模型为例：

未开启该功能时:

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

开启该功能后:

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

模型加载：开关虚拟环境并自定义依赖#

Added in version v1.8.1.

从 v1.8.1 开始，我们支持对单个模型加载开关虚拟环境，并用自定义包依赖覆盖模型的默认设置。

开关模型虚拟空间#

加载模型时，可以指定是否启用模型的虚拟环境。如果未指定，则默认遵循环境变量的配置。

在 Web UI 中，可以通过可选设置开关打开或关闭该功能。

actor

命令行加载时，使用 --enable-virtual-env 选项启用虚拟环境，使用 --disable-virtual-env 选项禁用虚拟环境。

使用示例：

xinference launch xxx --enable-virtual-env

设置虚拟环境包依赖#

对于支持的模型，Xinference 已经在虚拟环境中定义了包依赖和版本要求。但如果需要指定特定版本或安装额外依赖，可以在加载模型时手动提供。

在 Web UI 中，可以在虚拟环境开关同一位置点击加号图标来添加自定义依赖。

命令行中，使用 --virtual-env-package 或 -vp 来指定单个包版本。

使用示例：

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

除了常规的包依赖指定方式（如 transformers==xxx），Xinference 还支持一些扩展语法。

  • #system_xxx#：使用与系统 site packages 相同的版本，例如 #system_numpy#，确保安装的包版本与系统 site packages 中的 numpy 版本一致，防止依赖冲突。

虚拟环境管理#

Added in version v1.14.0.

Xinference 提供全面的虚拟环境管理功能，允许您为每个模型创建独立的 Python 环境，满足特定的包依赖需求。

actoractor

核心功能#

多 Python 版本支持 : 每个模型可以拥有不同 Python 版本的虚拟环境（例如 Python 3.10.18、3.11.5），实现与各种模型要求的兼容性。

依赖隔离 : 每个虚拟环境包含自己独立的包集合，防止不同模型之间的依赖冲突。

管理操作#

列出虚拟环境 : 查看集群中的所有虚拟环境，支持按模型名称或工作节点 IP 地址过滤。

创建环境 : 当使用 enable_virtual_env=true 启动模型时自动创建。系统会检测当前的 Python 版本并创建包含所需包的独立环境。

删除环境 : 可按模型名称和可选的 Python 版本删除特定虚拟环境，或删除模型的所有环境。

ModelHub JSON 格式（适用于 Xinference 模型）#

若计划将模型添加至Xinference的Model Hub，请在模型JSON中定义一个``virtualenv``块。自v2.0（v4流程）起， 建议使用引擎感知标记 ，以便单个JSON文件覆盖多个引擎。

重要规则：若新模型支持特定引擎，则 必须 在 virtualenv.packages 中至少包含该引擎的一个包条目，并附加标记（例如 #engine# == "vllm" ）。当虚拟环境启用时，引擎可用性检查依赖这些标记进行验证。

{
  "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 (required): list of pip requirement strings or markers.

  • inherit_pip_config (default true): inherit system pip configuration if present.

  • index_url / extra_index_url / find_links / trusted_host: pip index and mirror controls.

  • index_strategy: passed through to the virtualenv installer (used by some engines).

  • no_build_isolation: pip build isolation switch for tricky builds.

使用包裹的占位符注入引擎默认值：

  • #vllm_dependencies#

  • #sglang_dependencies#

  • #mlx_dependencies#

  • #transformers_dependencies#

  • #llama_cpp_dependencies#

  • #diffusers_dependencies#

  • #sentence_transformers_dependencies#

标记使用 #engine# 或 #model_engine# 进行比较（区分大小写）。引擎值在内部以小写形式传递，因此建议使用小写值，例如 #engine# == "vllm" 或 #engine# == "transformers" 。