Sirva LLMs personalizados com o Custom Model Serving.

info

Beta

Este recurso está em Beta. Os administradores do espaço de trabalho podem controlar o acesso a esse recurso na página Pré-visualizações . Consulte Gerenciar prévias do Databricks.

Esta página mostra como implantar grandes modelos de linguagem personalizados (LLMs) no Model Serving usando um mecanismo vLLM. Use este fluxo de trabalho para disponibilizar modelos ajustados, variantes PEFT, modelos multimodais e outros modelos de fundação que não estão disponíveis nas APIs do Foundation Model (FMAPI). O notebook de iniciação no final desta página contém todo o código executável para os passos seguintes.

Quando usar a disponibilização de LLM personalizado

Databricks recomenda o serviço de LLM personalizado quando houver um dos seguintes casos de uso:

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

Requisitos

• A disponibilização de LLM personalizado está em Beta. Administradores do workspace podem ativar ou desativar este recurso na página Pré-visualizações . Consulte Gerenciar prévias do Databricks.

• Compute de GPU serverless. Uma GPU A10 é o ambiente de desenvolvimento recomendado para modelos menores, e a H100 para modelos maiores.

• MLflow 3.12 ou acima. O notebook inicial fixa mlflow==3.12.0. Se você criar seu próprio ambiente, corresponda a esta versão.

o passo 1: configurar seu ambiente

Crie um Notebook em compute de GPU serverless com um A10 GPU. Instale o vLLM e suas dependências. O notebook inicial pina uma versão vLLM testada.

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

importante

Defina seu diretório de trabalho para o disco rígido local (por exemplo, usando tempfile.mkdtemp()). O sistema de arquivos /Workspace não oferece suporte a arquivos grandes como pesos de modelo.

O passo 2: downloads seu modelo

Baixar os pesos do modelo do Hugging Face com snapshot_download. O notebook 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 os seguintes:

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

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

GPU	Memória GPU	workload_type
T4	16 GB	GPU_SMALL
A10	24 GB	GPU_MEDIUM
H100	80 GB	GPU_XLARGE

Passo 3: Testar o modelo localmente com vLLM

Antes de implantar, teste o modelo diretamente no seu Notebook de GPU serverless lançando um servidor vLLM local. Testes locais permitem verificar o modelo, experimentar parâmetros vLLM e solucionar problemas antes de criar um endpoint de disponibilização.

Coisas importantes a saber:

• Compute de GPU serverless permite apenas as portas 3000–3999 para teste local. Selecione uma porta nesse intervalo; o notebook inicial usa 3.080.
• O servidor vLLM disponibiliza uma API compatível com OpenAI em /invocations.
• Você pode testar solicitações regulares e de transmissão.
• Ajuste parâmetros como --dtype, --max-model-len e --gpu-memory-utilization para seu modelo.
• Adicione --enforce-eager para um startup mais rápido, ao custo de algum desempenho de inferência.
• Para modelos maiores, use uma variante H100 de GPU serverless para testes locais.

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

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

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

• task deve ser "llm/v1/chat".
• O ponto de entrada deve abrir na porta 8080, a porta que o Model Serving espera.
• O comando de ponto de entrada deve espelhar o que você testou no passo 3, com a porta 8080 em vez da sua porta local.
• O ponto de entrada é iniciado a partir da pasta de artefatos de modelo do MLflow, portanto os caminhos de modelo são relativos a essa pasta.

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

O passo 5: Registre o modelo no Unity Catalog

Registrar o modelo no Unity Catalog usando mlflow.register_model. Serviço de LLM personalizado depende de implantações expressas. Utilize o parâmetro env_pack="databricks_model_serving" para ativá-lo.

Por exemplo, adicione o seguinte ao seu Notebook:

Python

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

O passo 6: Criar um endpoint de serviço

Criar o endpoint da interface do usuário ou programaticamente com o Databricks SDK. As decisões key são o tipo de compute, o tamanho da carga de trabalho e o comportamento de escala para zero.

Selecione um workload_type com base no seu modelo e cloud:

workload_type	GPU	Notas
GPU_SMALL	1x T4 (16 GB)	Menor opção
GPU_MEDIUM	1x A10 (24 GB)	Por default para inferência geral. Corresponde ao ambiente de desenvolvimento do Notebook.
GPU_XLARGE	1x H100 (80 GB), us-west-2	Recomendado para grandes cargas de trabalho de LLM. Requer inscrição; consulte Limitações. Não oferece suporte a escala para zero durante a fase beta.

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

O exemplo a seguir mostra uma configuração típica.

Python

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

Escala para zero e planejamento de capacidade

Serviço LLM personalizado em Beta provisiona um número fixo de réplicas atrás do seu endpoint. O dimensionamento automático entre mais de zero réplicas ainda não é compatível , portanto, é necessário dimensionar workload_type e workload_size para o tráfego de pico. O endpoint enfileira solicitações que excedem a capacidade das réplicas provisionadas.

Configure scale_to_zero_enabled=True para permitir que o endpoint seja dimensionado para zero réplicas quando ocioso. Inicializações a frio são lentas — carregar os pesos do modelo e começar o vLLM geralmente leva de um a vários minutos.

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

atenção

A capacidade de expansão não é garantida. Sempre que o Databricks precisar adquirir uma nova GPU para o seu endpoint — na criação, no aumento de workload_size ou quando um endpoint sai do zero —, a solicitação pode parar de responder se o provedor de nuvem não tiver capacidade de GPU em sua região. Isso se aplica a todos os tipos de GPU, mas é mais restrito para GPU_XLARGE (H100). A Databricks atenua isso com pools aquecidos e pré-reservas, que mantêm a capacidade de GPU disponível e pronta.

GPU_XLARGE (1xH100) endpoints não oferecem suporte a scale_to_zero_enabled=True durante o Beta. A capacidade do H100 é muito limitada para garantir um dimensionamento bem-sucedido a partir de uma inicialização a frio.

O passo 7: Consultar seu endpoint

Após o endpoint estar pronto, ele aparece automaticamente no AI Playground a partir da página do endpoint. Você também pode consultá-lo programaticamente usando o Databricks SDK, o OpenAI SDK ou curl.

Databricks SDK

Python

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

OpenAI SDK

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

curl

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

Monitorar seu endpoint

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

Registros ao vivo

A tab de Logs da página do endpoint na interface do usuário de disponibilização exibe stdout e stderr do seu processo vLLM em tempo real. É possível também abrir este resultado através da API de logs.

Logs e métricas registrados

Quando a telemetria é habilitada, tanto logs quanto métricas são persistidos em tabelas Delta do Unity Catalog para retenção de longo prazo, consultas SQL e compliance. Consulte Persistir dados de servindo modelo personalizados no Unity Catalog para obter instruções completas de configuração, requisitos e esquemas de tabela.

Especificamente para a disponibilização personalizada de LLM:

• Logs: stdout e stderr do processo vLLM são capturados automaticamente. Nenhum código de registro do lado do aplicativo é obrigatório.
• Métricas : O Databricks raspa automaticamente o endpoint Prometheus /metrics do servidor vLLM e persiste as métricas juntamente com os logs. Por padrão, são fornecidos 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 a versão Beta, não há IU para visualização de logs ou métricas. É possível consultar os dados persistidos diretamente no Unity Catalog usando SQL ou um Notebook. Consulte os esquemas de métrica e log documentados em Persista os dados de servindo modelo personalizados para o Unity Catalog.

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

Notebook de métricas de disponibilização de LLM personalizado

Abrir notebook em uma nova aba

Notebook de exemplo

Desenvolver e testar o modelo em um Notebook de GPU serverless, e então log e implantar a mesma configuração como um endpoint de serviço. O Notebook a seguir contém o fluxo executável completo deste guia.

Notebook de iniciação de serviço de LLM personalizado

Abrir notebook em uma nova aba

Limitações

Aplicam-se as seguintes limitações durante a versão Beta.

• GPU_XLARGE (1xH100) Endpoints estão disponíveis apenas em us-west-2 e exigem inscrição adicional com a equipe da sua account Databricks. Eles não habilitam a escala para zero durante a Beta.
• Sem autoscale entre réplicas. Dimensionamento para zero tem suporte em todos os tipos de GPU, exceto GPU_XLARGE. Consulte Escala para zero e planejamento de capacidade para as ressalvas de capacidade do provedor de cloud.
• Apenas a tarefa de chat do LLM (llm/v1/chat) é compatível, incluindo multimodal.
• Sem otimização de rotas.
• Sem IU para visualizar logs ou métricas. Consulte a telemetria diretamente no Unity Catalog.

Entre em contato com sua account Databricks para feedback ou perguntas.