Distribuisci LLM personalizzati con il serving di modelli personalizzati

Questa pagina mostra come servire il proprio LLM su un endpoint GPU Model Serving . Qualsiasi modello che vLLM esegue diventa un endpoint di produzione con un'API compatibile con OpenAI. Ecco come funziona:

• Esegui il server di inferenza, come vLLM, e scegli la sua versione e le impostazioni.
• Testi il server in un notebook AI Runtime . Un flag sbagliato o un errore di esaurimento di memoria si manifestano in pochi secondi invece che dopo un deployment.
• Distribuisci lo stesso comando e ambiente che hai costruito e che sai che funziona su un endpoint di servizio di produzione.

Quickstart

Importa il seguente notebook nel tuo workspace e clicca su Esegui tutto su AI Runtime con una GPU A10. In circa 15 minuti hai un endpoint Qwen3.5-4B che risponde alle richieste di chat compatibili con OpenAI.

Esegui Qwen3.5-4B con vLLM

Ottieni il notebook

Quando usare la gestione LLM personalizzata

Utilizzare un servizio LLM personalizzato nei seguenti casi:

• Hai affinato un LLM su AI Runtime e vuoi distribuirlo. Vedi la sezione qui sotto per un esempio.
• Vuoi servire un modello aperto che Foundation Model API (FMAPI) non supporta, come un nuovo LLM, un modello speech-to-text o un modello di embedding.
• Vuoi cambiare il runtime o l'architettura di un LLM e hai bisogno di controllare il runtime e l'ambiente.

Non utilizzare il serving personalizzato dell'LLM nei seguenti casi:

• FMAPI fornisce il modello di cui hai bisogno, inalterato. FMAPI è più semplice da usare e altamente ottimizzato.
• Il modello non entra su una singola GPU con circa 80 GB di memoria. Ad esempio, Qwen3.8-27B e gpt-oss-120b entrano, ma Kimi K3 e GLM 5.3 no.
• Hai bisogno di throughput o prezzo per token di livello frontier senza ottimizzazione. Le prestazioni sono in linea con vLLM open source sulla stessa GPU.

Requirements

Il servizio su LLM personalizzato ha i seguenti requisiti:

• Il tuo spazio di lavoro deve avere AI Runtime.
• Devi registrare il modello da un notebook AI Runtime. Un modello registrato da un ambiente CPU impacchetta le dipendenze della CPU e l'endpoint GPU non si avvia.
• Devi avere il permesso di creare modelli in uno schema del Catalogo Unity.
• Devi registrare il modello con env_pack="databricks_model_serving". Il serving LLM personalizzato è costruito su deployment express, che impacchettano l'ambiente del notebook con il modello.
• Devi usare MLflow 3.12 o superiore e databricks-sdk MLServer 0.102.0 o superiore. L'ambiente AI v6 include entrambi.

Notebook introduttivi

Ogni notebook porta un modello da Hugging Face a un endpoint, come il quickstart. Eseguine uno così com'è, oppure parti da uno per distribuire il tuo modello.

AI v6 e Standard v6 sono ambienti Runtime AI. AI v6 è fornito con vLLM, PyTorch, Transformers e altri pacchetti di machine learning comuni preinstallati e pronti all'uso. Consulta la lista dei pacchetti AI v6. Un notebook Standard v6 installa vLLM da solo, quindi puoi scegliere quale versione di vLLM usare. Usa un notebook Standard v6 quando il tuo modello ha bisogno di un vLLM o di trasformers più recenti rispetto a quelli inclusi nell'AI v6, come con Muse Glimmer.

Distribuisci il tuo modello

Per servire un altro modello, scegli il notebook iniziale con la stessa attività e la GPU di cui il tuo modello ha bisogno. Cambia MODEL_REPO_ID e le flag in vllm_command, poi esegui il notebook. Ogni notebook segue i seguenti passaggi:

1. Scarica i pesi modello da Hugging Face, oppure ottenli da un checkpoint di allenamento.
2. Avvia vLLM nel notebook e interrogalo.
3. Esegui il log del modello con il comando vLLM come punto di ingresso e registralo nel Catalogo Unity come deployment express.
4. Crea un endpoint di servizio, che avvia lo stesso comando.
5. Consulta l'endpoint con il client OpenAI, l'SDK Databricks o SQL ai_query.

Nell'esempio seguente, il metadata del modello ospita il compito e il punto di ingresso:

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

Distribuire un modello finemente calibrato

Ottimizza un modello su AI Runtime e servilo dallo stesso notebook. Per un esempio, vedi Supervised fine-tuning (Full) e serving di Qwen3.5-0.8B. Il tutorial affina Qwen3.5-0.8B su un singolo H100, confronta le risposte prima e dopo l'addestramento, e serve il modello fine-tuned.

Attività supportate

Il task nei metadati del modello imposta l'API servita dall'endpoint. Il tuo server deve esporre l'API compatibile OpenAI per quel compito. Altri compiti, come llm/v1/completions, non sono supportati. La tabella seguente elenca i compiti supportati.

Scegli una GPU

Azure Databricks consiglia di sviluppare sulla stessa GPU su cui distribuisci il modello, quindi le impostazioni che testi sono quelle che distribuisci. La tabella seguente elenca le GPU per il servizio personalizzato di LLM.

Problemi comuni

I seguenti problemi sono i più comuni quando cambi un portatile:

• Il download fallisce in /Workspace, che non accetta file da più GB. Scarica i pesi su disco locale, come fanno i notebook iniziali.
• Il server locale non si avvia. I notebook AI Runtime permettono solo porte da 3000 a 3999, quindi prova su una di queste porte. Solo il punto di ingresso usa la porta 8080, e altrimenti deve corrispondere al comando che hai testato.
• L'endpoint non riesce a trovare i pesi. L'entrypoint viene eseguito nella cartella degli artefatti del modello, quindi --model deve indicare la cartella dei pesi che hai salvato come artefatto.
• Un modello di embedding non fornisce embedding. Avvia vLLM con --runner pooling.
• La registrazione fallisce con TimeoutError('Timed out after 0:05:00') durante il caricamento di model_version.tar o model_environment.tar. Aggiorna a databricks-sdk 0.102.0 o superiore e registra di nuovo il modello.

Creare un endpoint

Crea l'endpoint dall'interfaccia di servizio o con l'SDK Databricks, come fanno i notebook iniziali. workload_type sceglie la GPU, e workload_size (Small, Medium, o Large) stabilisce il numero di repliche.

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

Scalabilità fino a zero e capacità

Attualmente gli endpoint LLM personalizzati non si ridimensionano automaticamente in modo dinamico, quindi dimensionali workload_size in base al traffico di picco.

Con la scala a zero, un endpoint inattivo arresta tutte le repliche. La richiesta successiva aspetta da uno a diversi minuti mentre il vLLM carica di nuovo il modello e tutte le repliche si avviano. Azure Databricks consiglia di disattivare la scala a zero per il traffico di produzione.

Interroga il tuo endpoint

Un endpoint di chat pronto appare nell'AI Playground. I seguenti esempi interrogano un endpoint con l'SDK Databricks, il client OpenAI e REST.

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

Alcuni modelli di incorporamento si aspettano un prefisso su ogni input, come search_query: o search_document:. Controlla la scheda del modello.

Monitora il tuo endpoint

La scheda Log dell'endpoint mostra stdout e stderr del tuo server in tempo reale. L'API dei log restituisce lo stesso output.

Azure Databricks inoltra le metriche del server vLLM e le traccia nella scheda Metrics dell'endpoint:

• Latenza: tempo al primo token, tempo per token di output, latenza della richiesta e tempo di coda.
• Caricamento: richieste in corso e in attesa.
• Cache KV: utilizzo e percentuale di hit.
• Throughput: token di prompt e generazione al secondo.

L'API export metrics restituisce le stesse metriche in formato Prometheus, quindi puoi raccoglierle tramite scraping in Prometheus o Datadog.

Con la telemetria attivata, Azure Databricks salva anche i log del server e le metriche Prometheus del vLLM nelle tabelle del catalogo Unity, così puoi interrogarle su periodi più lunghi. Vedere Rendere persistenti i dati del modello personalizzato nel catalogo unity.

Pricing

Paghi per ogni ora di istanza GPU, lo stesso che per altri servizi GPU di serving di modelli personalizzati. Vedi prezzi di Model Serving.

Limitazioni e disponibilità in base all'area geografica

Esegui il logging di un LLM personalizzato da AI Runtime, quindi l’erogazione di LLM personalizzati è disponibile nelle stesse regioni del calcolo GPU serverless. Quelle sono regioni USA su AWS e Azure. GCP non è supportato.

Le seguenti funzionalità arriveranno presto:

• Adattatori LoRA.
• Servizio tra aree geografiche.
• Registrazione dei modelli al di fuori di AI Runtime, ad esempio da Databricks Runtime o CPU serverless.

Le funzionalità seguenti non sono supportate:

• Routing consapevole della cache KV.
• Ottimizzazione delle rotte.