Modell-Virtual-Umgebung#

Added in version v1.5.0.

Hintergrund#

Einige Modelle werden nach ihrer Veröffentlichung nicht mehr gewartet, und die von ihnen abhängigen Bibliotheksversionen bleiben auf einem älteren Stand. Beispielsweise ist das Modell GOT-OCR2 weiterhin auf transformers 4.37.2 angewiesen. Wenn diese Bibliothek auf eine neuere Version aktualisiert wird, funktioniert das Modell nicht mehr korrekt; gleichzeitig benötigen viele neue Modelle jedoch die neueste Version von transformers. Diese Versionsunterschiede können zu Abhängigkeitskonflikten führen.

Lösung#

Um dieses Problem zu lösen, haben wir die Funktion Modell-Virtual-Umgebung eingeführt.

Installieren Sie die Abhängigkeiten, die für diese Funktion erforderlich sind, mit dem folgenden Befehl:

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

Durch Setzen der Umgebungsvariablen XINFERENCE_ENABLE_VIRTUAL_ENV=1 wird diese Funktion aktiviert.

Verwendungsbeispiel:

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

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

Warnung

Diese Funktion erfordert eine Internetverbindung oder die Nutzung eines selbst erstellten PyPI-Mirror-Dienstes.

Xinference übernimmt standardmäßig die aktuelle pip-Konfiguration.

Bemerkung

Hinweis: Beim Starten des vLLM/SgLang-Engine-Modells in einer virtuellen Umgebung kann bei Fehlern mit cuDNN Folgendes eingestellt werden:

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

Geändert in Version v2.0.0: Ab Xinference v2.0 ist die Funktion der virtuellen Umgebung standardmäßig aktiviert (d.h. der Standardwert von XINFERENCE_ENABLE_VIRTUAL_ENV ist 1).

Um diese Funktion global zu deaktivieren, setzen Sie XINFERENCE_ENABLE_VIRTUAL_ENV=0 beim Start von Xinference.

Nach Aktivierung dieser Funktion erstellt Xinference beim Laden eines Modells automatisch eine dedizierte virtuelle Umgebung für dieses und installiert die entsprechenden Abhängigkeiten darin. Dies verhindert Abhängigkeitskonflikte zwischen Modellen und stellt sicher, dass jedes Modell unabhängig in einer isolierten Umgebung ausgeführt wird.

Virtuelle Umgebungsverwaltung (v2.0)#

Globale Umschaltung#

Ab Version 2.0 ist die virtuelle Umgebung standardmäßig aktiviert. Sie können diese Option weiterhin über die globalen Einstellungen überschreiben:

# 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

Beim Starten nach Modell überschreiben#

Beim Starten des Modells können Sie die globalen Einstellungen überschreiben:

# 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

Pakete beim Start hinzufügen oder überschreiben#

Verwenden Sie in der Befehlszeile --virtual-env-package oder -vp, um eine einzelne Paketversion anzugeben.

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

Falls das angegebene Paket bereits in der Standardliste der virtuellen Umgebungspakete des Modells vorhanden ist, überschreibt die von Ihnen angegebene Version die Standardversion, anstatt sie zur Liste hinzuzufügen.

Speicherort#

Standardmäßig wird die virtuelle Umgebung des Modells unter folgendem Pfad gespeichert:

  • Vor v1.6.0: XINFERENCE_HOME / virtualenv / {model_name}

  • Von v1.6.0 bis v1.13.0: XINFERENCE_HOME / virtualenv / v2 / {model_name}

  • Seit v1.14.0: XINFERENCE_HOME / virtualenv / v3 / {model_name} / {python_version}

  • Seit v2.0: XINFERENCE_HOME / virtualenv / v4 / {model_name} / {model_engine} / {python_version}

Überspringe bereits installierte Bibliotheken.#

Added in version v1.8.1: Diese Funktion erfordert xoscar >= 0.7.12, die von Xinference v1.8.1 benötigte Mindestversion von Xoscar.

xinference verwendet das uv-Tool zum Erstellen einer virtuellen Umgebung und legt die system site-packages des aktuellen Python als Basisumgebung fest. Standardmäßig prüft `uv` nicht, ob Pakete bereits im System vorhanden sind, sondern installiert alle Abhängigkeiten neu in der virtuellen Umgebung. Dieser Ansatz bietet eine bessere Isolierung von Systempaketen, kann jedoch zu doppelten Installationen, längeren Initialisierungszeiten und erhöhtem Speicherplatzverbrauch führen.

Ab v1.8.1 gibt es eine experimentelle Funktion: Durch Setzen der Umgebungsvariablen XINFERENCE_VIRTUAL_ENV_SKIP_INSTALLED=1 wird uv bereits in den systemweiten site-packages vorhandene Pakete überspringen.

Geändert in Version v2.0: Diese Funktion ist in der Version v2.0 standardmäßig aktiviert. Zum Deaktivieren setzen Sie XINFERENCE_VIRTUAL_ENV_SKIP_INSTALLED=0.

Vorteile#

  • Vermeide die wiederholte Installation großer Abhängigkeiten (z.B. torch + CUDA).

  • Beschleunigung der Erstellung virtueller Umgebungen.

  • Reduzierung des Speicherplatzverbrauchs auf der Festplatte.

Verwenden#

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

Leistungsvergleich#

Am Beispiel des CosyVoice 0.5B Modells:

Wenn diese Funktion nicht aktiviert ist:

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

Nach Aktivierung dieser Funktion:

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

Modell laden: Virtuelle Umgebung umschalten und Abhängigkeiten anpassen#

Added in version v1.8.1.

Ab v1.8.1 unterstützen wir das Laden einer virtuellen Umgebung für einzelne Modelle und das Überschreiben der Standardeinstellungen des Modells mit benutzerdefinierten Paketabhängigkeiten.

Switch-Modell-Virtual Space#

Beim Laden des Modells kann angegeben werden, ob die virtuelle Umgebung des Modells aktiviert werden soll. Falls nicht angegeben, folgt es standardmäßig der Konfiguration der Umgebungsvariablen.

In der Web-Benutzeroberfläche kann diese Funktion über einen optionalen Einstellungsschalter ein- oder ausgeschaltet werden.

actor

Verwenden Sie beim Laden über die Befehlszeile die Option --enable-virtual-env, um die virtuelle Umgebung zu aktivieren, und die Option --disable-virtual-env, um sie zu deaktivieren.

Verwendungsbeispiel:

xinference launch xxx --enable-virtual-env

Festlegung der Paketabhängigkeiten der virtuellen Umgebung#

Für die unterstützten Modelle definiert Xinference bereits Paketabhängigkeiten und Versionsanforderungen in der virtuellen Umgebung. Falls jedoch eine bestimmte Version erforderlich ist oder zusätzliche Abhängigkeiten installiert werden müssen, können diese beim Laden des Modells manuell angegeben werden.

In der Web-Oberfläche können Sie durch Klicken auf das Plus-Symbol an derselben Stelle wie den virtuellen Umgebungsschalter benutzerdefinierte Abhängigkeiten hinzufügen.

In der Befehlszeile verwenden Sie --virtual-env-package oder -vp, um eine einzelne Paketversion anzugeben.

Verwendungsbeispiel:

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

Neben der üblichen Methode zur Angabe von Paketabhängigkeiten (z. B. transformers==xxx) unterstützt Xinference auch einige erweiterte Syntaxen.

  • #system_xxx#: Verwenden Sie dieselbe Version wie die System-Site-Pakete, z. B. #system_numpy#, um sicherzustellen, dass die installierte Paketversion mit der numpy-Version in den System-Site-Paketen übereinstimmt, um Abhängigkeitskonflikte zu vermeiden.

Verwaltung der virtuellen Umgebungen#

Added in version v1.14.0.

Xinference bietet umfassende Funktionen zur Verwaltung virtueller Umgebungen, mit denen Sie für jedes Modell eine unabhängige Python-Umgebung erstellen können, um spezifische Paketabhängigkeiten zu erfüllen.

actoractor

Kernfunktionen#

Unterstützung mehrerer Python-Versionen: Jedes Modell kann virtuelle Umgebungen mit unterschiedlichen Python-Versionen (z. B. Python 3.10.18, 3.11.5) besitzen, um die Kompatibilität mit verschiedenen Modellanforderungen zu gewährleisten.

Abhängigkeitsisolierung: Jede virtuelle Umgebung enthält ihr eigenes, unabhängiges Paketset, um Abhängigkeitskonflikte zwischen verschiedenen Modellen zu verhindern.

Verwaltungsvorgänge#

Virtuelle Umgebungen auflisten : Alle virtuellen Umgebungen im Cluster anzeigen, mit Filtern nach Modellname oder Arbeitsknoten-IP-Adresse.

Umgebung erstellen : Wird automatisch erstellt, wenn das Modell mit enable_virtual_env=true gestartet wird. Das System erkennt die aktuelle Python-Version und erstellt eine unabhängige Umgebung, die die erforderlichen Pakete enthält.

Umgebung löschen: Sie können eine bestimmte virtuelle Umgebung nach Modellname und optionaler Python-Version löschen oder alle Umgebungen eines Modells löschen.

ModelHub JSON-Format (für Xinference-Modelle)#

Wenn geplant ist, das Modell zum Model Hub von Xinference hinzuzufügen, definieren Sie bitte einen virtualenv-Block in der Modell-JSON. Seit v2.0 (v4-Workflow) wird die Verwendung von engine-bewussten Tags empfohlen , damit eine einzelne JSON-Datei mehrere Engines abdecken kann.

Wichtige Regel: Wenn das neue Modell eine bestimmte Engine unterstützt, muss virtualenv.packages mindestens einen Paketeintrag für diese Engine enthalten und mit einem Kennzeichen versehen sein (z. B. #engine# == "vllm"). Wenn die virtuelle Umgebung aktiviert ist, stützt sich die Überprüfung der Engine-Verfügbarkeit auf diese Kennzeichen zur Validierung.

{
  "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 (erforderlich): Liste der pip-Anforderungsstrings oder -Marker.

  • inherit_pip_config (Standardwert: true): Falls eine systemweite pip-Konfigurationsdatei existiert, werden deren Einstellungen übernommen.

  • index_url / extra_index_url / find_links / trusted_host : Pip-Index- und Spiegelsteuerung.

  • index_strategy : Wird an den Installer der virtuellen Umgebung übergeben (von einigen Engines verwendet).

  • no_build_isolation ：Schalter für die Bauisolierung von pip zur Verarbeitung komplexer Builds.

Verwenden Sie die Standardwerte der Injektions-Engine für Platzhalter in Paketen:

  • #vllm_dependencies#

  • #sglang_dependencies#

  • #mlx_dependencies#

  • #transformers_dependencies#

  • #llama_cpp_dependencies#

  • #diffusers_dependencies#

  • #sentence_transformers_dependencies#

Verwenden Sie für Vergleiche (Groß-/Kleinschreibung beachten) die Markierung #engine# oder #model_engine#. Engine-Werte werden intern in Kleinbuchstaben übergeben, daher wird die Verwendung von Kleinbuchstaben empfohlen, z. B. #engine# == "vllm" oder #engine# == "transformers".