模型虚拟空间#

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 的配置。

备注

模型虚拟空间功能默认处于关闭状态（即 XINFERENCE_ENABLE_VIRTUAL_ENV 的默认值为 0）。

该功能将在 Xinference v2.0.0 起默认开启。

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

支持的模型#

当前，该功能支持以下模型：

存储位置#

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

实验功能#

跳过已安装的库#

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.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 版本一致，防止依赖冲突。