模型虛擬環境#

在 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}

跳過已安裝的函式庫#

在 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

模型載入：切換虛擬環境並自訂相依套件#

在 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 版本一致，以防止相依性衝突。

虛擬環境管理#

在 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``（必填）：pip 要求字串或標記的清單。

  • inherit_pip_config``（預設值為 ``true）：若存在系統 pip 設定檔，則繼承其設定。

  • index_url / extra_index_url / find_links / trusted_host : pip 索引與映像檔控制。

  • index_strategy ：傳遞給虛擬環境安裝程式（由某些引擎使用）。

  • no_build_isolation ：用於處理複雜構建的 pip 構建隔離開關。

使用包裹的佔位符注入引擎預設值：

  • #vllm_dependencies#

  • #sglang_dependencies#

  • #mlx_dependencies#

  • #transformers_dependencies#

  • #llama_cpp_dependencies#

  • #diffusers_dependencies#

  • #sentence_transformers_dependencies#

標記使用 #engine# 或 #model_engine# 進行比較（區分大小寫）。引擎值在內部以小寫形式傳遞，因此建議使用小寫值，例如 #engine# == "vllm" 或 #engine# == "transformers"。