Fehlerbehebung#

Keine Berechtigung für das Huggingface-Repository.#

Beim Abrufen eines Modells können manchmal Berechtigungsprobleme auftreten. Beispielsweise kann beim Abrufen des Modells llama2 folgender Hinweis erscheinen:

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.

Dies liegt in der Regel daran, dass keine Berechtigung für das Huggingface-Repository vorliegt oder kein Huggingface-Token konfiguriert ist. Dies kann wie folgt behoben werden.

Anfrage für Hugging Face-Repository-Berechtigungen#

Um Zugriffsberechtigungen zu erhalten, öffnen Sie das entsprechende Huggingface-Repository und akzeptieren Sie dessen Bedingungen und Hinweise. Am Beispiel von llama2 können Sie diesen Link öffnen, um einen Antrag zu stellen: https://huggingface.co/meta-llama/Llama-2-7b-hf.

Festlegen der Huggingface-Zugangsdaten#

Die Anmeldeinformationen sind auf der Huggingface-Seite zu finden: https://huggingface.co/settings/tokens.

Die Zugangsdaten können durch Setzen der Umgebungsvariable konfiguriert werden: export HUGGING_FACE_HUB_TOKEN=your_token_here.

NVIDIA-Treiber und PyTorch-Version sind nicht kompatibel.#

Wenn Sie eine NVIDIA-Grafikkarte verwenden, könnte der folgende Fehler auftreten:

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

Dieser Fall wird in der Regel durch eine Inkompatibilität zwischen der CUDA-Version und der PyTorch-Version verursacht.

Sie können auf der offiziellen Website https://pytorch.org die zur CUDA-Version passende vorkompilierte Version von PyTorch installieren. Gleichzeitig überprüfen Sie bitte, dass die installierte CUDA-Version nicht kleiner als 11.8 ist, idealerweise zwischen 11.8 und 12.1 liegt.

Wenn Ihre CUDA-Version 11.8 ist, können Sie den entsprechenden PyTorch mit dem folgenden Befehl installieren:

pip install torch==2.0.1+cu118

Externe Systeme können nicht über <IP>:9997 auf den Xinference-Dienst zugreifen.#

Stellen Sie beim Starten von Xinference sicher, dass Sie den Parameter -H 0.0.0.0 hinzufügen:

xinference-local -H 0.0.0.0

Dann wird der Xinference-Dienst auf allen Netzwerkschnittstellen horchen (nicht nur auf 127.0.0.1 oder localhost).

Wenn Sie Docker-Image verwenden, fügen Sie bitte -p <PORT>:9997 zum Docker-Ausführungsbefehl hinzu, dann können Sie über <IP>:<PORT> auf Ihrem lokalen Rechner darauf zugreifen.

Das Starten des integrierten Modells dauert sehr lange, und das Modell schlägt manchmal beim Herunterladen fehl.#

Xinference verwendet standardmäßig HuggingFace als Modellquelle. Wenn sich Ihre Maschine in Festlandchina befindet, kann es bei der Verwendung des integrierten Modells zu Zugriffsproblemen kommen.

Um dieses Problem zu lösen, kann beim Start von Xinference die Umgebungsvariable XINFERENCE_MODEL_SRC=modelscope hinzugefügt werden, um die Modellquelle auf ModelScope zu ändern. Der Download in Festlandchina ist dann schneller.

Wenn Sie Xinference mit Docker starten, können Sie die Option -e XINFERENCE_MODEL_SRC=modelscope in den Docker-Befehl einfügen.

Bei Verwendung des offiziellen Docker-Images stirbt RayWorkerVllm aufgrund von OOM, sodass das Modell nicht geladen werden kann.#

Der Parameter --shm-size von Docker kann verwendet werden, um die Größe des gemeinsamen Speichers festzulegen. Die Standardgröße des gemeinsamen Speichers (/dev/shm) beträgt 64 MB, was für das vLLM-Backend möglicherweise nicht ausreicht.

Sie können die Größe erhöhen, indem Sie den Parameter --shm-size festlegen:

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

Fehlender Parameter model_engine beim Laden des LLM-Modells#

Seit Version v0.11.0 muss beim Laden eines LLM-Modells der zusätzliche Parameter model_engine übergeben werden. Weitere Informationen finden Sie unter hier.

Behebung des MKL-Thread-Schichtkonflikts#

Wenn Sie den Xinference-Server starten, tritt ein Fehler auf: ValueError: Model architectures ['Qwen2ForCausalLM'] failed to be inspected. . Please check the logs for more details.

Der im Log angezeigte Hauptgrund ist:

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.

Dies liegt in der Regel daran, dass Ihre NumPy-Installation über conda erfolgte, wobei die conda-Version von NumPy mit Intel MKL-Optimierung erstellt wurde. Dies führt zu Konflikten mit der im System geladenen GNU OpenMP-Bibliothek (libgomp).

Lösung 1: Neuschreiben der Thread-Ebene#

Setzen Sie MKL_THREADING_LAYER=GNU, um die Intel Math Kernel Library (MKL) zu zwingen, die GNU OpenMP-Implementierung zu verwenden:

MKL_THREADING_LAYER=GNU xinference-local

Lösung 2: NumPy mit pip neu installieren#

Deinstallieren Sie das mit conda installierte numpy und installieren Sie es dann mit pip neu.

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

Konfigurieren Sie den PyPI-Spiegel, um die Paketinstallationsgeschwindigkeit zu erhöhen.#

Wenn Sie sich in Festlandchina befinden, kann die Verwendung von PyPI-Spiegeln die Installationsgeschwindigkeit von Softwarepaketen erheblich beschleunigen. Hier sind einige häufig verwendete Spiegelquellen:

  • Tsinghua-Universitätsspiegel: https://pypi.tuna.tsinghua.edu.cn/simple

  • Alibaba Cloud Mirror: https://mirrors.aliyun.com/pypi/simple/

  • Tencent Cloud Mirror: https://mirrors.cloud.tencent.com/pypi/simple

Beachten Sie jedoch, dass auf einigen Spiegelservern möglicherweise einige Pakete fehlen. Wenn Sie beispielsweise ausschließlich den Alibaba-Cloud-Spiegel verwenden, um xinference[audio] zu installieren, kann die Installation fehlschlagen.

Dies liegt daran, dass das von MeloTTS benötigte Paket num2words im Alibaba-Cloud-Spiegel nicht verfügbar ist. Daher kann es bei der Ausführung von pip install xinference[audio] vorkommen, dass auf eine ältere Version zurückgegriffen wird, z. B. xinference==1.2.0 und xoscar==0.8.0 (Stand: 27. Oktober 2025).

Diese alten Versionen sind inkompatibel und führen zu folgendem Fehler: 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

Um dieses Problem bei der Installation des xinference-Audiopakets zu vermeiden, wird empfohlen, mehrere Spiegelquellen gleichzeitig zu verwenden.

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

Die Installation von Xinference 1.12.0 mit uv ist fehlgeschlagen (Stand November 2025).#

Hinweis: Dies ist ein temporäres Problem, das auf das aktuelle Softwarepaket-Ökosystem sowie die Abhängigkeitsauflösungsstrategie von uv zurückzuführen ist – diese priorisiert höhere Versionen direkter Abhängigkeiten gegenüber Versionen indirekter Abhängigkeiten.

Symptome#

Bei der Installation von xinference 1.12.0 im November 2025 mit uv pip install xinference kann es vorkommen, dass sehr alte Abhängigkeitspakete installiert werden, insbesondere:

  • transformers==4.12.2 (aus der Version von 2021)

  • tokenizers==0.10.3 (Version aus dem Jahr 2021)

  • huggingface-hub==1.0.1

Anschließend meldet uv den Fehler: „Failed to build tokenizers==0.10.3“ (Fehler beim Erstellen von tokenizers==0.10.3)

Grundursache#

Der Grund für dieses Problem ist, dass uv höhere Versionen direkter Abhängigkeiten priorisiert, während die Versionsanforderungen indirekter Abhängigkeiten ignoriert werden:

  1. xinference 1.12.0 legt huggingface-hub>=0.19.4 als direkte Abhängigkeit fest (keine obere Grenze).

  2. Bis zum 6. November 2025 wählt uv die neueste Version aus: huggingface-hub==1.0.1

  3. Allerdings erfordert transformers<=4.57.3 (eine indirekte Abhängigkeit über peft) huggingface-hub<1.0.

  4. Um Abhängigkeitskonflikte zu lösen, hat uv die direkte Abhängigkeit huggingface-hub==1.0.1 beibehalten und die indirekte Abhängigkeit transformers auf die sehr alte Version 4.12.2 herabgestuft.

Dies ist ein Designmerkmal von uv: Es erfüllt bevorzugt die von Ihnen explizit angegebenen Abhängigkeiten (direkte Abhängigkeiten) anstelle von transitiven Abhängigkeiten. Referenzlink: astral-sh/uv#16601

Aktualisierung: Stand 05.01.2026 hängt die neueste Version 4.57.3 von transformers weiterhin von huggingface-hub<1.0 ab.

Lösung#

Lösung 1: Version von huggingface-hub vorab einschränken (empfohlen)

Begrenzen Sie huggingface-hub explizit auf einen kompatiblen Versionsbereich:

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

Dadurch kann uv gezwungen werden, eine Version von huggingface-hub zu wählen, die mit der modernen Version von transformers kompatibel ist.

Lösung 2: Transformers als direkte Abhängigkeit festlegen

Durch die explizite Angabe von transformers wird es zu einer direkten Abhängigkeit, und uv bevorzugt eine neuere Version:

uv pip install transformers xinference

Lösung 3: pip verwenden

Oder verwenden Sie direkt pip install xinference, es wird automatisch die folgende Versionskombination auflösen:

  • transformers==4.57.1

  • huggingface-hub==0.36.0

  • tokenizers==0.22.1

vLLM + Torch + Xinference Kompatibilitätsproblem (Segmentation Fault)#

Symptome#

Wenn Sie vLLM < 0.12.0 installiert haben und xinference aktualisiert haben (insbesondere bei Verwendung von uv pip install -U xinference), kann xinference beim Start aufgrund eines Segmentierungsfehlers fehlschlagen:

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)

Grundursache#

Das Problem wird durch drei Faktoren gemeinsam verursacht:

  1. Binäre Inkompatibilität: vLLM-Versionen vor 0.12.0 wurden mit PyTorch 2.8.0 kompiliert und sind nicht mit PyTorch 2.9 kompatibel. Referenz: vLLM v0.12.0 Versionshinweise

  2. Xinference setzt keine Obergrenze für die Torch-Abhängigkeit: In der setup.cfg von Xinference wird keine Versionsobergrenze für PyTorch festgelegt:

    [options]
install_requires =
    torch                    # No version constraint!

    This allows package managers to upgrade PyTorch to incompatible versions.

  3. Verhaltensunterschiede verschiedener Paketmanager:

    • pip: eher konservativ – Abhängigkeiten werden nur dann aktualisiert, wenn diese inkompatibel sind, ansonsten wird nur das angegebene Paket aktualisiert.

    • uv mit dem Parameter -U: Die Strategie ist aggressiver – sie analysiert alle Abhängigkeiten neu und wählt die neueste Version aus.

Wenn Sie also noch nicht bereit sind, Ihren gesamten Technologie-Stack zu aktualisieren, sondern nur xinference aufrüsten möchten, können Sie Folgendes verwenden:

  • pip install -U xinference (PyTorch-Version unverändert lassen, nur xinference aktualisieren)

  • `uv pip install "xinference==1.16.0"` (Ohne den Parameter -U wird ebenfalls nur xinference aktualisiert)