故障排除#

沒有 huggingface 倉庫權限#

獲取模型時，有時候會遇到權限問題。比如在獲取 llama2 模型時可能會有以下提示：

Cannot access gated repo for url https://huggingface.co/api/models/meta-llama/Llama-2-7b-hf.
Repo model meta-llama/Llama-2-7b-hf is gated. You must be authenticated to access it.

这种情况通常是缺少 Hugging Face 倉庫的權限，或者是沒有設定 Hugging Face Token。可以按照以下方式解決這個問題。

申請 Huggingface 倉庫權限#

想要取得存取權限，請開啟對應的 huggingface 倉庫，同意其條款與注意事項。以 llama2 為例，可以開啟以下連結進行申請：https://huggingface.co/meta-llama/Llama-2-7b-hf.

設定存取 huggingface 憑證#

可以在 huggingface 頁面找到憑證，https://huggingface.co/settings/tokens.

可以透過設定環境變數來設定存取憑證，export HUGGING_FACE_HUB_TOKEN=your_token_here。

NVIDIA 驅動與 PyTorch 版本不匹配#

如果你在使用NVIDIA顯示卡，可能會遇到以下錯誤：

UserWarning: CUDA initialization: The NVIDIA driver on your system is too old
(found version 10010). Please update your GPU driver by downloading and installi
ng a new version from the URL: http://www.nvidia.com/Download/index.aspx Alterna
tively, go to: https://pytorch.org to install a PyTorch version that has been co
mpiled with your version of the CUDA driver. (Triggered internally at  ..\c10\cu
da\CUDAFunctions.cpp:112.)

這種情況一般是 CUDA 的版本和 Pytorch 版本不相容導致的。

可以到 https://pytorch.org 官網安裝和 CUDA 對應的預編譯版本的 PyTorch。同時，請檢查安裝的 CUDA 版本不要小於 11.8，最好版本在 11.8 到 12.1 之間。

例如你的 CUDA 版本是 11.8，可以使用以下指令安裝對應的 PyTorch：

pip install torch==2.0.1+cu118

外部系統無法透過 <IP>:9997 存取 Xinference 服務#

在啟動 Xinference 時記得要加上 -H 0.0.0.0 參數:

xinference-local -H 0.0.0.0

那麼 Xinference 服務將監聽所有網路介面（而不僅限於 127.0.0.1 或 localhost）。

如果使用的是 Docker 映像，請在 Docker 運行命令中加上 -p <PORT>:9997，你就可以透過本地機器的 <IP>:<PORT> 進行存取。

啟動內建模型需要很長時間，模型有時下載失敗#

Xinference 預設使用 HuggingFace 作為模型來源。如果你的機器在中國大陸，使用內建模型可能會遇到存取問題。

要解決這個問題，可以在啟動 Xinference 時添加環境變數 XINFERENCE_MODEL_SRC=modelscope，將模型來源更改為 ModelScope，在中國大陸下載速度更快。

如果你用 Docker 啟動 Xinference，可以在 Docker 命令中包含 -e XINFERENCE_MODEL_SRC=modelscope 選項。

使用官方 Docker 映像時，RayWorkerVllm 因 OOM 而死亡，導致模型無法載入#

Docker 的 --shm-size 參數可以用來設定共享記憶體的大小。共享記憶體(/dev/shm)的預設大小是 64MB，對於 vLLM 後端來說可能不夠。

你可以透過設定參數 --shm-size 來增加它的大小：

docker run --shm-size=128g ...

載入 LLM 模型時提示缺少 model_engine 參數#

自 v0.11.0 版本開始，載入 LLM 模型時需要傳入額外參數 model_engine 。具體資訊請參考 這裡 。

解決 MKL 執行緒層衝突#

在啟動 Xinference 伺服器時，如果遇到錯誤：ValueError: Model architectures ['Qwen2ForCausalLM'] failed to be inspected. . Please check the logs for more details.

日誌中顯示的根本原因是：

Error: mkl-service + Intel(R) MKL: MKL_THREADING_LAYER=INTEL is incompatible with libgomp-a34b3233.so.1 library.
Try to import numpy first or set the threading layer accordingly. Set MKL_SERVICE_FORCE_INTEL to force it.

這通常是因為你的 NumPy 是透過 conda 安裝的，而 conda 的 NumPy 是使用 Intel MKL 最佳化構建的，這導致它與環境中已載入的 GNU OpenMP 庫（libgomp）產生衝突。

解決方案 1：重寫執行緒層#

設定 MKL_THREADING_LAYER=GNU 可以強制 Intel 數學核心庫（MKL）使用 GNU 的 OpenMP 實現：

MKL_THREADING_LAYER=GNU xinference-local

解決方案 2：使用 pip 重新安裝 NumPy#

卸載 conda 安裝的 numpy，然後使用 pip 重新安裝。

pip uninstall -y numpy && pip install numpy
#Or just --force-reinstall
pip install --force-reinstall numpy

配置 PyPI 鏡像以加快軟體套件安裝速度#

如果你在中國大陸，使用 PyPI 鏡像可以顯著加快軟體套件的安裝速度。以下是一些常用的鏡像源：

  • 清華大學鏡像：https://pypi.tuna.tsinghua.edu.cn/simple

  • 阿里雲鏡像：https://mirrors.aliyun.com/pypi/simple/

  • 騰訊雲鏡像：https://mirrors.cloud.tencent.com/pypi/simple

但請注意，某些映像源上可能缺少部分軟體套件。例如，如果你僅使用阿里雲映像安裝 xinference[audio]，安裝可能會失敗。

這是因為 MeloTTS 所依賴的 num2words 軟體套件在阿里雲鏡像上不可用。因此，在執行 pip install xinference[audio] 時，可能會回退安裝舊版本，例如 xinference==1.2.0 和 xoscar==0.8.0 （截至 2025 年 10 月 27 日）。

這些舊版本不相容，會導致以下錯誤：MainActorPool.append_sub_pool() got an unexpected keyword argument 'start_method'

curl -s https://mirrors.aliyun.com/pypi/simple/num2words/ | grep -i "num2words"
# Returns NOTHING! But it works on Tsinghua or Tencent mirrors.
# uv pip install "xinference[audio]" will then install the following packages (as of Oct 27, 2025):
+ x-transformers==2.10.2
+ xinference==1.2.0
+ xoscar==0.8.0

為避免在安裝 xinference 音訊套件時出現此問題，建議同時使用多個映像來源：

uv pip install xinference[audio] --index-url https://mirrors.aliyun.com/pypi/simple --extra-index-url https://pypi.tuna.tsinghua.edu.cn/simple

# Optional: Set this globally in your uv config
mkdir -p ~/.config/uv
cat >> ~/.config/uv/uv.toml << EOF
index-url = "https://mirrors.aliyun.com/pypi/simple"
extra-index-url = ["https://pypi.tuna.tsinghua.edu.cn/simple"]
EOF

使用 uv 安裝 Xinference 1.12.0 失敗（截至 2025 年 11 月）#

注意： 這是一個暫時性的問題，原因在於目前的軟體套件生態系統以及 uv 的依賴解析策略——它會優先選擇 直接依賴的高版本，而不是 間接依賴的版本。

症狀#

在 2025 年 11 月使用 uv pip install xinference 安裝 xinference 1.12.0 時，你可能會遇到安裝到非常舊版本依賴套件的問題，尤其是：

  • transformers==4.12.2 （來自 2021 年的版本）

  • tokenizers==0.10.3 （來自 2021 年的版本）

  • huggingface-hub==1.0.1

隨後 uv 報錯："Failed to build tokenizers==0.10.3"（建置 tokenizers==0.10.3 失敗）

根本原因#

出現該問題的原因是 uv 會優先選擇 直接依賴的高版本，而忽略 間接依賴 中的版本要求：

  1. xinference 1.12.0 將 huggingface-hub>=0.19.4 指定為 直接依賴 （沒有上限約束）

  2. 截至 2025 年 11 月 6 日，uv 會選擇最新版本：huggingface-hub==1.0.1

  3. 然而，transformers<=4.57.3 （透過 peft 引入的 間接依賴 ）要求 huggingface-hub<1.0

  4. 為了解決依賴衝突，uv 保留了直接依賴 huggingface-hub==1.0.1，並將間接依賴 transformers 降級到了非常舊的版本 4.12.2。

這屬於 uv 的設計特性：它會優先滿足你明確指定的相依項目（直接相依），而非遞迴相依。參考連結：astral-sh/uv#16601

更新： 截至 2026.01.05，transformers 最新版本 4.57.3 依然 依賴 huggingface-hub<1.0。

解決方案#

解決方案 1：預先限定 huggingface-hub 版本（推薦）

顯式地將 huggingface-hub 限定在一個相容的版本範圍內：

uv pip install "huggingface-hub>=0.34.0,<1.0" xinference

這樣可以強制 uv 選擇與現代版本 transformers 相容的 huggingface-hub 版本。

解決方案 2：將 transformers 設為直接依賴

透過明確指定 transformers，它會成為直接依賴，uv 將優先選擇更高版本：

uv pip install transformers xinference

解決方案 3：使用 pip

或者直接使用 pip install xinference，它會自動解析到以下版本組合：

  • transformers==4.57.1

  • huggingface-hub==0.36.0

  • tokenizers==0.22.1

vLLM + Torch + Xinference 相容性問題（段錯誤）#

症狀#

若您安裝的是 vLLM < 0.12.0，且已升級 xinference（特別是使用 uv pip install -U xinference 時），xinference 可能在啟動時因區段錯誤而失敗：

root@server:/home# xinference-local --host 0.0.0.0 --port 9997
INFO 12-30 17:35:37 [__init__.py:216] Automatically detected platform cuda.
Aborted (core dumped)

根本原因#

該問題由三個因素共同導致：

  1. 二進位不相容性：vLLM 在 0.12.0 之前的版本是基於 PyTorch 2.8.0 編譯的，這些版本與 PyTorch 2.9 不相容。參考：vLLM v0.12.0 發布說明

  2. Xinference 對 Torch 依賴未設定上限：Xinference 的 setup.cfg 中未為 PyTorch 指定版本上限：

    [options]
install_requires =
    torch                    # No version constraint!

    This allows package managers to upgrade PyTorch to incompatible versions.

  3. 不同套件管理員的行為差異：

    • pip：較為保守 —— 僅在相依性不相容時，才會升級相關相依性，否則只升級指定的套件。

    • 使用 -U 參數的 uv：策略較為激進 —— 會重新解析**所有**依賴，並選擇最新版本

因此，在你尚未準備好升級整個技術棧、而只是想升級 xinference 時，可以選擇使用：

  • pip install -U xinference (keeps PyTorch unchanged, only upgrades xinference)

  • uv pip install "xinference==1.16.0" (without -U flag, only upgrades xinference too)