Servez les LLM personnalisés avec Custom Model Serving

info

Bêta

Cette fonctionnalité est en Bêta. Les administrateurs du Workspace peuvent contrôler l'accès à cette fonctionnalité à partir de la page Previews . Consultez Gérer les aperçus Databricks.

Cette page vous montre comment déployer des grands modèles linguistiques (LLM) personnalisés sur Model Serving à l'aide d'un moteur vLLM. Utilisez ce workflow pour servir des modèles affinés, des variantes PEFT, des modèles multimodaux et d’autres modèles de fondation qui ne sont pas disponibles dans les APIs de modèles de fondation (FMAPI). Le Notebook de démarrage à la fin de cette page contient tout le code exécutable pour les étapes suivantes.

Quand utiliser le service LLM personnalisé

Databricks recommande le service de LLM personnalisés lorsque vous avez l’un des cas d’usage suivants :

Modèles entièrement affinés avec des poids personnalisés que vous avez entraînés sur Databricks.
Modèles de Hugging Face qui ne sont pas disponibles dans FMAPI.
Recettes PEFT personnalisées non prises en charge par FMAPI.
Modèles spécialisés en dehors du catalogue FMAPI, tels que MedGemma.
Modèles multimodaux (vision-langage) tels que Qwen/Qwen2.5-VL-3B-Instruct.
Les modèles d'intégration qui ne sont pas disponibles dans FMAPI, tels que nomic-ai/nomic-embed-text-v2-moe.
Tout modèle compatible avec un 1xH100 (80 Go de mémoire GPU).

Exigences

Le service LLM personnalisé est en version bêta. Les administrateurs du workspace peuvent activer ou désactiver cette fonctionnalité depuis la page Aperçus . Consultez Gérer les Aperçus Databricks.
Compute GPU serverless. Un GPU A10 est l'environnement de développement recommandé pour les petits modèles, H100 pour les modèles plus grands.
MLflow 3.12 ou version ultérieure et databricks-sdk>=0.102.0. Le Notebook de démarrage pins mlflow==3.12.0 et une version compatible du SDK. Si vous construisez votre propre environnement, faites correspondre ces versions. Les versions antérieures du SDK peuvent expirer lors de l'upload des artefacts de modèle pendant l'enregistrement. Consultez L'upload d'artefact expire pendant l'enregistrement.

Étape 1 : Configurez votre environnement

Créez un Notebook sur un compute GPU serverless avec un GPU A10. Installez vLLM et ses dépendances. Le Notebook de démarrage pin une version vLLM testée.

Vous pouvez également spécifier des dépendances via un environnement serverless au lieu d'utiliser %pip install.

important

Définissez votre répertoire de travail sur le disque dur local (par exemple, en utilisant tempfile.mkdtemp()). Le système de fichiers /Workspace ne prend pas en charge les fichiers volumineux tels que les poids du modèle.

Étape 2 : download votre modèle

download model weights from Hugging Face avec snapshot_download. Le notebook de démarrage utilise Qwen/Qwen3-4B comme exemple, mais vous pouvez remplacer n’importe quel modèle qui correspond au budget mémoire de votre GPU sélectionné, y compris les suivants :

Modèles multimodaux tels que Qwen/Qwen2.5-VL-3B-Instruct pour les cas d'utilisation vision-langage.
Des modèles plus grands qui peuvent être exécutés sur un 1xH100, tels que openai/gpt-oss-120b.

Sélectionnez un GPU en fonction de la mémoire et des besoins en performances de votre modèle.

GPU	Mémoire GPU	`workload_type`
T4	16 Go	`GPU_SMALL`
A10	24 Go	`GPU_MEDIUM`
H100	80 Go	`GPU_XLARGE`

Étape 3 : Testez le modèle localement avec vLLM

Avant de déployer, testez le modèle directement dans votre notebook GPU serverless en lançant un serveur vLLM local. Les tests locaux vous permettent de vérifier le modèle, d'expérimenter avec les paramètres vLLM et de résoudre les problèmes avant de créer un endpoint de service.

Éléments clés à savoir :

Le compute GPU Serverless autorise uniquement les ports 3000–3999 pour les tests locaux. Sélectionnez un port dans cette plage ; le notebook de démarrage utilise le port 3080.
Le serveur vLLM expose une API compatible OpenAI à l'adresse /invocations.
Vous pouvez tester les requêtes normales et de streaming.
Ajustez des paramètres tels que --dtype, --max-model-len, et --gpu-memory-utilization pour votre modèle.
Ajoutez --enforce-eager pour un démarrage plus rapide de la Startup, au détriment de certaines performances d'inférence.
Pour les modèles plus grands, utilisez une variante GPU serverless H100 pour les tests locaux.

Lorsque vous êtes satisfait de la configuration, arrêtez le serveur local avant de continuer.

Étape 4 : Log le modèle avec un point d'entrée personnalisé

Cette étape connecte votre configuration locale à Model Serving et présente les exigences de configuration suivantes :

Le task doit être "llm/v1/chat" (modèles de discussion, y compris multimodaux) ou "llm/v1/embeddings" (modèles d'intégration). Veuillez consulter les tâches prises en charge.
Le point d'entrée doit s'ouvrir sur le port 8080, le port attendu par Model Serving.
La commande de point d'entrée doit correspondre à ce que vous avez testé à l'étape 3, avec le port 8080 au lieu de votre port local.
Le point d'entrée se lance depuis le dossier des artefacts du modèle MLflow, ainsi les chemins de modèle sont relatifs à ce dossier.

Pour un modèle de chat :

Python
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"
    ),
}

Pour un modèle d'intégration, définissez task sur "llm/v1/embeddings" et start votre serveur en mode d'intégration. Avec la version vLLM utilisée ici, c'est-à-dire --runner pooling (les versions vLLM plus anciennes utilisent --task embed) :

Python
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"
    ),
}

Tâches prises en charge

`task`	Type de modèle	Surface de query
`llm/v1/chat`	Modèles de chat, y compris multimodaux (vision-langage)	`chat.completions`
`llm/v1/embeddings`	Modèles d'intégration	`embeddings`

Le task que vous déclarez doit correspondre à ce que votre point d'entrée sert réellement : le point d'entrée doit exposer l'API compatible avec OpenAI pour cette tâche sur le port 8080. Les exemples ci-dessus utilisent vLLM, mais tout serveur qui respecte ce contrat fonctionne. D'autres types de tâches, tels que llm/v1/completions, ne sont pas pris en charge.

Étape 5 : Enregistrer le modèle dans Unity Catalog

Enregistrez le modèle dans Unity Catalog à l'aide de mlflow.register_model. Le service LLM personnalisé dépend des déploiements express. Utilisez le paramètre env_pack="databricks_model_serving" pour l'activer.

Par exemple, ajoutez ce qui suit à votre notebook :

Python

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

Étape 6 : Créer un Endpoint de service

Créez l'Endpoint à partir de l'interface utilisateur ou par programmation avec le SDK Databricks. Les décisions clés sont le type de compute, la taille de la charge de travail et le comportement de mise à l'échelle à zéro.

Sélectionnez un workload_type en fonction de votre modèle et de votre cloud :

`workload_type`	GPU	Notes
`GPU_SMALL`	1x T4 (16 Go)	Option la plus petite.
`GPU_MEDIUM`	1x A10 (24 Go)	Par default pour l'inférence générale. Correspond à l'environnement de développement du Notebook.
`GPU_XLARGE`	1x H100 (80 Go), `us-west-2`	Recommandé pour les charges de travail LLM importantes. Nécessite une inscription ; consultez Limitations. Ne prend pas en charge l'évolutivité vers zéro pendant la phase bêta.

`workload_type`	GPU	Notes
`GPU_SMALL`	1x T4 (16 Go)	Option la plus petite.
`GPU_MEDIUM`	1x A10 (24 Go)	Par default pour l'inférence générale. Correspond à l'environnement de développement du Notebook.
`GPU_XLARGE`	1x H100 (80 Go), `us-west-2`	Recommandé pour les charges de travail LLM importantes. Nécessite une inscription ; consultez Limitations. Ne prend pas en charge l'évolutivité vers zéro pendant la phase bêta.

workload_size (Small, Medium ou Large) contrôle le nombre de réplicas provisionnées derrière l'endpoint. Utiliser Small pour le développement et les charges de travail à faible trafic.

L'exemple suivant présente une configuration typique :

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

Dimensionnement à zéro et planification de la capacité

Le service LLM personnalisé en version bêta provisionne un nombre fixe de répliques derrière votre endpoint. L'autoscaling entre plus de zéro répliques n'est pas encore pris en charge , vous devez donc dimensionner workload_type et workload_size en fonction de votre trafic maximal. L'Endpoint met en file d'attente les requêtes qui dépassent la capacité des répliques provisionnées.

Définissez scale_to_zero_enabled=True pour permettre à l'Endpoint de monter en charge vers zéro réplique lorsqu'il est inactif. Les cold start sont lents — le chargement des poids du modèle et le démarrage de vLLM prennent généralement une à plusieurs minutes.

Pour les charges de travail sensibles à la latence ou critiques pour la production, définissez scale_to_zero_enabled=False et dimensionnez workload_size pour votre trafic de pointe à l'avance.

attention

La capacité d'extension n'est pas garantie. Chaque fois que Databricks doit acquérir un nouveau GPU pour votre Endpoint—lors de la création, lors de l'augmentation de workload_size, ou lorsqu'un Endpoint se réveille à partir de zéro—la requête peut cesser de répondre si le fournisseur de cloud n'a pas de capacité GPU dans votre région. Ceci s’applique à tous les types de GPU, mais est le plus limité pour GPU_XLARGE (H100). Databricks y remédie grâce à des pools chauds et à la préréservation, qui maintiennent la capacité GPU disponible et prête.

GPU_XLARGE Les endpoints (1xH100) ne prennent pas en charge scale_to_zero_enabled=True pendant la version bêta. La capacité H100 est trop limitée pour garantir une montée en charge à froid réussie.

Étape 7 : Interrogez votre Endpoint.

Une fois l'Endpoint prêt, il apparaît automatiquement dans l'AI Playground à partir de la page de l'Endpoint. Vous pouvez également l'interroger par programme à l'aide du SDK Databricks, du SDK OpenAI ou de curl.

Modèles de chat (llm/v1/chat) :

Databricks SDK
OpenAI SDK
curl

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

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

Shell
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

Modèles d'intégration (llm/v1/embeddings) :

OpenAI SDK
curl

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

Shell
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'intégration attendent un préfixe spécifique à la tâche sur chaque entrée (par exemple, nomic-embed-text-v2-moe utilise search_query: et search_document:). Consultez la fiche de votre modèle pour ses conventions d'entrée.

Surveiller votre endpoint

Le service de LLM personnalisé utilise la même infrastructure d’observabilité que les endpoints de service de modèles personnalisés standard, mais avec quelques extras spécifiques à vLLM décrits dans les sections suivantes.

Logs en direct

La Logs tab de la page de l'Endpoint dans l'interface utilisateur de Serving affiche stdout et stderr de votre processus vLLM en temps réel. Vous pouvez également ouvrir ce résultat via l'API Logs.

Logs persistants et métriques

Lorsque la télémétrie est activée, les logs et les métriques sont persistés dans des tables Delta de Unity Catalog pour une conservation à long terme, l'interrogation SQL et la conformité. Consultez Persister les données de service de modèle personnalisé dans Unity Catalog pour les instructions de configuration complètes, les exigences et les schémas de table.

Pour la diffusion de LLM personnalisés spécifiquement :

Logs : stdout et stderr du processus vLLM sont capturés automatiquement. Aucun code de journalisation côté application n'est requis.
**Mesures** : Databricks gratte automatiquement l'endpoint Prometheus du serveur vLLM /metrics et persiste les mesures avec les Logs. Par default, vous obtenez la latence par requête, le throughput, les comptes de jetons, la profondeur de la file d'attente et l'utilisation du cache KV.

Query des données de télémétrie

Pendant la version Beta, il n'y a pas d'interface utilisateur pour visualiser les logs ou les métriques. Interrogez les données persistantes directement dans Unity Catalog à l'aide de SQL ou d'un Notebook. Consultez les schémas de métriques et de logs documentés dans Conserver les données de service de modèle personnalisées dans Unity Catalog.

Le notebook suivant montre comment analyser et visualiser les métriques vLLM persistantes :

Notebook de métriques de service LLM personnalisées

Ouvrir le notebook dans un nouvel onglet Ouvrir dans Databricks

Exemple de Notebook

Développez et testez le modèle dans un Notebook GPU Serverless, puis Log et déployez la même configuration en tant qu'Endpoint de service. Le Notebook suivant contient le flux exécutable complet de ce guide.

Notebook de démarrage pour le service de LLM personnalisé

Ouvrir le notebook dans un nouvel onglet Ouvrir dans Databricks

Limitations

Les limitations suivantes s'appliquent pendant la phase Bêta.

GPU_XLARGE Les endpoints (1xH100) sont disponibles uniquement dans us-west-2 et nécessitent une inscription supplémentaire auprès de votre équipe de compte Databricks. Ils n'activent pas la mise à l'échelle vers zéro pendant la phase Bêta.
Pas de mise à l’échelle automatique entre les répliques. La mise à zéro est prise en charge sur tous les types de GPU, à l’exception de GPU_XLARGE. Voir Scale-to-zero et planification de la capacité pour les mises en garde concernant la capacité du fournisseur de cloud.
Seules les tâches de discussion (llm/v1/chat, y compris multimodales) et d'embeddings (llm/v1/embeddings) sont prises en charge. Consultez les tâches prises en charge.
Aucune optimisation des itinéraires.
Pas d'interface utilisateur pour visualiser les Logs ou les métriques. Interroger la télémétrie directement dans Unity Catalog.

Contactez l'équipe de votre compte Databricks pour tout commentaire ou question.

L'upload d'artefacts expire lors de l'enregistrement

Lorsque vous enregistrez le modèle avec env_pack, Databricks upload les poids et l’environnement du modèle empaqueté en tant qu’artefacts (model_version.tar et model_environment.tar). Avec les versions databricks-sdk antérieures à 0.102.0, l'upload d'artefacts LLM volumineux peut expirer après cinq minutes et échouer à l'enregistrement avec une erreur telle que la suivante :

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

Pour corriger cela, mettez à niveau vers databricks-sdk>=0.102.0 et réenregistrez le modèle :

Python
%pip install databricks-sdk>=0.102.0

Quand utiliser le service LLM personnalisé​

Exigences​

Étape 1 : Configurez votre environnement​

Étape 2 : download votre modèle​

Étape 3 : Testez le modèle localement avec vLLM​

Étape 4 : Log le modèle avec un point d'entrée personnalisé​

Tâches prises en charge​

Étape 5 : Enregistrer le modèle dans Unity Catalog​

Étape 6 : Créer un Endpoint de service​

Dimensionnement à zéro et planification de la capacité​

Étape 7 : Interrogez votre Endpoint.​

Surveiller votre endpoint​

Logs en direct​

Logs persistants et métriques​

Query des données de télémétrie​