Servir des LLM personnalisés avec la mise en service de modèle personnalisé

Cette page montre comment déployer votre propre LLM sur un endpoint GPU Model Serving. Tout modèle exécuté par vLLM devient un point de terminaison de production avec une API compatible OpenAI. Voici comment cela fonctionne :

• Vous exécutez le serveur d’inférence, comme vLLM, et choisissez sa version et ses paramètres.
• Vous testez le serveur dans un notebook AI Runtime. Un mauvais indicateur ou une erreur de mémoire insuffisante apparaît en quelques secondes au lieu d’apparaître après un déploiement.
• Vous déployez la même commande et le même environnement que vous avez créés et dont vous savez qu’ils fonctionnent vers un point de terminaison de mise en service.

Quickstart

Importez le notebook suivant dans votre espace de travail et cliquez sur Exécuter tout sur AI Runtime avec un GPU A10. En environ 15 minutes, vous avez un point de terminaison Qwen3.5-4B qui répond aux demandes de chat compatibles OpenAI.

Déployer Qwen3.5-4B avec vLLM

Obtenir un ordinateur portable

Quand utiliser le service LLM personnalisé

Utilisez un service LLM personnalisé dans les cas suivants :

• Vous avez peaufiné un LLM sur AI Runtime et vous voulez le déployer. Voir la section ci-dessous pour un exemple.
• Vous voulez servir un modèle ouvert que les API Foundation Model (FMAPI) ne prennent pas en charge, comme un nouveau LLM, un modèle de reconnaissance vocale ou un modèle d’embedding.
• Vous voulez changer l’environnement d’exécution ou l’architecture d’un LLM et vous devez contrôler l’environnement d’exécution et l’environnement.

N’utilisez pas de LLM personnalisé dans les cas suivants :

• FMAPI fournit le modèle dont vous avez besoin, sans changement. FMAPI est plus simple à utiliser et très optimisé.
• Le modèle ne tient pas sur un seul GPU avec environ 80 Go de mémoire. Par exemple, Qwen3.8-27B et gpt-oss-120b conviennent, mais Kimi K3 et GLM 5.3 non.
• Il vous faut un débit ou un prix par jeton de niveau avancé sans faire de réglage. Les performances égalent le vLLM open source sur le même GPU.

Requirements

Le service de LLM personnalisé a les exigences suivantes :

• Votre espace de travail doit avoir AI Runtime.
• Vous devez enregistrer le modèle depuis un notebook IA Runtime. Un modèle enregistré depuis un environnement CPU empaquete des dépendances CPU, et le point de terminaison GPU ne démarre pas.
• Vous devez avoir l’autorisation de créer des modèles dans un schéma du catalogue Unity.
• Vous devez enregistrer le modèle avec env_pack="databricks_model_serving". Le service LLM personnalisé est construit sur des déploiements express, qui regroupent l’environnement du notebook avec le modèle.
• Vous devez utiliser MLflow 3.12 ou version supérieure et databricks-sdk 0.102.0 ou version supérieure. L’environnement IA v6 inclut les deux.

Notebooks de démarrage

Chaque notebook associe un modèle de Hugging Face à un point de terminaison interrogé, comme le démarrage rapide. Exécutez-en un tel quel ou démarrez de l’un d’entre eux pour servir votre propre modèle.

AI v6 et Standard v6 sont des environnements d’exécution IA. AI v6 est équipé de vLLM, PyTorch, Transformers et d’autres packages d’apprentissage automatique courants préinstallés et prêts à l’emploi. Voir la liste des paquets AI v6. Un notebook Standard v6 installe le vLLM lui-même, donc vous choisissez sa version. Utilisez un notebook Standard v6 lorsque votre modèle a besoin d’un vLLM ou de transformers plus récents que ceux de l’AI v6, comme avec Muse Glimmer.

Servir votre propre modèle

Pour servir un autre modèle, choisissez le notebook de démarrage avec la même tâche et le GPU dont votre modèle a besoin. Modifiez MODEL_REPO_ID et les indicateurs dans vllm_command, puis lancez le notebook. Chaque notebook suit les étapes suivantes :

1. Téléchargez les poids modèles sur Hugging Face, ou obtenez-les à partir d’un point de contrôle d’entraînement.
2. Commence le vLLM dans le notebook et interroge-le.
3. Journalisez le modèle avec la commande vLLM comme point d’entrée, et enregistrez-le dans Unity Catalog comme déploiement express.
4. Créez un endpoint de service, qui lance la même commande.
5. Interrogez le point de terminaison avec le client OpenAI, le SDK Databricks ou SQL ai_query.

Dans l’exemple suivant, le metadata du modèle spécifie la tâche et le point d’entrée :

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

Servir un modèle affiné

Ajustez un modèle sur AI Runtime et servez-le depuis le même notebook. Pour un exemple, voir Réglage fin supervisé (Complet) et déploiement de Qwen3.5-0.8B. Le tutoriel ajuste Qwen3.5-0.8B sur un seul H100, compare les réponses avant et après l’entraînement, et sert le modèle affiné.

Servir des adaptateurs LoRA

Un point de terminaison peut servir plusieurs adaptateurs LoRA sur un même modèle de base : vLLM charge le modèle de base une fois et applique l’adaptateur que chaque requête nomme. Pour un exemple qui utilise deux adaptateurs d’espace réservé, voir le notebook de prise en main Qwen3.5-4B et LoRA adapters.

Pour servir les adaptateurs LoRA, faites ce qui suit :

1. Sauvegardez chaque adaptateur dans son propre dossier, par exemple avec save_pretrained de la bibliothèque Hugging Face Parameter-Efficient Fine-Tuning (PEFT).

2. Journalisez le dossier des adaptateurs à côté des poids du modèle de base, et ajoutez les indicateurs LoRA de vLLM au point d’entrée. --max-loras Détermine combien d’adaptateurs peuvent fonctionner dans un même lot. Réglez --max-lora-rank sur un rang au moins égal à celui de votre plus grand adaptateur. Le vLLM n’accepte que 1, 8, 16, 32, 64, 128, 256, 320 et 512, donc arrondissez à la valeur supérieure.

   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. Créez le point de terminaison et interrogez un adaptateur par nom.

Les adaptateurs présentent les limitations suivantes :

• La sélection d’adaptateur ne fonctionne que sur les points de terminaison du chat (llm/v1/chat).
• Le point de terminaison doit servir un seul modèle avec 100 % de son trafic qui lui est attribué. Les points d’accès qui répartissent le trafic entre modèles ou versions ne peuvent pas sélectionner d’adaptateur.
• Les adaptateurs se chargent lorsque le point de terminaison démarre. Pour les changer, enregistrez une nouvelle version de modèle et mettez à jour le point de terminaison.

Tâches prises en charge

Le task dans les métadonnées du modèle définit l’API servie par le point de terminaison. Votre serveur doit exposer l’API compatible OpenAI pour cette tâche. D’autres tâches, comme llm/v1/completions, ne sont pas prises en charge. Le tableau suivant liste les tâches prises en charge.

Choisissez un GPU

Azure Databricks recommande de développer sur le même GPU sur lequel vous effectuez le serving, donc les paramètres que vous testez sont ceux que vous déployez. La table suivante liste les GPU pour le service LLM personnalisé.

Problèmes courants

Les problèmes suivants sont les plus courants lorsque vous changez de notebook :

• Le téléchargement échoue dans /Workspace, qui n’accepte pas les fichiers de plusieurs Go. Téléchargez les pondérations sur le disque local, comme le font les notebooks de démarrage.
• Le serveur local ne démarre pas. Les notebooks AI Runtime n’autorisent que les ports 3000 à 3999, donc testez sur l’un d’eux. Seul le point d’entrée utilise le port 8080, et il doit sinon correspondre à la commande que vous avez testée.
• Le point de terminaison ne trouve pas les pondérations. Le point d’entrée s’exécutant dans le dossier d'artefacts du modèle, --model doit nommer le dossier de pondérations que vous avez enregistré.
• Un modèle d’embedding ne fournit pas d’embeddings. Commencez le vLLM avec --runner pooling.
• L’inscription échoue avec TimeoutError('Timed out after 0:05:00') lors du téléchargement de model_version.tar ou de model_environment.tar. Mettez à jour vers databricks-sdk la version 0.102.0 ou supérieure et enregistrez à nouveau le modèle.

Créer un point de terminaison

Créez le point de terminaison depuis l’interface utilisateur de Serving ou avec le SDK Databricks, comme le font les notebooks de démarrage. workload_type choisit le GPU, et workload_size (Small, Medium, ou Large) fixe le nombre de répliques.

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

Mise à l’échelle à zéro et capacité

Actuellement, les points de terminaison personnalisés des LLM ne s’autoscalent pas dynamiquement, donc dimensionnez workload_size pour votre trafic maximal.

Avec la mise à l'échelle à zéro, un point de terminaison inactif arrête tous les réplicas. La requête suivante attend de une à plusieurs minutes pendant que le vLLM recharge le modèle et que toutes les répliques démarrent. Azure Databricks recommande de désactiver le scale-to-zero pour le trafic de production.

Interrogez votre point de terminaison

Un point de terminaison de chat prêt apparaît dans l’AI Playground. Les exemples suivants interrogent un point de terminaison avec le SDK Databricks, le client OpenAI et REST.

Kit de développement logiciel (SDK) Databricks

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")],
)

Client OpenAI

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 : embeddings

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

Certains modèles d’embedding attendent un préfixe sur chaque entrée, comme search_query: ou search_document:. Vérifie la carte du modèle.

Interroger un adaptateur LoRA

Pour choisir un adaptateur LoRA, envoyez une requête de chat OpenAI à https://<workspace-url>/serving-endpoints/chat/completions. Définissez l’en-tête Databricks-Model-Serving-Endpoint sur le nom de votre point de terminaison, et nommez l’adaptateur dans model. Un nom inconnu renvoie une erreur. L’URL du point de terminaison /invocations, le SDK Databricks query et ai_query ignorent le nom de l’adaptateur et utilisent le modèle de base.

Client OpenAI

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

Surveiller votre point de terminaison

L’onglet Journaux du point de terminaison affiche les journaux stdout et stderr de votre serveur en direct. L’API de logs renvoie la même sortie.

Azure Databricks transmet les métriques de votre serveur vLLM et les affiche dans l'onglet Métriques du point de terminaison :

• Latence : temps jusqu’au premier token, temps par token de sortie, latence de requête et temps d’attente.
• Chargement : requêtes en cours et en attente.
• Cache KV : utilisation et taux d'accès.
• Débit : jetons de prompt et de génération par seconde.

L’API d’export des métriques renvoie les mêmes métriques au format Prometheus, donc vous pouvez les scraper dans Prometheus ou Datadog.

Avec la télémétrie activée, Azure Databricks sauvegarde également les journaux du serveur et les métriques Prometheus vLLM dans des tables du catalogue Unity, ce qui vous permet de les interroger sur de longues périodes. Consultez la section Conserver un modèle personnalisé servant des données dans le catalogue Unity.

Pricing

Vous payez par heure d’instance GPU, comme pour d’autres services d’inférence de modèles personnalisés sur GPU. Voir la tarification de Model Serving.

Limitations et disponibilité de la région

Vous enregistrez un LLM personnalisé depuis AI Runtime, donc le service de LLM personnalisé est disponible dans les mêmes régions que le calcul GPU serverless. Ce sont des régions américaines sur AWS et Azure. GCP n’est pas pris en charge.

Les fonctionnalités suivantes ne sont pas encore prises en charge :

• Service interrégional.
• Journalisation des modèles en dehors d’AI Runtime, par exemple depuis Databricks Runtime ou un serveur CPU serverless.
• Routage tenant compte du cache KV.
• Optimisation d’itinéraire.