Benutzerdefinierte LLMs mit benutzerdefinierter Modellbereitstellung bereitstellen

Important

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

Diese Seite zeigt, wie man ein eigenes LLM auf einem Model Serving GPU-Endpunkt bereitstellt. Jedes Modell, das in vLLM läuft, wird zu einem Produktionsendpunkt mit einer OpenAI-kompatiblen API. So funktioniert es:

  • Du betreibst den Inferenzserver, zum Beispiel vLLM, und wählst dessen Version und Einstellungen aus.
  • Du testest den Server in einem KI-Runtime-Notebook . Ein falsches Flag oder ein Out-of-Memory-Fehler erscheint innerhalb von Sekunden statt nach einer Bereitstellung.
  • Sie stellen denselben Befehl und dieselbe Umgebung, die Sie erstellt haben und von denen Sie wissen, dass sie funktionieren, auf einem Produktionbereitstellungsendpunkt bereit.

Quickstart

Importiere das folgende Notebook in deinen Arbeitsbereich und klicke in AI Runtime auf Alle ausführen mit einer A10-GPU. In etwa 15 Minuten hast du einen Qwen3.5-4B-Endpunkt, der OpenAI-kompatible Chat-Anfragen beantwortet.

Qwen3.5-4B mit vLLM bereitstellen

Notebook abrufen

Wann benutzerdefinierte LLM-Bereitstellungen verwendet werden sollten

Verwenden Sie in den folgenden Fällen die benutzerdefinierte LLM-Bereitstellung:

  • Du hast ein LLM auf AI Runtime feinabgestimmt und möchtest es bereitstellen. Siehe den Abschnitt unten für ein Beispiel.
  • Man möchte ein offenes Modell bereitstellen, das von Foundation Model APIs (FMAPI) nicht unterstützt wird, wie ein neues LLM, ein Sprach-zu-Text-Modell oder ein Embedding-Modell.
  • Du möchtest die Laufzeit oder Architektur eines LLMs ändern und brauchst Kontrolle über Laufzeit und Umgebung.

Verwenden Sie in den folgenden Fällen nicht die Bereitstellung benutzerdefinierter LLMs:

  • FMAPI liefert das Modell, das Sie brauchen, unverändert. FMAPI ist einfacher zu bedienen und hoch optimiert.
  • Das Modell passt nicht auf eine einzige GPU mit etwa 80 GB Speicher. Zum Beispiel passen Qwen3.8-27B und gpt-oss-120b, aber Kimi K3 und GLM 5.3 nicht.
  • Du brauchst Frontier-Level-Durchsatz oder Preis pro Token ohne Tuning. Die Leistung entspricht der Leistung von Open-Source-vLLM auf derselben GPU.

Requirements

Um die Beispiele in diesem Leitfaden auszuführen:

  • Dein Arbeitsbereich muss AI Runtime haben.
  • Sie müssen das Modell aus einem KI-Runtime-Notebook loggen. Ein Modell, das aus einer CPU-Umgebung gespeichert wurde, enthält CPU-Abhängigkeiten, und der GPU-Endpunkt startet nicht.
  • Du musst die Berechtigung haben, Modelle in einem Unity-Katalog-Schema zu erstellen.
  • Du musst MLflow 3.12 oder höher und databricks-sdk 0.102.0 oder höher verwenden. Die KI-v6-Umgebung umfasst beides.

Die Beispiele verwenden env_pack="databricks_model_serving", um die Notebook-Umgebung während der Modellregistrierung zu verpacken. Dieser Workflow wird weiterhin unterstützt. Berechtigte Modelle können außerdem automatisch Express-Bereitstellung ohne diesen Parameter nutzen.

Starter-Notebooks

Jedes Notebook bringt ein Modell von Hugging Face zu einem Endpunkt für Abfragen, wie dem Quickstart. Führe eines unverändert aus oder beginne mit einem, um dein eigenes Modell bereitzustellen.

Modell Aufgabe Umwelt Notebook-GPU Endpunkt-GPU
Qwen3.5-4B Chat AI v6 oder Standard v6 A10 A10G (AWS), A100 (Azure)
Qwen3.8-27B Chat mit Tool-Aufrufen KI v6 H100 H100 (AWS), A100 (Azure)
Gemma 4 26B-A4B Chat mit Tool-Aufrufen KI v6 H100 H100 (AWS), A100 (Azure)
Muse Glimmer 30B Chat Standard v6 H100 H100 (AWS), A100 (Azure)
Whisper Groß-V3-Turbo Sprache-zu-Text KI v6 A10 A10G (AWS), A100 (Azure)
Qwen3-Embedding-0.6B Embeddings KI v6 A10 A10G (AWS), A100 (Azure)
Qwen3.5-4B- und Low-Rank-Adaptation (LoRA)-Adapter Chat mit Adaptern KI v6 A10 A10G (AWS), A100 (Azure)

AI v6 und Standard v6 sind KI-Laufzeitumgebungen. AI v6 wird mit vLLM, PyTorch, Transformers und anderen gängigen Machine-Learning-Paketen vorinstalliert und einsatzbereit geliefert. Siehe die AI-v6-Paketliste. Ein Standard-v6-Notebook installiert vLLM selbst, also wählst du die Version aus. Verwende ein Standard-v6-Notebook, wenn dein Modell ein neueres vLLM oder Transformers benötigt als AI v6, wie bei Muse Glimmer.

Stelle dein eigenes Modell bereit

Um ein anderes Modell bereitzustellen, wähle das Starternotebook mit derselben Aufgabe und die GPU, die dein Modell benötigt. Ändern Sie MODEL_REPO_ID und die Flaggen in vllm_command, führen Sie dann das Notebook aus. Jedes Notebook führt folgende Schritte durch:

  1. Laden Sie die Modellgewichte von Hugging Face herunter oder holen Sie sie aus einem Trainings-Checkpoint.
  2. Starte vLLM im Notizbuch und frage es ab.
  3. Protokolliere das Modell mit dem vLLM-Befehl als Einstiegspunkt und registriere es als Express Deployment im Unity-Katalog.
  4. Erstellen Sie einen Serving-Endpunkt, der denselben Befehl startet.
  5. Fragen Sie den Endpunkt mit dem OpenAI-Client, dem Databricks SDK oder SQL ai_query ab.

Im folgenden Beispiel enthält das metadata des Modells die Aufgabe und den Einstiegspunkt:

import mlflow
from mlflow.pyfunc.model import ChatCompletionResponse, ChatModel

# The endpoint runs the entrypoint and never calls predict, but MLflow needs a model class to log.
class Placeholder(ChatModel):
    def predict(self, context, messages, params):
        return ChatCompletionResponse.from_dict({"choices": []})

model_info = mlflow.pyfunc.log_model(
    name="my-model",
    python_model=Placeholder(),
    artifacts={"model_dir": "my-model"},  # the weights folder, which --model names
    metadata={
        "task": "llm/v1/chat",
        "entrypoint": (
            "python -u -m vllm.entrypoints.openai.api_server "
            "--model my-model --served-model-name my-model "
            "--host 0.0.0.0 --port 8080 --max-model-len 16384"
        ),
    },
)
mlflow.register_model(model_info.model_uri, "<catalog>.<schema>.my_model", env_pack="databricks_model_serving")

Ein fein abgestimmtes Modell bereitstellen

Feinjustiere ein Modell in AI Runtime und stelle es aus demselben Notebook bereit. Ein Beispiel finden Sie unter Überwachtes Fine-Tuning (vollständig) und Bereitstellung von Qwen3.5-0.8B. Das Tutorial feinjustiert Qwen3.5-0.8B auf einem einzelnen H100, vergleicht Antworten vor und nach dem Training und stellt das feinabgestimmte Modell bereit.

LoRA-Adapter bereitstellen

Ein Endpunkt kann mehrere LoRA-Adapter auf einem Basismodell bereitstellen: vLLM lädt das Basismodell einmal und wendet den Adapter an, den jede Anfrage angibt. Ein Beispiel, das zwei Platzhalter-Adapter verwendet, finden Sie im Qwen3.5-4B und LoRA-Adapter Starter-Notebook.

Um LoRA-Adapter bereitzustellen, machen Sie Folgendes:

  1. Speichere jeden Adapter in einem eigenen Ordner, zum Beispiel mit save_pretrained aus der Hugging Face Parameter-Efficient Fine-Tuning (PEFT)-Bibliothek.

  2. Protokollieren Sie den Adapter-Ordner neben den Gewichten des Basismodells und fügen Sie die LoRA-Flags von vLLM zum Eintrittspunkt hinzu. --max-loras Legt fest, wie viele Adapter in einem einzigen Batch laufen können. Setzen Sie --max-lora-rank mindestens auf den Rang Ihres größten Adapters. vLLM akzeptiert nur 1, 8, 16, 32, 64, 128, 256, 320 und 512, also aufrunden.

    model_info = mlflow.pyfunc.log_model(
        name="my-model",
        python_model=Placeholder(),
        artifacts={"model_dir": "my-model", "adapters": "adapters"},  # the base weights, and one folder per adapter
        metadata={
            "task": "llm/v1/chat",
            "entrypoint": (
                "python -u -m vllm.entrypoints.openai.api_server "
                "--model my-model --served-model-name my-model "
                "--enable-lora --lora-modules finance=adapters/finance support=adapters/support "
                "--max-loras 2 --max-lora-rank 8 "
                "--host 0.0.0.0 --port 8080"
            ),
        },
    )
    
  3. Erstellen Sie den Endpunkt und fragen Sie einen Adapter nach Namen ab.

Adapter haben folgende Einschränkungen:

  • Die Adapterauswahl funktioniert nur auf Chat-Endpunkten (llm/v1/chat).
  • Der Endpunkt muss ein einziges Modell mit 100 % seines gesamten Anfrageverkehrs bedienen. Endpunkte, die den Datenverkehr zwischen Modellen oder Versionen aufteilen, können keinen Adapter auswählen.
  • Adapter werden geladen, wenn der Endpunkt startet. Um sie zu ändern, registrieren Sie eine neue Modellversion und aktualisieren Sie den Endpunkt.

Unterstützte Aufgaben

task in den Metadaten des Modells legt die API fest, die der Endpunkt bereitstellt. Dein Server muss die OpenAI-kompatible API für diese Aufgabe bereitstellen. Andere Aufgaben wie llm/v1/completions, werden nicht unterstützt. Die folgende Tabelle listet die unterstützten Aufgaben auf.

task Modelltyp Abfrage mit
llm/v1/chat Chat-Modelle, einschließlich Vision-Sprachmodellen chat.completions
llm/v1/embeddings Einbetten von Modellen embeddings
llm/v1/audio/transcriptions Sprach-zu-Text-Modelle audio.transcriptions
llm/v1/audio/translations Modelle für die Übersetzung von Sprache ins Englische audio.translations

Wähle eine GPU

Azure Databricks empfiehlt, auf derselben GPU zu entwickeln, auf der das Modell bereitgestellt wird, daher sind die Einstellungen, die man testet, die Einstellungen, die man selbst bereitstellt. Die folgende Tabelle listet die GPUs für benutzerdefinierte LLM-Bereitstellung auf.

workload_type Grafikprozessor (GPU) Hinweise
GPU_SMALL 1x T4 (16 GB) Modelle mit bis zu etwa 5 Milliarden Parametern.
GPU_LARGE 1x A100 (80 GB) Große Modelle. Allgemein verfügbar.
GPU_LARGE_RTX 1x RTX PRO 6000 (96 GB) Mehr Speicher und Geschwindigkeit als A100. Verfügbar in southeastasia und westus2.

Häufig auftretende Probleme

Die folgenden Probleme sind die häufigsten beim Wechsel eines Notebooks:

  • Der Download schlägt fehl in /Workspace, das keine Dateien im Multi-GB-Bereich akzeptiert. Lade die Gewichte auf die lokale Festplatte herunter, wie es die Starter-Notebooks tun.
  • Der lokale Server startet nicht. AI-Runtime-Notebooks erlauben nur Ports von 3000 nach 3999, also testet auf einem davon. Nur der Entrypoint verwendet Port 8080, und ansonsten muss er mit dem Befehl übereinstimmen, den Sie getestet haben.
  • Der Endpunkt kann die Gewichte nicht finden. Der Entrypoint läuft im Artefaktordner des Modells und --model muss also den von dir geloggten Ordner mit den Gewichten benennen.
  • Ein Einbettungsmodell liefert keine Einbettungen aus. Starte vLLM mit --runner pooling.
  • Registrierung schlägt beim TimeoutError('Timed out after 0:05:00') Hochladen model_version.tar oder model_environment.tarfehl. Upgrade auf databricks-sdk 0.102.0 oder höher und registriere das Modell erneut.

Erstellen eines Endpunkts

Erstellen Sie den Endpunkt aus der Serving UI oder mit dem Databricks SDK, wie es die Starter-Notebooks tun. workload_type wählt die GPU aus und workload_size (Small, Medium, oder Large) legt die Anzahl der Replikate fest.

ServedEntityInput(
    entity_name="<catalog>.<schema>.<model>",
    entity_version="<version>",
    workload_type=ServingModelWorkloadType.GPU_MEDIUM,
    workload_size="Small",
    scale_to_zero_enabled=False,
)

Auf Null skalieren und Kapazität

Derzeit skalieren benutzerdefinierte LLM-Endpunkte nicht automatisch und dynamisch; wählen Sie daher die Größe workload_size passend für Ihr Spitzenaufkommen.

Bei der Skalierung auf null stoppt ein inaktiver Endpunkt alle Replikate. Die nächste Anfrage wartet ein bis mehrere Minuten, während vLLM das Modell erneut lädt und alle Repliken starten. Azure Databricks empfiehlt, Scale-to-Zero für Produktionsverkehr auszuschalten.

Warning

Die Skalierungskapazität ist nicht garantiert. Wann immer Azure Databricks eine neue GPU für Ihren Endpunkt zuzuweisen muss, zum Beispiel bei der Erstellung, bei einer workload_size Erhöhung oder wenn ein Endpunkt aus dem Nullzustand aktiviert wird, kann die Anfrage möglicherweise nicht mehr reagieren, wenn der Cloud-Anbieter keine GPU-Kapazität in Ihrer Region hat. 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.

Endpunkt abfragen

Ein einsatzbereiter Chat-Endpoint erscheint im AI Playground. Die folgenden Beispiele fragen einen Endpunkt mit dem Databricks SDK, dem OpenAI-Client und REST ab.

Databricks SDK

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.serving import ChatMessage, ChatMessageRole

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

OpenAI-Client

from openai import OpenAI

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"}])
client.embeddings.create(model="<endpoint-name>", input=["The quick brown fox jumps over the lazy dog."])
with open("speech.flac", "rb") as audio:
    client.audio.transcriptions.create(model="<endpoint-name>", file=audio)

REST: Chat

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

REST: Einbettungen

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 ein Präfix auf jeder Eingabe, wie search_query: oder search_document:. Überprüfen Sie die Modellkarte.

LoRA-Adapter abfragen

Um einen LoRA-Adapter auszuwählen, senden Sie eine OpenAI-Chatanfrage an https://<workspace-url>/serving-endpoints/chat/completions. Setze den Databricks-Model-Serving-Endpoint Header auf deinen Endpunktnamen und nenne den Adapter in model. Ein unbekannter Name gibt einen Fehler zurück. Die /invocations URL des Endpunkts, die Databricks SDKs query und ai_query ignorieren den Adapternamen und verwenden das Basismodell.

OpenAI-Client

from openai import OpenAI

client = OpenAI(
    api_key=DATABRICKS_TOKEN,
    base_url=f"{DATABRICKS_HOST}/serving-endpoints",
    default_headers={"Databricks-Model-Serving-Endpoint": "<endpoint-name>"},
)
client.chat.completions.create(model="finance", messages=[{"role": "user", "content": "What is EBITDA?"}])

REST

curl -X POST \
  -u "token:$DATABRICKS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Databricks-Model-Serving-Endpoint: <endpoint-name>" \
  -d '{"model":"finance","messages":[{"role":"user","content":"What is EBITDA?"}]}' \
  https://<workspace-url>/serving-endpoints/chat/completions

Überwachen Sie Ihren Endpunkt

Der Logs-Tab des Endpunkts zeigt die Server-stdout und stderr-Logs live. Die Logs-API liefert die gleiche Ausgabe.

Azure Databricks leitet die Metriken Ihres vLLM-Servers weiter und zeigt sie auf dem Metrics-Tab des Endpunkts dar:

  • Latenz: Zeit bis zum ersten Token, Zeit pro Ausgabetoken, Anfragelatenz und Warteschlangenzeit.
  • Auslastung: Anfragen laufen und warten.
  • KV-Cache: Nutzung und Trefferrate.
  • Durchsatz: Prompt- und Generierungstoken pro Sekunde.

Die Exportmetrics-API liefert dieselben Metriken im Prometheus-Format, sodass man sie in Prometheus oder Datadog scrapen kann.

Mit aktivierter Telemetrie speichert Azure Databricks außerdem die Serverprotokolle und die vLLM Prometheus-Metriken in Unity-Catalog-Tabellen, sodass man sie über längere Zeiträume abfragen kann. Weitere Informationen finden Sie unter BDaten von benutzerdefinierten Modellbereitstellungsendpunkten in Unity Catalog speichern.

Pricing

Du zahlst pro GPU-Instanzstunde, genauso wie bei anderen GPU-Custom-Model-Serving. Siehe Model Serving-Preisgestaltung.

Einschränkungen und regionale Verfügbarkeit

Du loggst ein benutzerdefiniertes LLM aus AI Runtime, sodass die Bereitstellung von benutzerdefinierten LLMs in denselben Regionen wie serverlose GPU-Rechenleistungen verfügbar ist. Das sind US-Regionen auf AWS und Azure. GCP wird nicht unterstützt.

Die folgenden Features werden nicht unterstützt:

  • Regionsübergreifende Bereitstellung.
  • Logging von Modellen außerhalb von AI Runtime, zum Beispiel von Databricks Runtime oder CPU-Serverless.
  • KV-cache-bewusstes Routing.
  • Routenoptimierung.