Benutzerdefinierte LLMs mit benutzerdefinierter Modellbereitstellung bereitstellen

Important

Dieses Feature befindet sich in der Betaversion. Arbeitsbereichsadministratoren können den Zugriff auf dieses Feature über die Vorschauseite steuern. Siehe Manage Azure Databricks Previews.

Auf dieser Seite wird gezeigt, wie Sie benutzerdefinierte großsprachige Modelle (LLMs) für die Modellbereitstellung mithilfe eines vLLM-Moduls bereitstellen. Verwenden Sie diesen Workflow, um fein abgestimmte Modelle, PEFT-Varianten, multimodale Modelle und andere Foundation-Modelle zu bedienen, die in Foundation Model-APIs (FMAPI) nicht verfügbar sind. Das Start-Notebook am Ende dieser Seite enthält den gesamten ausführbaren Code für die folgenden Schritte.

Wann benutzerdefinierte LLM-Bereitstellungen verwendet werden sollten

Azure Databricks empfiehlt benutzerdefinierte LLM-Dienste, wenn Sie über einen der folgenden Anwendungsfälle verfügen:

  • Voll fein abgestimmte Modelle mit benutzerdefinierten Gewichten, die Sie auf Azure Databricks trainiert haben.
  • Modelle von Hugging Face, die in FMAPI nicht verfügbar sind.
  • Benutzerdefinierte PEFT-Rezepte, die FMAPI nicht unterstützt.
  • Spezialisierte Modelle außerhalb des FMAPI-Katalogs, z. B. MedGemma.
  • Multimodale Modelle (Vision-Language) wie Qwen/Qwen2.5-VL-3B-Instruct.
  • Einbettungsmodelle, die in FMAPI nicht verfügbar sind, wie z. B. nomic-ai/nomic-embed-text-v2-moe.
  • Jedes Modell, das auf ein 1xH100 passt (80 GB GPU-Speicher).

Requirements

  • Benutzerdefinierte LLM-Bereitstellung befindet sich in Der Betaversion. Arbeitsbereichsadministratoren können dieses Feature über die Vorschauseite aktivieren oder deaktivieren. Siehe Manage Azure Databricks Previews.

  • Serverlose GPU-Berechnung. Eine A10 GPU ist die empfohlene Entwicklungsumgebung für kleinere Modelle, H100 für größere Modelle.

  • MLflow 3.12 oder höher und databricks-sdk>=0.102.0. Das Starter-Notebook legt mlflow==3.12.0 und eine kompatible SDK-Version fest. Wenn Sie Eine eigene Umgebung erstellen, stimmen Sie mit diesen Versionen überein. Bei früheren SDK-Versionen kann es beim Hochladen von Modellartefakten während der Registrierung zu Zeitüberschreitungen kommen. Siehe Zeitüberschreitung beim Hochladen von Artefakten bei der Registrierung.

Schritt 1: Einrichten Ihrer Umgebung

Erstellen Sie ein Notizbuch auf serverlosen GPU-Compute mit einer A10-GPU. Installieren Sie vLLM und deren Abhängigkeiten. Das Startnotebook heftet eine getestete vLLM-Version an.

Sie können Abhängigkeiten auch über eine serverlose Umgebung angeben, anstatt %pip install zu verwenden.

Important

Legen Sie Ihr Arbeitsverzeichnis auf lokale Festplatte fest (z. B. mit tempfile.mkdtemp()). Das /Workspace Dateisystem unterstützt keine großen Dateien wie Modellgewichtungen.

Schritt 2: Herunterladen ihres Modells

Laden Sie Modellgewichte von Hugging Face mit snapshot_download. Das Start-Notebook verwendet Qwen/Qwen3-4B als Beispiel, aber Sie können jedes Modell verwenden, das in das Speicherbudget Ihrer ausgewählten GPU passt, einschließlich der folgenden Modelle:

  • Multimodale Modelle wie Qwen/Qwen2.5-VL-3B-Instruct für Vision-Language-Anwendungsfälle.
  • Größere Modelle, die auf eine 1xH100 passen, wie etwa openai/gpt-oss-120b.

Wählen Sie eine GPU basierend auf den Speicher- und Leistungsanforderungen Ihres Modells aus.

Grafikprozessor (GPU) GPU-Arbeitsspeicher workload_type
T4 16 GB GPU_SMALL
A100 80 GB GPU_LARGE

Schritt 3: Lokales Testen des Modells mit vLLM

Testen Sie vor der Bereitstellung das Modell direkt in Ihrem serverlosen GPU-Notizbuch, indem Sie einen lokalen vLLM-Server starten. Mit lokalen Tests können Sie das Modell überprüfen, mit vLLM-Parametern experimentieren und Probleme beheben, bevor Sie einen Dienstendpunkt erstellen.

Wichtige Dinge zu wissen:

  • Serverlose GPU-Compute ermöglicht nur Ports 3000-3999 für lokale Tests. Wählen Sie einen Port in diesem Bereich aus; Das Startnotizbuch verwendet 3080.
  • Der vLLM-Server stellt unter /invocations eine OpenAI-kompatible API bereit.
  • Sie können sowohl normale als auch Streaminganforderungen testen.
  • Optimieren Sie Parameter wie --dtype, --max-model-len, und --gpu-memory-utilization für Ihr Modell.
  • Fügen Sie --enforce-eager hinzu, um den Start zu beschleunigen, auf Kosten eines Teils der Inferenzleistung.
  • Verwenden Sie für größere Modelle eine serverlose GPU-Variante für H100 für lokale Tests.

Wenn Sie mit der Konfiguration zufrieden sind, beenden Sie den lokalen Server, bevor Sie fortfahren.

Schritt 4: Protokollieren des Modells mit einem benutzerdefinierten Einstiegspunkt

Dieser Schritt verbindet Ihr lokales Setup mit Model Serving und verfügt über die folgenden Konfigurationsanforderungen:

  • Das task muss "llm/v1/chat" (Chatmodelle, einschließlich multimodaler Modelle) oder "llm/v1/embeddings" (Embedding-Modelle) sein. Siehe unterstützte Aufgaben.
  • Der Einstiegspunkt muss am Port 8080 geöffnet werden, dem port, den das Model Serving erwartet.
  • Der Einstiegspunktbefehl muss das, was Sie in Schritt 3 getestet haben, mit Port 8080 anstelle des lokalen Ports spiegeln.
  • Der Einstiegspunkt wird aus dem Ordner "MLflow-Modellartefakte" gestartet, sodass Modellpfade relativ zu diesem Ordner sind.

Für ein Chatmodell:

metadata = {
    "task": "llm/v1/chat",
    "entrypoint": (
        "python -u -m vllm.entrypoints.openai.api_server "
        "--model qwen3 --served-model-name qwen "
        "--host 0.0.0.0 --port 8080 "
        "--dtype float16 --max-model-len 16384 "
        "--gpu-memory-utilization 0.85"
    ),
}

Stellen Sie bei einem Einbettungsmodell task auf "llm/v1/embeddings" ein und starten Sie Ihren Server im Einbettungsmodus. Mit der hier verwendeten vLLM-Version, das heißt --runner pooling (ältere vLLM-Versionen verwenden --task embed):

metadata = {
    "task": "llm/v1/embeddings",
    "entrypoint": (
        "python -u -m vllm.entrypoints.openai.api_server "
        "--model nomic-embed --served-model-name nomic-embed "
        "--runner pooling "
        "--host 0.0.0.0 --port 8080 "
        "--gpu-memory-utilization 0.85"
    ),
}

Unterstützte Aufgaben

task Modelltyp Abfrageoberfläche
llm/v1/chat Chatmodelle, einschließlich multimodaler (Bild-Sprache) chat.completions
llm/v1/embeddings Einbetten von Modellen embeddings

Das task, das Sie deklarieren, muss mit dem übereinstimmen, was Ihr Entrypoint tatsächlich bereitstellt: Der Entrypoint muss die OpenAI-kompatible API für diese Aufgabe auf Port 8080 bereitstellen. In den obigen Beispielen wird vLLM verwendet, aber jeder Server, der diesen Vertrag erfüllt, funktioniert. Andere Aufgabentypen, wie z. B. llm/v1/completions, werden nicht unterstützt.

Schritt 5: Registrieren des Modells im Unity-Katalog

Registrieren Sie das Modell mit mlflow.register_model in Unity Catalog. Die Bereitstellung benutzerdefinierter LLMs hängt von Express-Bereitstellungen ab. Verwenden Sie den env_pack="databricks_model_serving" Parameter, um ihn zu aktivieren.

Fügen Sie beispielsweise Folgendes zu Ihrem Notizbuch hinzu:


model_version = mlflow.register_model(model_info.model_uri, UC_MODEL_NAME, env_pack="databricks_model_serving")

Schritt 6: Erstellen eines Dienstendpunkts

Erstellen Sie den Endpunkt über die UI oder programmgesteuert mit dem Azure Databricks SDK. Die wichtigsten Entscheidungen sind Rechentyp, Workload-Größe und das Verhalten bei der Skalierung auf null.

Wählen Sie anhand Ihres Modells und Ihrer Cloud eine workload_type aus:

workload_type Grafikprozessor (GPU) Hinweise
GPU_SMALL 1x T4 (16 GB) Kleinste Option.
GPU_LARGE 1x A100 (80 GB) Empfohlen für große LLM-Workloads.

workload_size (Small, Mediumoder Large) steuert die Anzahl der bereitgestellten Replikate hinter dem Endpunkt. Verwenden Sie Small für Entwicklung und Workloads mit geringem Datenaufkommen.

Das folgende Beispiel zeigt eine typische Konfiguration:

ServedEntityInput(
    entity_name="main.<catalog>.<model_name>",
    entity_version="<version>",
    workload_type=ServingModelWorkloadType.GPU_MEDIUM,
    workload_size="Small",
    scale_to_zero_enabled=True,
)

Skalierungs-zu-Null- und Kapazitätsplanung

Die Bereitstellung benutzerdefinierter LLMs in Betaversionen stellt eine feste Anzahl von Replikaten hinter Ihrem Endpunkt bereit. Die automatische Skalierung zwischen mehr als null Replikaten wird noch nicht unterstützt, daher müssen Sie größe workload_type und workload_size für ihren Spitzendatenverkehr festlegen. Der Endpunkt stellt Anforderungen, die die Kapazität der bereitgestellten Replikate überschreiten, in die Warteschlange.

Legen Sie scale_to_zero_enabled=True fest, um zuzulassen, dass der Endpunkt im Leerlauf auf null Replikate skaliert wird. Kaltstarts sind langsam – das Laden der Modellgewichte und das Starten von vLLM dauert typischerweise ein bis mehrere Minuten.

Legen Sie bei latenzkritischen oder produktionskritischen Workloads scale_to_zero_enabled=False fest und dimensionieren Sie workload_size im Voraus für Ihre Spitzenlast.

Warning

Die Skalierungskapazität ist nicht garantiert. Wann immer Azure Databricks eine neue GPU für Ihren Endpunkt anfordern muss – bei der Erstellung, bei workload_size Erhöhungen oder wenn ein Endpunkt aus dem Nullzustand hochfährt –, kann die Anforderung unbeantwortet bleiben, wenn der Cloud-Anbieter in Ihrer Region nicht über ausreichende GPU-Kapazität verfügt. Dies gilt für alle GPU-Typen. Databricks entschärft dies mit warmen Pools und Vorreservation, wodurch die GPU-Kapazität verfügbar und bereit bleibt.

Schritt 7: Abfragen Ihres Endpunkts

Wenn der Endpunkt bereit ist, wird er auf der Seite des Endpunkts automatisch im KI-Playground angezeigt. Sie können sie auch programmgesteuert mit dem Databricks SDK, dem OpenAI SDK oder curl abfragen.

Chatmodelle (llm/v1/chat):

Databricks SDK

w.serving_endpoints.query(
    name="<endpoint-name>",
    messages=[ChatMessage(role=ChatMessageRole.USER, content="Hello")],
)

OpenAI SDK

client = OpenAI(
    api_key=DATABRICKS_TOKEN,
    base_url=f"{DATABRICKS_HOST}/serving-endpoints",
)
client.chat.completions.create(
    model="<endpoint-name>",
    messages=[{"role": "user", "content": "Hello"}],
)

cURL

curl -X POST \
  -u "token:$DATABRICKS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"Hello"}]}' \
  https://<workspace-url>/serving-endpoints/<endpoint-name>/invocations

Einbettungsmodelle (llm/v1/embeddings):

OpenAI SDK

client = OpenAI(
    api_key=DATABRICKS_TOKEN,
    base_url=f"{DATABRICKS_HOST}/serving-endpoints",
)
client.embeddings.create(
    model="<endpoint-name>",
    input=["The quick brown fox jumps over the lazy dog."],
)

cURL

curl -X POST \
  -u "token:$DATABRICKS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"input":["The quick brown fox jumps over the lazy dog."]}' \
  https://<workspace-url>/serving-endpoints/<endpoint-name>/invocations

Einige Einbettungsmodelle erwarten bei jeder Eingabe ein aufgabenspezifisches Präfix (zum Beispiel verwendet nomic-embed-text-v2-moesearch_query: und search_document:). Überprüfen Sie die Karte Ihres Modells auf die Eingabekonventionen.

Überwachen Sie Ihren Endpunkt

Die Bereitstellung benutzerdefinierter LLMs verwendet dieselbe Observability-Infrastruktur wie standardmäßige Endpunkte für die benutzerdefinierte Modellbereitstellung, jedoch mit einigen vLLM-spezifischen Erweiterungen, die in den folgenden Abschnitten beschrieben werden.

Liveprotokolle

Die Registerkarte Protokolle auf der Endpunktseite in der Serving-Benutzeroberfläche zeigt stdout und stderr aus Ihrem vLLM-Prozess in Echtzeit an. Sie können diese Ausgabe auch über die Protokoll-API öffnen.

Persistent gespeicherte Protokolle und Metriken

Wenn Telemetrie aktiviert ist, werden protokolle und Metriken für die langfristige Aufbewahrung, SQL-Abfrage und Compliance in Unity Catalog Delta-Tabellen beibehalten. Siehe Benutzerdefinierte Modellbereitstellungsdaten in Unity Catalog beibehalten für vollständige Einrichtungsanweisungen, Anforderungen und Tabellenschemas.

Für benutzerdefinierte LLM speziell für die Bereitstellung von:

  • Protokolle: stdout und stderr aus dem vLLM-Prozess werden automatisch erfasst. Es ist kein anwendungsseitiger Protokollierungscode erforderlich.
  • Metrics: Azure Databricks verschrottet automatisch den Prometheus /metrics-Endpunkt des vLLM-Servers und speichert die Metriken zusammen mit Protokollen. Standardmäßig erhalten Sie Latenz, Durchsatz, Tokenanzahl, Warteschlangentiefe und KV-Cache-Auslastung pro Anforderung.

Telemetriedaten abfragen

Während der Betaversion gibt es keine Benutzeroberfläche zum Visualisieren von Protokollen oder Metriken. Abfragen der gespeicherten Daten direkt im Unity-Katalog mithilfe von SQL oder einem Notizbuch. Sehen Sie sich die Metrik- und Protokollschemas an, die in Daten von benutzerdefinierten Modellbereitstellungs Endpunkten in Unity Catalog speichern dokumentiert sind.

Das folgende Notizbuch zeigt, wie Sie die dauerhaften vLLM-Metriken analysieren und visualisieren:

Benutzerdefiniertes LLM-Notizbuch zur Bereitstellung von Metriken

Notebook abrufen

Beispiel-Notebook

Entwickeln und testen Sie das Modell in einem Notebook mit serverloser GPU, protokollieren Sie anschließend dieselbe Konfiguration und stellen Sie sie als Bereitstellungsendpunkt bereit. Das folgende Notebook enthält den vollständigen ausführbaren Ablauf aus diesem Leitfaden.

Benutzerdefiniertes Starter-Notebook für die LLM-Bereitstellung

Notebook abrufen

Einschränkungen

Die folgenden Einschränkungen gelten während der Betaversion.

  • Keine automatische Skalierung zwischen Replikaten. Scale-to-Zero wird unterstützt.
  • Nur der Chat (llm/v1/chateinschließlich multimodaler) und Einbettungsaufgaben (llm/v1/embeddings) werden unterstützt. Siehe unterstützte Aufgaben.
  • Keine Routenoptimierung.
  • Keine Benutzeroberfläche zum Visualisieren von Protokollen oder Metriken. Abfrage-Telemetrie direkt im Unity-Katalog.

Wenden Sie sich für Feedback oder Fragen an Ihr Azure Databricks Kontoteam.

Zeitüberschreitung beim Hochladen des Artefakts während der Registrierung

Wenn Sie das Modell mit env_pack registrieren, lädt Azure Databricks die paketierten Modellgewichte und die Umgebung als Artefakte (model_version.tar und model_environment.tar) hoch. Mit Versionen vor databricks-sdk, 0.102.0 kann das Hochladen großer LLM-Artefakte nach fünf Minuten zu einer Zeitüberschreitung führen und die Registrierung mit einem Fehler wie dem folgenden fehlschlagen:

MlflowException: The following failures occurred while uploading one or more artifacts to
/Models/<catalog>/<schema>/<model>/<version>: {
  '.../model_environment.tar': "TimeoutError('Timed out after 0:05:00')",
  '.../model_version.tar': "TimeoutError('Timed out after 0:05:00')"
}

Um dies zu beheben, führen Sie ein Upgrade auf databricks-sdk>=0.102.0 durch und registrieren Sie das Modell erneut:

%pip install databricks-sdk>=0.102.0
  • Last updated on