Atender LLMs personalizados com o Serviço de Modelo Personalizado

Esta página mostra como servir seu próprio LLM em um endpoint de GPU Model Serving . Qualquer modelo que o vLLM roda torna-se um endpoint de produção com uma API compatível com OpenAI. É assim que funciona:

• Você roda o servidor de inferência, como o vLLM, e escolhe sua versão e configurações.
• Você testa o servidor em um notebook com GPU serverless . Uma flag errada ou um erro de falta de memória aparece em segundos, em vez de após uma implantação.
• Você implanta o mesmo comando e ambiente que construiu e sabe que funciona em um endpoint de serviço de produção.

Início Rápido

Importe o seguinte notebook para seu espaço de trabalho e clique em Executar tudo no AI Runtime com uma GPU A10. Em cerca de 15 minutos, você tem um endpoint Qwen3.5-4B que responde a pedidos de chat compatíveis com OpenAI.

Implante o Qwen3.5-4B com vLLM

Obter laptop

Quando usar o serviço LLM personalizado

Use o serviço de LLM personalizado nos seguintes casos:

• Você ajustou um LLM no AI Runtime e quer colocá-lo em produção. Veja a seção abaixo para um exemplo.
• Você quer servir um modelo aberto que as APIs do Foundation Model (FMAPI) não suportam, como um novo LLM, um modelo de fala para texto ou um modelo de embedding.
• Você quer mudar o tempo de execução ou a arquitetura de um LLM e precisa de controle do tempo de execução e do ambiente.

Não use serving personalizado de LLM nos seguintes casos:

• FMAPI fornece o modelo de que você precisa, sem alterações. O FMAPI é mais simples de usar e altamente otimizado.
• O modelo não cabe em uma única GPU com cerca de 80 GB de memória. Por exemplo, Qwen3.8-27B e gpt-oss-120b servem, mas Kimi K3 e GLM 5.3 não.
• Você precisa de taxa de transferência de nível de ponta ou preço por token sem ajustes. O desempenho equivale ao do vLLM código aberto na mesma GPU.

Requirements

O serviço personalizado de LLM possui os seguintes requisitos:

• Seu workspace deve ter computação serverless com GPU.
• Você deve registrar o modelo a partir de um notebook com GPU serverless. Um modelo registrado de um ambiente de CPU empacota dependências de CPU e o ponto de extremidade de GPU não inicia.
• Você precisa ter permissão para criar modelos em um esquema do Unity Catalog.
• Você deve registrar o modelo com env_pack="databricks_model_serving". O serviço personalizado de LLM é baseado em implantações express, que empacotam o ambiente do notebook com o modelo.
• Você deve usar MLflow 3.12 ou superior e databricks-sdk 0.102.0 ou superior. O ambiente da IA v6 inclui os dois.

Notebooks iniciais

Cada notebook leva um modelo do Hugging Face para um ponto de extremidade consultado, como o início rápido. Execute um como está ou comece de um para servir seu próprio modelo.

AI v6 e Standard v6 são ambientes de execução de IA. A AI v6 vem com vLLM, PyTorch, Transformers e outros pacotes comuns de aprendizado de máquina pré-instalados e prontos para uso. Veja a lista de pacotes do AI v6. Um notebook Standard v6 instala o vLLM por conta própria, então você escolhe sua versão. Use um notebook Standard v6 quando seu modelo precisar de um vLLM ou transformadores mais recentes do que os incluídos no AI v6, como no caso do Muse Glimmer.

Sirva seu próprio modelo

Para servir outro modelo, escolha o notebook inicial com a mesma tarefa e a GPU que seu modelo precisa. Altere MODEL_REPO_ID e as flags em vllm_command, então rode o notebook. Todo notebook executa os seguintes passos:

1. Baixe os pesos modelo do Hugging Face, ou pegue-os em um checkpoint de treinamento.
2. Inicie o vLLM no notebook e consulte-o.
3. Registre o modelo com o comando vLLM como ponto de entrada e registre-o no Unity Catalog como uma implantação expressa.
4. Crie um ponto de extremidade do serviço, que inicia o mesmo comando.
5. Consulte o endpoint com o cliente OpenAI, o SDK Databricks ou SQL ai_query.

No exemplo a seguir, o metadata modelo contém a tarefa e o ponto de entrada:

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

Servir um modelo otimizado

Ajuste um modelo no AI Runtime e o sirva a partir do mesmo notebook. Para um exemplo, veja Ajuste fino supervisionado (Completo) e implantação de Qwen3.5-0.8B. O tutorial ajusta o Qwen3.5-0.8B em um único H100, compara respostas antes e depois do treinamento e disponibiliza o modelo ajustado.

Tarefas com suporte

O task nos metadados do modelo define a API que o ponto de extremidade serve. Seu servidor deve expor a API compatível com OpenAI para essa tarefa. Outras tarefas, como llm/v1/completions, não são suportadas. A tabela a seguir lista as tarefas suportadas.

Escolha uma GPU

O Azure Databricks recomenda o desenvolvimento na mesma GPU em que você serve, para que as configurações que você testa sejam as configurações que você implanta. A tabela a seguir lista as GPUs para serving personalizado de LLMs.

Problemas comuns

Os seguintes problemas são os mais comuns quando você troca um notebook:

• O download falha em /Workspace, que não aceita arquivos de vários GB. Baixe os pesos para o disco local, como fazem os notebooks iniciais.
• O servidor local não inicia. Notebooks com GPU serverless permitem apenas portas 3000 a 3999, então teste em uma dessas. Apenas o ponto de entrada usa a porta 8080, e fora isso ele deve corresponder ao comando que você testou.
• O endpoint não consegue encontrar os pesos. O ponto de entrada fica na pasta de artefatos do modelo, então --model deve nomear a pasta de pesos que você registrou.
• Um modelo de embedding não serve embeddings. Comece o vLLM com --runner pooling.
• O registro falha com TimeoutError('Timed out after 0:05:00') ao fazer upload de model_version.tar ou model_environment.tar. Atualize para databricks-sdk 0.102.0 ou superior e registre o modelo novamente.

Criar um ponto de extremidade

Crie o endpoint a partir da interface de Serving ou com o SDK Databricks, como fazem os notebooks iniciais. workload_type escolhe a GPU, e workload_size (Small, Medium, ou Large) define o número de réplicas.

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

Escalar para zero e capacidade

Atualmente, endpoints personalizados de LLM não escalam dinamicamente automaticamente, portanto, dimensione workload_size para o seu pico de tráfego.

Com a escalabilidade para zero, um ponto de extremidade ocioso interrompe todas as réplicas. A próxima solicitação leva de um a vários minutos enquanto o vLLM carrega o modelo novamente e todas as réplicas iniciam. Azure Databricks recomenda desligar o scale-to-zero para tráfego de produção.

Consulte seu endpoint

Um endpoint de chat pronto aparece no AI Playground. Os exemplos a seguir consultam um endpoint com o SDK Databricks, o cliente OpenAI e o REST.

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

Cliente 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

Alguns modelos de embedding esperam um prefixo em cada entrada, como search_query: ou search_document:. Verifique o model card.

Monitore seu endpoint

A guia Logs do ponto de extremidade mostra os stdout e stderr do seu servidor em tempo real. A API de logs retorna a mesma saída.

O Azure Databricks encaminha as métricas do seu servidor vLLM e as exibe em gráficos na aba Métricas do endpoint:

• Latência: tempo até o primeiro token, tempo por token de saída, latência de requisição e tempo de fila.
• Carga: solicitações em execução e aguardando.
• KV cache: uso e taxa de acerto.
• Throughput: tokens de prompt e geração por segundo.

A API de métricas de exportação retorna as mesmas métricas no formato Prometheus, então você pode coletá-las com o Prometheus ou o Datadog.

Com a telemetria ativada, o Azure Databricks também salva os logs do servidor e as métricas do vLLM Prometheus em tabelas do Unity Catalog, para que você possa consultá-las por períodos mais longos. Consulte Persist custom model serving data to Unity Catalog.

Pricing

Você paga por hora de instância de GPU, da mesma forma que para outros serviços de modelo personalizado com GPU. Veja os preços do Model Serving.

Limitações e disponibilidade de região

Você registra um LLM personalizado do AI Runtime, portanto, o serviço de LLM personalizado está disponível nas mesmas regiões que a computação de GPU sem servidor. Essas são regiões dos EUA na AWS e Azure. GCP não é suportado.

Os seguintes recursos estão chegando em breve:

• Adaptadores LoRA.
• Serviço entre regiões.
• Registro de modelos fora do AI Runtime, por exemplo, do Databricks Runtime ou computação sem servidor de CPU.

Não há suporte aos seguintes recursos:

• Roteamento com reconhecimento de cache chave-valor.
• Otimização de rotas.