Sirva LLMs personalizados com o Custom Model Serving.
Visualização
Workspace admins can control access to this recurso from the Previews page. Os administradores do Workspace podem controlar o acesso a este recurso na página Previews . Consulte Gerenciar Databricks previews.
Esta página mostra como disponibilizar seu próprio LLM em um endpoint GPU do Model Serving. Qualquer modelo em execução pelo vLLM se torna um Endpoint de produção com uma API compatível com OpenAI. Funciona da seguinte maneira:
- Você faz a execução do servidor de inferência, como o vLLM, e escolhe sua versão e suas configurações.
- Você testa o servidor em um notebook de GPU serverless. Uma flag incorreta ou um erro de falta de memória aparece em segundos, e não após um deployment.
- Você implanta o mesmo comando e ambiente que criou e sabe que funciona em um endpoint de serviço de produção.
Início rápido
Importe o seguinte notebook para o seu workspace e clique em Run all no AI Runtime com uma GPU A10. Em cerca de 15 minutos, você terá um Qwen3.5-4B endpoint que responde a solicitações de chat compatíveis com OpenAI.
Disponibilize o Qwen3.5-4B com o vLLM
Quando usar a disponibilização de LLM personalizado
Use custom LLM serving in the following cases:
- Você fine-tuneou um LLM no AI Runtime e deseja disponibilizá-lo. Consulte a seção abaixo para obter um exemplo.
- You want to serve an open model that Foundation Model APIs (FMAPI) doesn't support, like a new LLM, a speech-to-text model, or an embedding model.
- Você deseja alterar o runtime ou a arquitetura de um LLM e precisa de controle sobre o runtime e o ambiente.
Don't use custom LLM serving in the following cases:
- FMAPI serves the model you need, unchanged. FMAPI is simpler to use and highly optimized.
- 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 cabem, mas Kimi K3 e GLM 5.3, não.
- Você precisa de throughput de nível de fronteira ou preço por tokens sem ajuste. O desempenho é compatível com o vLLM de código aberto na mesma GPU.
Requisitos
A disponibilização de LLM personalizado tem os seguintes requisitos:
- Your workspace must have serverless GPU compute.
- Você deve registrar o modelo a partir de um notebook com GPU serverless. Um modelo registrado a partir de um ambiente de CPU pacote dependências de CPU, e o Endpoint de GPU falha ao começar.
- Você deve ter permissão para criar modelos em um esquema do Unity Catalog.
- Você deve fazer o registro do modelo com
env_pack="databricks_model_serving". O serving de LLM personalizado é criado com base em implantações expressas, que empacotam o ambiente do notebook com o modelo. - Você deve usar o MLflow 3.12 ou acima e o
databricks-sdk0.102.0 ou acima. O ambiente AI v6 inclui ambos.
Starter notebooks
Cada notebook leva um modelo do Hugging Face para um endpoint query, como o início rápido. Execução um como está ou comece a partir de um para disponibilizar seu próprio modelo.
Modelo | Tarefa | ambiente | GPU de notebook | Endpoint GPU |
|---|---|---|---|---|
Bate-papo | AI v6 ou Standard v6 | A10 | A10G (AWS), A100 (Azure) | |
Chat com chamadas de ferramenta | AI v6 | H100 | H100 (AWS), A100 (Azure) | |
Chat com chamadas de ferramenta | AI v6 | H100 | H100 (AWS), A100 (Azure) | |
Bate-papo | Standard v6 | H100 | H100 (AWS), A100 (Azure) | |
Fala para texto | AI v6 | A10 | A10G (AWS), A100 (Azure) | |
Incorporações | AI v6 | A10 | A10G (AWS), A100 (Azure) |
AI v6 e Standard v6 são ambientes do AI Runtime. O AI v6 vem com vLLM, PyTorch, Transformers e outros pacotes comuns de machine learning pré-instalados e prontos para uso. Consulte a lista de pacotes do AI v6. Um notebook do Standard v6 instala o próprio vLLM, portanto você escolhe a versão dele. Use um notebook do Standard v6 quando seu modelo precisar de uma versão mais recente do vLLM ou dos transformers do que a incluída no AI v6, como no caso do Muse Glimmer.
Sirva seu próprio modelo
Para disponibilizar outro modelo, escolha o notebook inicial com a mesma tarefa e a GPU necessária para o seu modelo. Altere o MODEL_REPO_ID e as flags em vllm_command e, em seguida, execução o notebook. Cada notebook executa os seguintes passos:
- Faça o download dos pesos do modelo do Hugging Face ou obtenha-os de um checkpoint de treinamento.
- Comece o vLLM no notebook e faça uma query nele.
- Registre o modelo com o comando vLLM como seu ponto de entrada e faça o registro dele no Unity Catalog como um express deployment.
- Crie um endpoint de serviço, que começa o mesmo comando.
- Faça uma query no endpoint com o cliente OpenAI, o Databricks SDK ou SQL
ai_query.
No exemplo a seguir, o metadata do 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")
Disponibilizar um modelo ajustado
Faça o ajuste fino de um modelo em AI Runtime e disponibilize-o a partir do mesmo notebook. Para ver um exemplo, consulte Supervised fine-tuning (Full) and serving of Qwen3.5-0.8B. O tutorial faz o ajuste fino de Qwen3.5-0.8B em uma única H100, compara as respostas antes e depois do treinamento e disponibiliza o modelo ajustado.
Tarefas compatíveis
O task nos metadados do modelo define a API que o endpoint serve. Seu servidor deve expor a API compatível com OpenAI para essa tarefa. Outras tarefas, como llm/v1/completions, não são aceitas. A tabela a seguir lista as tarefas compatíveis.
| Tipo de modelo | Query with |
|---|---|---|
| Modelos de chat, incluindo modelos de visão e linguagem |
|
| Modelos de incorporação |
|
| Modelos de conversão de fala em texto |
|
| Modelos de tradução de fala para inglês |
|
Escolha uma GPU
A Databricks recomenda o desenvolvimento na mesma GPU em que você faz o serving, de modo que as configurações testadas sejam as configurações implantadas. A tabela a seguir lista as GPUs para o custom LLM serving.
| GPU | Notas |
|---|---|---|
| 1x T4 (16 GB) | Modelos pequenos. |
| 1x A10G (24 GB) | Modelos de até cerca de 10B de parâmetros. Disponível em geral. |
| 1x L40S (48 GB) | Modelos de até cerca de 15B parâmetros. Disponível em |
| 1x H100 (80 GB) | Recomendado para LLMs grandes. Disponível apenas em |
| 1x RTX PRO 6000 (96 GB) | Mais memória do que a H100, mas menos otimizada para a disponibilização de LLM. Disponível em |
Problemas comuns
Os problemas a seguir são os mais comuns ao alterar um notebook:
- O download falha em
/Workspace, que não aceita arquivos de vários GB. download os pesos para o disco local, assim como fazem os notebooks iniciais. - O servidor local não começa. Notebooks de GPU serverless permitem apenas as portas 3000 a 3999, portanto, teste em uma delas. Somente o entrypoint usa a porta 8080 e, caso contrário, deve corresponder ao comando que você testou.
- The endpoint can't find the weights. The entrypoint execução in the model's artifacts folder, so
--modelmust name the weights folder you logged. - Um modelo de incorporação não serve incorporações. Comece o vLLM com
--runner pooling. - O registro falha com
TimeoutError('Timed out after 0:05:00')ao fazer upload demodel_version.taroumodel_environment.tar. Atualize para odatabricks-sdk0.102.0 ou acima e faça o registro do modelo novamente.
Criar um endpoint
Crie o endpoint na interface do usuário do Serving ou com o Databricks SDK, conforme os notebooks iniciais fazem. 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,
)
Escala para zero e capacidade
Atualmente, os Endpoint de LLM personalizados não realizam autoscale dinamicamente; portanto, dimensione o tamanho de workload_size para o seu pico de tráfego.
With escala-to-zero, an idle Endpoint stops all replicas. The next request waits one to several minutes while vLLM loads the model again and all replicas start up. Databricks recommends turning off escala-to-zero for production traffic.
A capacidade de aumento de escala não é garantida. Sempre que o Databricks precisar adquirir uma nova GPU para o seu endpoint, como na criação, em um aumento de workload_size ou quando um endpoint é ativado a partir de zero, a solicitação poderá falhar se o cloud provider não tiver capacidade de GPU na sua região. A Databricks mitiga isso com pools aquecidos e pré-reserva, que mantêm a capacidade da GPU disponível e pronta.
GPU_XLARGE Os Endpoint (1xH100) não oferecem suporte a scale_to_zero_enabled=True no momento.
Faça a query do seu endpoint
Um endpoint de chat pronto aparece no AI Playground. Os exemplos a seguir consultam um endpoint com o Databricks SDK, o cliente OpenAI e o REST.
- Databricks SDK
- OpenAI client
- REST: chat
- REST: embeddings
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")],
)
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)
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
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 incorporação esperam um prefixo em cada entrada, como search_query: ou search_document:. Verifique o cartão do modelo.
Monitorar seu endpoint
A tab de Logs do endpoint mostra o stdout e o stderr do seu servidor em tempo real. A logs API retorna a mesma saída.
O Databricks encaminha as métricas do servidor vLLM e as exibe em gráficos na tab Metrics do endpoint:
- Latência: tempo para o primeiro tokens, tempo por tokens de saída, latência da requisição e tempo na fila.
- Carregar: solicitações em execução e em espera.
- Cache KV: uso e taxa de acerto.
- Throughput: tokens de prompt e de geração por segundo.
A API de exportação de métricas retorna as mesmas métricas no formato Prometheus, permitindo que você as colete no Prometheus ou no Datadog.
Com a telemetria ativada, o Databricks também salva os logs do servidor e as métricas do Prometheus do vLLM nas tabelas do Unity Catalog, para que você possa fazer query deles por períodos mais longos. Consulte Persistir dados de servindo modelo personalizados no Unity Catalog.
preços
Você paga por hora de instância de GPU, o mesmo que para outro servindo modelo personalizado de GPU. Consulte preços do Model Serving.
Limitações e disponibilidade regional
Você faz o log de um LLM personalizado do AI Runtime, portanto, a disponibilização de LLMs personalizados está disponível nas mesmas regiões que o compute de GPU serverless. Essas são regiões dos EUA na AWS e no Azure. O GCP não é compatível.
Os seguintes recursos estarão disponíveis em breve:
- Adaptadores LoRA.
- Disponibilização entre regiões.
- Fazendo o log de modelos fora do AI Runtime, por exemplo, do Databricks Runtime ou de serverless de CPU.
Os seguintes recursos não são compatíveis:
- Roteamento com reconhecimento de cache KV.
- Otimização de rotas.