Disponibilize LLMs personalizados com o Custom Model Serving

Esta página mostra-lhe como implementar modelos de linguagem (LLMs) personalizados no Model Serving usando um motor vLLM . Utilize este fluxo de trabalho para servir modelos finamente ajustados, variantes do PEFT, modelos multimodais e outros modelos de fundação que não estejam disponíveis nas APIs do Modelo Foundation (FMAPI). O caderno inicial no final desta página contém todo o código executável para os passos seguintes.

Quando usar serviço personalizado para LLM

O Azure Databricks recomenda o serviço de LLM personalizado quando tem um dos seguintes casos de uso:

• Modelos totalmente afinados com pesos personalizados que treinaste no Azure Databricks.
• Modelos da Hugging Face que não estão disponíveis em FMAPI.
• Receitas personalizadas de PEFT que o FMAPI não suporta.
• Modelos especializados fora do catálogo FMAPI, como o MedGemma.
• Modelos multimodais (visão-linguagem) como Qwen/Qwen2.5-VL-3B-Instruct.
• Qualquer modelo que caba numa 1xH100 (80 GB de memória GPU).

Requirements

• O serviço personalizado de LLM está em Beta. Os administradores do espaço de trabalho podem ativar ou desativar esta funcionalidade a partir da página de Pré-visualizações . Ver Gerir as pré-visualizações de Azure Databricks.

• Computação sem servidor com GPU. Uma GPU A10 é o ambiente de desenvolvimento recomendado para modelos mais pequenos, enquanto a H100 para modelos maiores.

• MLflow 3.12 ou superior. Os pinos mlflow==3.12.0do caderno inicial . Se criares o teu próprio ambiente, utiliza esta versão.

Passo 1: Configura o teu ambiente

Crie um caderno com computação GPU sem servidor com uma GPU A10. Instala o vLLM e as suas dependências. O notebook inicial fixa uma versão testada do vLLM.

Também pode especificar dependências num ambiente sem servidor em vez de usar %pip install.

Passo 2: Descarregue o seu modelo

Descarregue os pesos dos modelos do Hugging Face com snapshot_download. O portátil inicial usa Qwen/Qwen3-4B como exemplo, mas pode substituir qualquer modelo que se ajuste ao orçamento de memória da GPU selecionada, incluindo o seguinte:

• Modelos multimodais, como Qwen/Qwen2.5-VL-3B-Instruct para casos de uso em linguagem de visão.
• Modelos maiores que cabem numa H100, como openai/gpt-oss-120b.

Selecione uma GPU com base nas necessidades de memória e desempenho do seu modelo.

Passo 3: Testar o modelo localmente com vLLM

Antes de implementares, testa o modelo diretamente no teu portátil GPU serverless, lançando um servidor vLLM local. Testes locais permitem-lhe verificar o modelo, experimentar parâmetros de vLLM e resolver problemas antes de criar um endpoint de serviço.

Coisas importantes a saber:

• A computação de GPU serverless permite apenas as portas 3000–3999 para testes locais. Selecione uma porta nesse intervalo; o notebook inicial utiliza 3080.
• O servidor vLLM expõe uma API compatível com OpenAI em /invocations.
• Podes testar tanto pedidos normais como de streaming.
• Ajuste parâmetros como --dtype, --max-model-len, e --gpu-memory-utilization para o seu modelo.
• Adiciona --enforce-eager para um arranque mais rápido, à custa de algum desempenho de inferência.
• Para modelos maiores, use uma variante de GPU serverless H100 para testes locais.

Quando estiver satisfeito com a configuração, pare o servidor local antes de continuar.

Passo 4: Registar o modelo com um ponto de entrada personalizado

Esta etapa liga a sua configuração local ao Model Serving e tem os seguintes requisitos de configuração:

• O task deve ser "llm/v1/chat".
• O ponto de entrada deve abrir-se na porta 8080, a porta que a Model Serving espera.
• O comando de entrada tem de espelhar o que testaste no Passo 3, com a porta 8080 em vez da porta local.
• O ponto de entrada arranca a partir da pasta de artefactos do modelo MLflow, por isso os caminhos dos modelos são relativos a essa pasta.

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

Passo 5: Registar o modelo no Unity Catalog

Registe o modelo no Unity Catalog usando mlflow.register_model. A disponibilização de LLMs personalizados depende de implementações rápidas. Usa o env_pack="databricks_model_serving" parâmetro para o ativar.

Por exemplo, adicione o seguinte ao seu caderno:

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

Passo 6: Criar um endpoint de serviço

Cria o endpoint a partir da interface ou programaticamente com o Azure Databricks SDK. As decisões-chave são o tipo de computação, o tamanho da carga de trabalho e o comportamento de escala para zero.

Selecione um workload_type com base no seu modelo e na nuvem:

workload_size (Small, Medium, ou Large) controla o número de réplicas provisionadas atrás do ponto final. Utilize Small para desenvolvimento e cargas de trabalho com pouco tráfego.

O exemplo seguinte mostra uma configuração típica:

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

Redução para zero e planeamento da capacidade

Um LLM personalizado que serve em Beta fornece um número fixo de réplicas atrás do seu endpoint. O dimensionamento automático para mais de zero réplicas ainda não é suportado, por isso tem de dimensionar workload_type e workload_size para o seu tráfego de pico. O endpoint coloca em fila pedidos que excedam a capacidade das réplicas provisionadas.

Defina scale_to_zero_enabled=True para permitir que o endpoint reduza para zero réplicas quando estiver ocioso. Os arranques a frio são lentos — carregar os pesos do modelo e iniciar o vLLM normalmente demora de um a vários minutos.

Para cargas de trabalho sensíveis à latência ou críticas para a produção, defina scale_to_zero_enabled=False e dimensione workload_size para o seu pico de tráfego à partida.

Passo 7: Consulte o seu endpoint

Depois de o endpoint estar pronto, ele aparece automaticamente no AI Playground a partir da página do endpoint. Também pode consultá-lo programaticamente usando o SDK Databricks, o SDK OpenAI ou curl.

Databricks SDK

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

curl

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

Monitorize o seu endpoint

A disponibilização personalizada de LLM utiliza a mesma infraestrutura de observabilidade que os endpoints padrão de disponibilização de modelos personalizados, mas com algumas funcionalidades adicionais específicas do vLLM descritas nas secções seguintes.

Registos em tempo real

O separador Logs da página do endpoint na interface de utilizador de Serving mostra stdout e stderr do teu processo vLLM em tempo real. Também pode abrir esta saída através da API de logs.

Registos e métricas persistentes

Quando a telemetria está ativada, tanto os logs como as métricas são mantidos para as tabelas Delta do Unity Catalog para retenção a longo prazo, consulta SQL e conformidade. Consulte Persistir modelo personalizado que serve dados ao Catálogo Unity para instruções completas de configuração, requisitos e esquemas de tabela.

Para LLM personalizados que servem especificamente:

• Os registos: stdout e stderr do processo vLLM são capturados automaticamente. Não é necessário código de registo do lado da aplicação.
• Métricas: o Azure Databricks recolhe automaticamente métricas a partir do ponto de extremidade Prometheus /metrics do servidor vLLM e armazena-as de forma persistente juntamente com os registos. Por defeito, obtém latência por pedido, throughput, contagem de tokens, profundidade da fila e utilização do cache KV.

Consultar dados de telemetria

Durante a Beta, não existe interface para visualizar logs ou métricas. Consulta os dados persistentes diretamente no Unity Catalog usando SQL ou um caderno. Veja os esquemas métricos e logaristas documentados no modelo personalizado Persist que servem dados ao Unity Catalog.

O caderno seguinte mostra como analisar e visualizar as métricas vLLM persistentes:

Caderno de métricas de serviço personalizado para LLM

Obter caderno

Bloco de notas de exemplo

Desenvolva e teste o modelo num notebook GPU sem servidor, depois registe e implemente a mesma configuração como um endpoint de serviço. O caderno seguinte contém o fluxo completo executável deste guia.

Notebook inicial para implementação de LLM personalizado

Obter caderno

Limitações

As seguintes limitações aplicam-se durante a Beta.

• Não há escalabilidade automática entre réplicas. É suportado o escalonamento até zero.
• Apenas a tarefa de chat do LLM (llm/v1/chat) é suportada, incluindo multimodal.
• Sem otimização de rotas.
• Sem interface para visualizar logs ou métricas. Consulta telemetria diretamente no Unity Catalog.

Contacte a sua equipa de contas Azure Databricks para obter feedback ou perguntas.