Consultar modelos fundamentais e de embedding

O Databricks oferece várias formas de consultar modelos de fundação. Escolha uma interface com base em se você precisa de uma API independente do provedor, recursos específicos do provedor ou inferência em lote.

Maneiras de consultar um modelo

Início Rápido

Consulte um serviço modelo em dois passos:

Passo 1: Escolha um modelo

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

Passo 2: Envie uma solicitação usando a API unificada compatível com OpenAI

Use a API MLflow Chat Completions com o SDK Python da OpenAI:

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)

Requirements

• Um espaço de trabalho Azure Databricks em uma região suportada pelo Unity Gateway.
• Unity Catalog habilitado para seu workspace. Consulte Habilitar um workspace para o Unity Catalog.
• Direito de consulta ao Workspace: Acesso ao Workspace ou Acesso do Consumidor. Consulte Gerenciar direitos.

Serviços de modelo de consulta com APIs unificadas

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

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)

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

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)

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

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)

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

Consultar serviços de modelo com ai_query

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

Para consultar um serviço modelo com ai_query, execute ai_query contra um serviço modelo:

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

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

Para obter a sintaxe completa ai_query e a referência de parâmetros, consulte função ai_query. Para obter práticas recomendadas e modelos com suporte, consulte Use ai_query.

Limitações

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

Consultar serviços de modelo com APIs nativas

APIs nativas oferecem interfaces específicas para provedores para consultar modelos no Azure 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 OpenAI Responses API para consultar serviços de modelo baseados em modelos OpenAI (GPT).
• Use a API de Mensagens da Anthropic para consultar os serviços de modelo baseados em modelos do Claude.
• Use a API do Google Gemini para consultar serviços de modelos baseados em modelos Gemini.

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

Próximas Etapas 

• Descobrir e controlar o acesso aos serviços de modelo
• Integrar com agentes de codificação