Distribuisci LLM personalizzati con il serving di modelli personalizzati

Questa pagina illustra come distribuire modelli di linguaggio di grandi dimensioni personalizzati in Model Serving usando un motore vLLM . Usare questo flusso di lavoro per gestire modelli ottimizzati, varianti PEFT, modellimultidimensionali e altri modelli di base non disponibili nelle API del modello di base (FMAPI). Il notebook di avvio alla fine di questa pagina contiene tutto il codice eseguibile per i passaggi seguenti.

Quando usare la gestione LLM personalizzata

Azure Databricks consiglia la gestione LLM personalizzata quando si dispone di uno dei casi d'uso seguenti:

• Modelli completamente ottimizzati con pesi personalizzati sottoposti a training su Azure Databricks.
• Modelli di Hugging Face che non sono disponibili in FMAPI.
• Ricette PEFT personalizzate non supportate da FMAPI.
• Modelli specializzati al di fuori del catalogo FMAPI, ad esempio MedGemma.
• Modelli multimodali (visione-linguaggio) come Qwen/Qwen2.5-VL-3B-Instruct.
• Incorporamento di modelli non disponibili in FMAPI, ad esempio nomic-ai/nomic-embed-text-v2-moe.
• Qualsiasi modello adatto a un modello 1xH100 (80 GB di memoria GPU).

Requirements

• La gestione LLM personalizzata è in versione beta. Gli amministratori dell'area di lavoro possono abilitare o disattivare questa funzionalità dalla pagina Anteprime . Vedere Gestire le anteprime di Azure Databricks.

• Calcolo GPU serverless. Una GPU A10 è l'ambiente di sviluppo consigliato per i modelli più piccoli, H100 per i modelli più grandi.

• MLflow 3.12 o versione successiva e databricks-sdk>=0.102.0. I pin mlflow==3.12.0 del notebook di avvio e una versione compatibile dell'SDK. Se si crea un ambiente personalizzato, assicurarsi che corrisponda a queste versioni. Le versioni precedenti dell’SDK possono andare in timeout durante il caricamento degli artefatti del modello in fase di registrazione. Vedere Timeout del caricamento degli artefatti durante la registrazione.

Passaggio 1: Configurare l'ambiente

Crea un notebook su una piattaforma di calcolo GPU serverless con una GPU A10. Installare vLLM e le relative dipendenze. Il notebook di avvio aggiunge una versione vLLM testata.

È anche possibile specificare le dipendenze tramite un ambiente serverless anziché usare %pip install.

Passaggio 2: Scaricare il modello

Scaricare i pesi del modello da Hugging Face con snapshot_download. Il notebook di avvio usa Qwen/Qwen3-4B come esempio, ma è possibile sostituire qualsiasi modello che soddisfi il budget di memoria della GPU selezionato, inclusi i seguenti:

• Modelli multimodali come Qwen/Qwen2.5-VL-3B-Instruct per casi d'uso visione-linguaggio.
• Modelli più grandi che si adattano a 1xH100, ad esempio openai/gpt-oss-120b.

Selezionare una GPU in base alle esigenze di memoria e prestazioni del modello.

Passaggio 3: Testare il modello in locale con vLLM

Prima di eseguire la distribuzione, testare il modello direttamente nel notebook GPU serverless avviando un server vLLM locale. Il test locale consente di verificare il modello, sperimentare i parametri vLLM e risolvere i problemi prima di creare un endpoint di gestione.

Aspetti chiave da conoscere:

• L'elaborazione serverless con GPU consente di usare solo le porte 3000–3999 per i test locali. Selezionare una porta in tale intervallo; il notebook di avvio usa 3080.
• Il server vLLM espone un'API compatibile con OpenAI all'indirizzo /invocations.
• È possibile testare sia le richieste regolari che le richieste di streaming.
• Ottimizza parametri come --dtype, --max-model-len e --gpu-memory-utilization del modello.
• Aggiungere --enforce-eager per l'avvio più veloce, a costo di alcune prestazioni di inferenza.
• Per i modelli di dimensioni maggiori, usare una variante GPU serverless H100 per i test locali.

Quando si è soddisfatti della configurazione, arrestare il server locale prima di procedere.

Passaggio 4: Registrare il modello con un punto di ingresso personalizzato

Questo passaggio connette la configurazione locale a Model Serving e presenta i requisiti di configurazione seguenti:

• task deve essere "llm/v1/chat" (modelli di chat, inclusi i modelli multimodali) o "llm/v1/embeddings" (modelli di embedding). Vedere Attività supportate.
• Il punto di ingresso deve essere aperto sulla porta 8080, la porta prevista da Model Serving.
• Il comando del punto di ingresso deve eseguire il mirroring di quanto testato nel passaggio 3, con la porta 8080 anziché la porta locale.
• Il punto di ingresso viene avviato dalla cartella artefatti del modello MLflow, quindi i percorsi del modello sono relativi a tale cartella.

Per un modello di chat:

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

Per un modello di embedding, imposta task su "llm/v1/embeddings" e avvia il server in modalità embedding. Con la versione vLLM usata qui, ovvero --runner pooling le versioni precedenti di vLLM usano --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"
    ),
}

Attività supportate

L'elemento task dichiarato deve corrispondere a quello effettivamente usato dal punto di ingresso: il punto di ingresso deve esporre l'API compatibile con OpenAI per tale attività sulla porta 8080. Gli esempi precedenti usano vLLM, ma tutti i server che soddisfano questo contratto funzionano. Altri tipi di attività, ad esempio llm/v1/completions, non sono supportati.

Passaggio 5: Registrare il modello nel catalogo unity

Registrare il modello in Unity Catalog usando mlflow.register_model. La gestione LLM personalizzata dipende dalle distribuzioni rapide. Usare il env_pack="databricks_model_serving" parametro per abilitarlo.

Ad esempio, aggiungere quanto segue al notebook:

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

Passaggio 6: Creare un endpoint di gestione

Creare l'endpoint dall'interfaccia utente o a livello di codice con Azure Databricks SDK. Le decisioni chiave sono il tipo di calcolo, le dimensioni del carico di lavoro e il comportamento da scala a zero.

Seleziona un workload_type in base al modello e al cloud:

workload_size (Small, Medium o Large) determina il numero di repliche di cui è stato effettuato il provisioning dietro l'endpoint. Usa Small per carichi di lavoro di sviluppo e a basso traffico.

L'esempio seguente illustra una configurazione tipica:

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

Ridimensionamento a zero e pianificazione della capacità

La gestione LLM personalizzata in Beta effettua il provisioning di un numero fisso di repliche dietro l'endpoint. La scalabilità automatica tra più di zero repliche non è ancora supportata, quindi è necessario ridimensionare workload_type e workload_size per il traffico di picco. L'endpoint accoda le richieste che superano la capacità delle repliche sottoposte a provisioning.

Impostare scale_to_zero_enabled=True per consentire all'endpoint di ridimensionarsi fino a zero repliche quando è inattivo. Gli avvii a freddo sono lenti: il caricamento dei pesi del modello e l'avvio di vLLM richiede in genere uno o più minuti.

Per i carichi di lavoro sensibili alla latenza o critici per la produzione, imposta scale_to_zero_enabled=False e dimensiona workload_size in base ai picchi di traffico fin da subito.

Passaggio 7: Interroga il tuo endpoint

Dopo che l'endpoint è pronto, viene visualizzato automaticamente in AI Playground dalla pagina dell'endpoint. È anche possibile eseguire query a livello di codice usando Databricks SDK, OpenAI SDK o curl.

Modelli di chat (llm/v1/chat):

SDK Databricks

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

curva

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

Incorporamento di modelli (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."],
)

curva

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 prevedono un prefisso specifico dell'attività per ogni input( ad esempio, nomic-embed-text-v2-moe usa search_query: e search_document:). Controllare la scheda del modello per individuare le relative convenzioni di input.

Monitora il tuo endpoint

La gestione LLM personalizzata usa la stessa infrastruttura di osservabilità dei modelli personalizzati standard che gestisce gli endpoint, ma con alcune funzionalità aggiuntive specifiche di vLLM descritte nelle sezioni seguenti.

Log in tempo reale

La scheda Log della pagina dell'endpoint nell'interfaccia utente di gestione mostra stdout e stderr dal processo vLLM in tempo reale. È anche possibile aprire questo output tramite l'API logs.

Log e metriche persistenti

Quando la telemetria è abilitata, i log e le metriche vengono resi persistenti nelle tabelle Delta del catalogo Unity per la conservazione a lungo termine, le query SQL e la conformità. Per istruzioni, requisiti e schemi di tabella completi, vedere Rendere persistenti i dati del modello personalizzato che gestisce i dati in Unity Catalog .

Per la gestione LLM personalizzata in modo specifico:

• Log: stdout e stderr dal processo vLLM vengono acquisiti automaticamente. Non è necessario alcun codice di registrazione sul lato applicazione.
• Metrics: Azure Databricks elimina automaticamente l'endpoint Prometheus del server vLLM /metrics e mantiene le metriche insieme ai log. Per impostazione predefinita, si ottengono la latenza per richiesta, il throughput, il numero di token, la profondità della coda e l'utilizzo della cache KV.

Interrogazione dei dati di telemetria

Durante la versione beta non è disponibile alcuna interfaccia utente per la visualizzazione di log o metriche. Interroga direttamente i dati persistenti in Unity Catalog tramite SQL o un notebook. Consultare gli schemi di metriche e log documentati in Salvare in modo persistente i dati personalizzati del serving dei modelli in Unity Catalog.

Il notebook seguente illustra come analizzare e visualizzare le metriche vLLM persistenti:

Notebook delle metriche di gestione LLM personalizzato

Ottieni il notebook

Notebook di esempio

Sviluppa e testa il modello in un notebook con GPU serverless, quindi registra e distribuisci la stessa configurazione come endpoint di serving. Il notebook seguente contiene il flusso eseguibile completo di questa guida.

Notebook di avvio per la gestione LLM personalizzato

Ottieni il notebook

Limitations

Le limitazioni seguenti si applicano durante la versione beta.

• Nessuna scalabilità automatica tra repliche. La scalabilità a zero è supportata.
• Sono supportate solo le attività di chat (llm/v1/chat, incluse quelle multimodali) e gli embedding (llm/v1/embeddings). Vedere Attività supportate.
• Nessuna ottimizzazione del percorso.
• Nessuna interfaccia utente per la visualizzazione di log o metriche. Eseguire query sui dati di telemetria direttamente nel catalogo unity.

Rivolgiti al team responsabile del tuo account Azure Databricks per commenti o domande.

Il caricamento degli artefatti va in timeout durante la registrazione

Quando si registra il modello con env_pack, Azure Databricks carica i pesi e l'ambiente del modello in pacchetto come artefatti (model_version.tar e model_environment.tar). Con le versioni di databricks-sdk precedenti a 0.102.0, il caricamento di artefatti LLM di grandi dimensioni può andare in timeout dopo cinque minuti e la registrazione può non riuscire con un errore simile al seguente:

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

Per risolvere il problema, aggiornare a databricks-sdk>=0.102.0 e registrare nuovamente il modello:

%pip install databricks-sdk>=0.102.0