Atender LLMs personalizados com o Serviço de Modelo Personalizado

Esta página mostra como implantar LLMs (modelos de linguagem grandes) personalizados no Model Serving usando um mecanismo vLLM . Use esse fluxo de trabalho para atender a modelos ajustados, variantes PEFT, modelos multimodal e outros modelos de base que não estão disponíveis nas APIs do Foundation Model (FMAPI). O bloco de anotações inicial no final desta página contém todo o código executável para as etapas a seguir.

Quando usar o serviço LLM personalizado

Azure Databricks recomenda o serviço llm personalizado quando você tiver um dos seguintes casos de uso:

• Modelos totalmente refinados com pesos personalizados que você treinou no Azure Databricks.
• Modelos do Hugging Face que não estão disponíveis na FMAPI.
• Receitas PEFT personalizadas que o FMAPI não dá suporte.
• Modelos especializados fora do catálogo FMAPI, como MedGemma.
• Modelos multimodal (linguagem visual), como Qwen/Qwen2.5-VL-3B-Instruct.
• Inserindo modelos que não estão disponíveis no FMAPI, como nomic-ai/nomic-embed-text-v2-moe.
• Qualquer modelo que se ajuste a um 1xH100 (80 GB de memória gpu).

Requirements

• O serviço LLM personalizado está em Beta. Os administradores do workspace podem habilitar ou desativar esse recurso na página Visualizações . Consulte Gerenciar visualizações do Azure Databricks.

• Computação de GPU sem servidor. Uma GPU A10 é o ambiente de desenvolvimento recomendado para modelos menores, H100 para modelos maiores.

• MLflow 3.12 ou superior e databricks-sdk>=0.102.0. Os pinos mlflow==3.12.0 do notebook inicial e uma versão compatível do SDK. Se você criar seu próprio ambiente, corresponda a essas versões. Versões anteriores do SDK podem demorar ao carregar artefatos de modelo durante o registro. Veja o tempo limite de carregamento do Artefato durante o registro.

Etapa 1: Configurar seu ambiente

Crie um notebook na computação de GPU sem servidor com uma GPU A10. Instale a vLLM e suas dependências. O notebook inicial fixa uma versão testada do vLLM.

Você também pode especificar dependências por meio de um ambiente sem servidor em vez de usar %pip install.

Etapa 2: Baixar seu modelo

Baixe os pesos de modelo do Hugging Face com snapshot_download. O bloco de anotações inicial usa Qwen/Qwen3-4B como exemplo, mas você pode substituir qualquer modelo que se ajuste ao orçamento de memória da GPU selecionada, incluindo o seguinte:

• Modelos multimodal, como Qwen/Qwen2.5-VL-3B-Instruct para casos de uso de linguagem visual.
• Modelos maiores que se encaixam em 1xH100, como openai/gpt-oss-120b.

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

Etapa 3: Testar o modelo localmente com vLLM

Antes de implantar, teste o modelo diretamente em seu notebook de GPU sem servidor iniciando um servidor vLLM local. Os testes locais permitem verificar o modelo, experimentar com os parâmetros do vLLM e solucionar problemas antes de criar um endpoint de serviço.

Principais coisas a saber:

• A computação de GPU sem servidor permite apenas as portas 3000 a 3999 para testes locais. Selecione uma porta dentro desse intervalo; o notebook inicial usa 3080.
• O servidor vLLM expõe uma API compatível com OpenAI em /invocations.
• Você pode testar solicitações regulares e de streaming.
• Ajuste parâmetros como --dtype, --max-model-lene --gpu-memory-utilization para seu modelo.
• Adicione --enforce-eager para uma inicialização mais rápida, ao custo de parte do desempenho de inferência.
• Para modelos maiores, use uma variante de GPU sem servidor H100 para testes locais.

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

Etapa 4: Registrar o modelo com um ponto de entrada personalizado

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

• task deve ser "llm/v1/chat" (modelos de chat, incluindo os multimodais) ou "llm/v1/embeddings" (modelos de embedding). Consulte as tarefas com suporte.
• O ponto de entrada deve ser aberto na porta 8080, a porta esperada pelo Model Serving.
• O comando de ponto de entrada deve espelhar o que você testou na Etapa 3, com a porta 8080 em vez da porta local.
• O ponto de entrada é iniciado da pasta de artefatos do modelo MLflow, portanto, os caminhos de modelo são relativos a essa pasta.

Para um modelo de 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"
    ),
}

Para um modelo de inserção, defina task"llm/v1/embeddings" e inicie o servidor no modo de inserção. Com a versão da vLLM usada aqui, ou seja --runner pooling , (versões mais antigas da vLLM usam --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"
    ),
}

Registre o modelo com mlflow.pyfunc.log_model e passe o metadata dicionário que você definiu como argumento metadata . A python_model classe ChatModel base tipifica o modelo registrado como um modelo de chat.

Servir executa seu ponto de entrada em vez do método do predict modelo, então predict nunca é chamado e pode devolver um resultado vazio. Aponte artifacts para a pasta que contém seus pesos baixados e faça mlflow o pinho com extra_pip_requirements para combinar com seu caderno:

import mlflow
from mlflow.pyfunc.model import ChatModel, ChatCompletionResponse

# ChatModel types this as a chat model; serving runs the entrypoint, so predict is never called.
class LLMModel(ChatModel):
    def predict(self, context, messages, params):
        return ChatCompletionResponse.from_dict({"choices": []})

model_info = mlflow.pyfunc.log_model(
    name="qwen",
    python_model=LLMModel(),
    artifacts={"model_dir": "qwen3"},
    metadata=metadata,
    extra_pip_requirements=["mlflow==3.12.0"],
)
model_info.model_uri

Tarefas com suporte

O task que você declara deve corresponder ao que seu ponto de entrada realmente fornece: o ponto de entrada precisa expor, na porta 8080, a API compatível com a OpenAI para essa tarefa. Os exemplos acima usam vLLM, mas qualquer servidor que atenda a esse contrato funciona. Outros tipos de tarefa, como llm/v1/completions, não têm suporte.

Etapa 5: Registrar o modelo no Catálogo do Unity

Registre o modelo no Catálogo do Unity usando mlflow.register_model. O fornecimento de LLM personalizado baseia-se em implantações express, portanto o registro usa o parâmetro env_pack="databricks_model_serving" e requer mlflow>=3.12 e databricks-sdk>=0.102.0.

Por exemplo, adicione o seguinte ao bloco de anotações:

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

Etapa 6: Criar um ponto de extremidade do serviço

Crie o endpoint pela interface do usuário ou programaticamente com o SDK do Azure Databricks. As principais decisões 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 em seu modelo e nuvem:

workload_size (Small, Medium ou Large) define o número de réplicas provisionadas por trás do endpoint. Use Small para cargas de trabalho de desenvolvimento e de baixo tráfego.

O exemplo a seguir 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,
)

Escalonamento até zero e planejamento de capacidade

O serviço de LLM personalizado na versão beta provisiona um número fixo de réplicas por trás do seu ponto de extremidade. Ainda não há suporte para dimensionamento automático entre mais de zero réplicas, portanto, você deve dimensionar workload_type e workload_size para o tráfego de pico. O ponto de extremidade enfileira as solicitações que excedem a capacidade de réplicas provisionadas.

Defina scale_to_zero_enabled=True para permitir que o endpoint reduza para zero réplicas quando estiver ocioso. As inicializações a frio são lentas – carregar pesos de modelo e iniciar o vLLM normalmente leva 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 seu tráfego de pico com antecedência.

Etapa 7: Consultar seu ponto de extremidade

Depois que o ponto de extremidade estiver pronto, ele aparecerá automaticamente no Playground de IA na página do ponto de extremidade. Você também pode consultá-lo programaticamente usando o SDK do Databricks, o SDK do OpenAI ou o curl.

Modelos de chat (llm/v1/chat):

SDK do Databricks

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

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

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

Inserindo modelos (llm/v1/embeddings):

SDK de OpenAI

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

curl

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

Alguns modelos de embeddings esperam um prefixo específico para a tarefa em cada entrada (por exemplo, nomic-embed-text-v2-moe usa search_query: e search_document:). Consulte a documentação do seu modelo para verificar as convenções de entrada.

Monitore seu endpoint

O serviço de LLM personalizado usa a mesma infraestrutura de observabilidade que os pontos de extremidade de serviço de modelo personalizado padrão, mas com alguns recursos adicionais específicos de vLLM descritos nas seções a seguir.

Logs dinâmicos

A guia Logs da página do ponto de extremidade na IU de Serviços mostra stdout e stderr do seu processo do vLLM em tempo real. Você também pode abrir essa saída por meio da API de logs.

Logs e métricas persistidos

Quando a telemetria está habilitada, logs e métricas são armazenados de forma persistente em tabelas Delta do Unity Catalog para retenção de longo prazo, consultas SQL e conformidade. Consulte Persistir dados do serviço de modelo personalizado no Catálogo do Unity para obter instruções completas de configuração, requisitos e esquemas de tabela.

Para o serviço de LLM personalizado especificamente:

• Logs: stdout e stderr do processo vLLM são capturados automaticamente. Não é necessário nenhum código de logging no aplicativo.
• Métricas: o Azure Databricks coleta automaticamente métricas do endpoint do Prometheus /metrics do servidor vLLM e as armazena juntamente com os logs. Por padrão, você obtém latência por requisição, taxa de transferência, contagem de tokens, profundidade da fila e utilização do cache KV.

Consultar dados de telemetria

Durante o Beta, não há nenhuma interface do usuário para visualizar logs ou métricas. Consulte os dados persistentes diretamente no Catálogo do Unity usando SQL ou um notebook. Consulte os esquemas de métrica e de log documentados em Persistir dados do serviço de modelo personalizado no Catálogo do Unity.

O notebook a seguir mostra como analisar e visualizar as métricas de vLLM persistentes:

Notebook de métricas do serviço de LLM personalizado

Obter laptop

Caderno de exemplo

Desenvolva e teste o modelo em um notebook com GPU sem servidor e, em seguida, registre em log e implante a mesma configuração que um ponto de extremidade de serviço. O notebook a seguir contém o fluxo executável completo deste guia.

Notebook inicial do serviço de LLM personalizado

Obter laptop

Limitações

As limitações a seguir se aplicam durante o Beta.

• Sem escalonamento automático das réplicas. Há suporte ao escalonamento até zero.
• Somente as tarefas de chat (llm/v1/chatincluindo multimodal) e inserções (llm/v1/embeddings) têm suporte. Consulte as tarefas com suporte.
• Nenhuma otimização de rota.
• Nenhuma interface do usuário para visualizar logs ou métricas. Consultar a telemetria diretamente no Catálogo do Unity.

Entre em contato com sua equipe de conta Azure Databricks para obter comentários ou perguntas.

O upload de artefatos expira durante o registro

Quando você registra o modelo com env_pack, o Azure Databricks faz upload dos pesos do modelo empacotado e do ambiente como artefatos (model_version.tar e model_environment.tar). Com versões do databricks-sdk anteriores a 0.102.0, o carregamento de artefatos grandes de LLM pode expirar após cinco minutos e fazer com que o registro falhe com um erro como o seguinte:

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

Para corrigir isso, atualize databricks-sdk>=0.102.0 e registre novamente o modelo:

%pip install databricks-sdk>=0.102.0