Consultar modelos básicos e modelos de incorporação

O Databricks oferece várias maneiras de query modelos básicos. Escolha uma interface com base em se você precisa de uma API independente de provedor, recursos específicos do provedor ou inferência em lotes.

Formas de consultar um modelo

Abordagem	Quando usar
APIs unificadas	Usar interfaces compatíveis com OpenResponses e OpenAI Chat Completions. O Databricks traduz cada solicitação para o formato nativo do modelo downstream, para que você possa alternar entre modelos de diferentes provedores sem alterar o código do cliente.
APIs nativas do provedor	Use recursos específicos do provedor ou código SDK existente da OpenAI, Anthropic ou Google.
ai_query	Executar inferência em lotes de SQL ou Python.

Abordagem	Quando usar
APIs unificadas	Usar interfaces compatíveis com OpenResponses e OpenAI Chat Completions. O Databricks traduz cada solicitação para o formato nativo do modelo downstream, para que você possa alternar entre modelos de diferentes provedores sem alterar o código do cliente.
APIs nativas do provedor	Use recursos específicos do provedor ou código SDK existente da OpenAI, Anthropic ou Google.
ai_query	Executar inferência em lotes de SQL ou Python.

Início rápido

Faça query de um serviço de modelo em dois os passos:

Passo 1: Escolher um modelo

O Databricks fornece modelos prontos para uso, como claude-sonnet-4-5 ou gpt-5-6-sol. Os modelos fornecidos pelo Databricks são registrados no Unity Catalog em system.ai.

O passo 2: Enviar uma solicitação usando a API unificada compatível com OpenAI

Use a API de Conclusão de Chat do MLflow com o SDK Python da OpenAI:

Python

from openai import OpenAI
import os

DATABRICKS_TOKEN = os.environ.get('DATABRICKS_TOKEN')

client = OpenAI(
  api_key=DATABRICKS_TOKEN,  # your personal access token
  base_url="https://<workspace-url>/ai-gateway/mlflow/v1"  # your Databricks workspace instance
)

chat_completion = client.chat.completions.create(
  messages=[
    {"role": "user", "content": "What is Databricks?"},
  ],
  model="system.ai.claude-sonnet-4-5",
  max_tokens=256
)

print(chat_completion.choices[0].message.content)

Requisitos

• Um workspace do Databricks em uma região com suporte ao Unity Gateway.
• Unity Catalog habilitado para seu workspace. Consulte Ativar um workspace para o Unity Catalog.
• Direito do workspace para query: Acesso ao workspace ou Acesso do consumidor com a prévia Acesso do consumidor ao Unity Gateway habilitada para sua conta (Public Preview). Consulte Gerenciar direitos e Gerenciar prévias do Databricks.

Consultar serviços de modelo com APIs unificadas

As APIs unificadas oferecem uma interface compatível com OpenAI para consultar modelos no Databricks. Use APIs unificadas para alternar facilmente entre modelos de diferentes provedores sem alterar seu código.

API de respostas unificadas

API de Respostas Unificadas

A Unified Responses API (/mlflow/v1/responses) é uma API compatível com OpenResponsese agnóstica de provedor para consultar modelos no Databricks. O Databricks o recomenda em vez da API MLflow Chat Completions. Escolha o melhor modelo para o seu caso de uso entre provedores, sem alterar seu código.

Python

Python

from openai import OpenAI
import os

DATABRICKS_TOKEN = os.environ.get('DATABRICKS_TOKEN')

client = OpenAI(
  api_key=DATABRICKS_TOKEN,
  base_url="https://<workspace-url>/ai-gateway/mlflow/v1"
)

response = client.responses.create(
  model="<model-service>",
  input=[{"role": "user", "content": "What is Databricks?"}]
)

print(response.output_text)

REST API

Bash

curl \
  -u token:$DATABRICKS_TOKEN \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model-service>",
    "input": [
      {"role": "user", "content": "What is Databricks?"}
    ]
  }' \
  https://<workspace-url>/ai-gateway/mlflow/v1/responses

Substitua <workspace-url> pelo URL do seu workspace do Databricks e <model-service> pelo nome totalmente qualificado do seu serviço de modelo.

API de Conclusões de Chat do MLflow

API de Conclusões de Chat do MLflow

Python

Python

from openai import OpenAI
import os

DATABRICKS_TOKEN = os.environ.get('DATABRICKS_TOKEN')

client = OpenAI(
  api_key=DATABRICKS_TOKEN,
  base_url="https://<workspace-url>/ai-gateway/mlflow/v1"
)

chat_completion = client.chat.completions.create(
  messages=[
    {"role": "user", "content": "Hello!"},
    {"role": "assistant", "content": "Hello! How can I assist you today?"},
    {"role": "user", "content": "What is Databricks?"},
  ],
  model="system.ai.gpt-5-6-sol",
  max_tokens=256
)

print(chat_completion.choices[0].message.content)

REST API

Bash

curl \
  -u token:$DATABRICKS_TOKEN \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "model": "system.ai.gpt-5-6-sol",
    "max_tokens": 256,
    "messages": [
      {"role": "user", "content": "Hello!"},
      {"role": "assistant", "content": "Hello! How can I assist you today?"},
      {"role": "user", "content": "What is Databricks?"}
    ]
  }' \
  https://<workspace-url>/ai-gateway/mlflow/v1/chat/completions

Substitua <workspace-url> pela URL do seu workspace do Databricks.

API de Embeddings MLflow

API de Embeddings do MLflow

Python

Python

from openai import OpenAI
import os

DATABRICKS_TOKEN = os.environ.get('DATABRICKS_TOKEN')

client = OpenAI(
  api_key=DATABRICKS_TOKEN,
  base_url="https://<workspace-url>/ai-gateway/mlflow/v1"
)

embeddings = client.embeddings.create(
  input="What is Databricks?",
  model="<model-service>"
)

print(embeddings.data[0].embedding)

REST API

Bash

curl \
  -u token:$DATABRICKS_TOKEN \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model-service>",
    "input": "What is Databricks?"
  }' \
  https://<workspace-url>/ai-gateway/mlflow/v1/embeddings

Substitua <workspace-url> pelo URL do seu workspace do Databricks e <model-service> pelo nome totalmente qualificado do seu serviço de modelo.

Consultar serviços de modelo com ai_query

Você pode usar a ai_query função para fazer query serviços de modelo diretamente do SQL ou Python. Isso permite capturar informações de acompanhamento de uso para suas cargas de trabalho de inferência em lote.

Para fazer query de um serviço de modelo com ai_query, faça a execução de ai_query em um serviço de modelo:

SQL

SELECT ai_query(
  'system.ai.claude-sonnet-4-5',
  'Summarize the following text: ' || text_column
) AS summary
FROM my_table
LIMIT 10

A tabela do sistema de acompanhamento de uso (system.ai_gateway.usage) captura solicitações feitas por meio do ai_query para serviços de modelo. Essas solicitações também aparecem no painel de uso integrado.

Para a sintaxe completa ai_query e referência de parâmetros, consulte a ai_query função. Para melhores práticas e modelos compatíveis, consulte Use ai_query.

Limitações

• ai_query O suporte para o Unity Gateway está disponível apenas para modelos fornecidos pelo Databricks. Passe o nome do serviço de modelo system.ai (por exemplo, system.ai.claude-sonnet-4-5 ou system.ai.gpt-5-6-sol). Serviços de modelo que você cria no Unity Gateway ainda não são suportados.
• Somente o acompanhamento de uso se aplica a cargas de trabalho de inferência em lote de ai_query. Outros recursos do Unity Gateway, como limites de taxa, proteções implementadas com políticas de serviço, tabelas de inferência e fallback, não se aplicam.

Fazer query de serviços de modelo com APIs nativas

APIs nativas oferecem interfaces específicas de provedor para query modelos no Databricks. Use APIs nativas para acessar os recursos mais recentes específicos do provedor.

Cada API nativa funciona apenas com serviços de modelo cujo modelo subjacente usa o formato de API correspondente:

• Use a API de Respostas da OpenAI para consultar serviços de modelo baseados em modelos OpenAI (GPT).
• Use a API de Mensagens da Anthropic para consultar serviços de modelo compatíveis com modelos Claude.
• Use a API Google Gemini para consultar serviços de modelo apoiados por modelos Gemini.

Para consultar um serviço de modelo independentemente do seu modelo subjacente, use as APIs unificadas em vez disso.

Próximos os passos

• Descobrir e governar o acesso a serviços de modelo
• Integrar com agentes de codificação