Disponibilize LLMs personalizados com o Custom Model Serving

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

• Executas o servidor de inferência, como o vLLM, e escolhes a sua versão e definições.
• Testas o servidor num notebook com GPU serverless. Uma flag errada ou um erro de falta de memória aparece em segundos em vez de após uma implementação.
• Fazes o deployment do mesmo comando e ambiente que construíste e sabes que funciona para um endpoint de serviço de produção.

Início Rápido

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

Servir Qwen3.5-4B com vLLM

Obter caderno

Quando usar serviço personalizado para LLM

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

• Afinaste um LLM em AI Runtime e queres disponibilizá-lo. Veja a secção abaixo para um exemplo.
• Queres servir um modelo aberto que as APIs do Foundation Model (FMAPI) não suportam, como um novo LLM, um modelo de voz para texto ou um modelo de embedding.
• Queres mudar o runtime ou a arquitetura de um LLM e precisas de controlar o runtime e o ambiente.

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

• A FMAPI fornece o modelo de que precisas, inalterado. O FMAPI é mais simples de usar e altamente otimizado.
• O modelo não cabe numa única GPU com cerca de 80 GB de memória. Por exemplo, Qwen3.8-27B e gpt-oss-120b encaixam, mas Kimi K3 e GLM 5.3 não.
• Precisas de throughput ou preço por token de ponta sem fazer tuning. O desempenho iguala o do vLLM open source na mesma GPU.

Requirements

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

• O seu espaço de trabalho deve ter computação GPU serverless.
• Tens de registar o modelo a partir de um notebook com GPU serverless. Um modelo registado a partir de um ambiente de CPU empacota as dependências da CPU, e o endpoint da GPU falha em arrancar.
• Deve ter permissão para criar modelos num esquema do Unity Catalog.
• Deve registar o modelo com env_pack="databricks_model_serving". O serviço personalizado de LLM é construído sobre implementações Express, que integram o ambiente do notebook com o modelo.
• Deve usar MLflow 3.12 ou superior e databricks-sdk 0.102.0 ou superior. O ambiente da IA v6 inclui ambos os elementos.

notebooks de exemplo

Cada notebook leva um modelo do Hugging Face para um endpoint alvo da consulta, como o quickstart. Execute uma tal como está, ou comece a partir de uma para implementar o seu próprio modelo.

AI v6 e Standard v6 são ambientes de IA Runtime. A IA v6 vem com vLLM, PyTorch, Transformers e outros pacotes comuns de aprendizagem automática pré-instalados e prontos a usar. Veja a lista de pacotes do AI v6. Um notebook Standard v6 instala o próprio vLLM, por isso escolhes a sua versão. Use um notebook Standard v6 quando o seu modelo precisar de um vLLM ou transformers mais recentes do que o AI v6 inclui, como acontece com o Muse Glimmer.

Disponibilize o seu próprio modelo

Para servir outro modelo, escolhe o notebook inicial com a mesma tarefa e a GPU de que o teu modelo precisa. Altere MODEL_REPO_ID e as flags em vllm_command, depois execute o notebook. Cada notebook executa os seguintes passos:

1. Descarregue os pesos modelo do Hugging Face, ou obtenha-os num ponto de controlo de treino.
2. Começa o vLLM no notebook e faz uma consulta.
3. Regista o modelo com o comando vLLM como ponto de entrada e regista-o no Unity Catalog como um deployment expresso.
4. Cria um endpoint de serviço, que inicia o mesmo comando.
5. Consulte o endpoint com o cliente OpenAI, o SDK Databricks ou SQL ai_query.

No exemplo seguinte, o metadata modelo manté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")

Disponibilizar um modelo ajustado

Afina um modelo no AI Runtime e serve-o a partir do mesmo notebook. Para um exemplo, veja Ajuste fino supervisionado (Completo) e implementação de Qwen3.5-0.8B. O tutorial afina o Qwen3.5-0.8B num único H100, compara respostas antes e depois do treino, e disponibiliza o modelo afinado.

Tarefas suportadas

O task nos metadados do modelo define a API que o endpoint serve. O 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 seguinte lista as tarefas suportadas.

Escolha uma GPU

O Azure Databricks recomenda desenvolver na mesma GPU em que serves, por isso as definições que testas são as que implementas. A tabela seguinte lista as GPUs para serviço personalizado de LLMs.

Problemas comuns

Os seguintes problemas são os mais comuns quando se troca um portátil:

• O download falha em /Workspace, que não aceita ficheiros de vários GB. Descarregue os pesos para o disco local, tal como fazem os notebooks iniciais.
• O servidor local não arranca. Notebooks com GPU serverless só permitem as portas 3000 a 3999, por isso experimenta numa dessas portas. Só o entrypoint usa a porta 8080, e caso contrário tem de corresponder ao comando que testou.
• O endpoint não consegue encontrar os pesos. O ponto de entrada fica na pasta de artefactos do modelo, por isso --model deve nomear a pasta de pesos que guardou.
• Um modelo de embedding não serve embeddings. Inicie o vLLM com --runner pooling.
• O registo falha com TimeoutError('Timed out after 0:05:00') ao carregar model_version.tar ou model_environment.tar. Atualize para databricks-sdk 0.102.0 ou superior e volte a registar o modelo.

Criar um ponto final

Crie o endpoint a partir da IU 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,
)

Dimensionamento até zero e capacidade

Atualmente, endpoints LLM personalizados não escalam dinamicamente, por isso dimensiona workload_size para o teu pico de tráfego.

Com scale-to-zero, um endpoint inativo pára todas as réplicas. O pedido seguinte demora de um a vários minutos enquanto o vLLM carrega novamente o modelo e todas as réplicas arrancam. O Azure Databricks recomenda desligar o scale-to-zero para tráfego de produção.

Consultar o seu ponto de extremidade

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

Databricks SDK

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: conversa

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:. Verifica a ficha do modelo.

Monitorize o seu endpoint

O separador de Logs do endpoint mostra os stdout do seu servidor e stderr em direto. A API dos logs devolve a mesma saída.

O Azure Databricks encaminha as métricas do seu servidor vLLM e grafica-as no separador Métricas do endpoint:

• Latência: tempo até ao primeiro token, tempo por token de saída, latência de pedido e tempo de fila.
• Carga: solicitações em execução e à espera.
• Cache KV: utilização e taxa de acerto.
• Throughput: prompt e tokens de geração por segundo.

A API de métricas de exportação devolve as mesmas métricas em formato Prometheus, por isso pode recolhê-las para o Prometheus ou o Datadog.

Com a telemetria ativada, o Azure Databricks também guarda os registos do servidor e as métricas Prometheus do vLLM em tabelas do Unity Catalog, para que possas consultá-las durante períodos mais longos. Veja Persistir modelo personalizado que serve dados para o Catálogo Unity.

Pricing

Paga-se por hora de instância da GPU, o mesmo que para outros serviços de serving de modelos personalizados com GPU. Veja preços do Model Serving.

Limitações e disponibilidade da região

Registas um LLM personalizado a partir do AI Runtime, por isso o serviço de LLM personalizado está disponível nas mesmas regiões que o processamento de GPU serverless. São regiões dos EUA na AWS e Azure. O GCP não é suportado.

As seguintes funcionalidades estão a chegar em breve:

• Adaptadores LoRA.
• Disponibilização entre regiões.
• Registar modelos fora do AI Runtime, por exemplo do Databricks Runtime ou de CPU serverless.

Os seguintes recursos não são suportados:

• Encaminhamento com reconhecimento da cache KV.
• Otimização de rotas.