Consultar APIs de modelos (serviços de modelos)

Use o Unity AI Gateway para consultar serviços de modelo no Unity Catalog com APIs de modelo do Azure Databricks, usando o SDK compatível com OpenAI, APIs nativas de provedores ou SQL.

Observação

Quando um serviço de modelo roteia para um destino de serviço de provedor de modelo, apenas os recursos do Gateway de IA do Unity do serviço de modelo (como limites de taxa, verificadores de integridade, tabelas de inferência e fallback) se aplicam. Qualquer recurso do Gateway de IA do Unity configurado no próprio serviço do provedor de modelo é ignorado.

Comece a consultar APIs de modelos

Consulte uma API de modelo em duas etapas:

Passo 1: Escolha uma API de modelo pronta para uso

O Azure Databricks fornece APIs de modelos prontas para uso no system.ai esquema, como system.ai.claude-sonnet-4-5 e system.ai.gpt-5-6-sol. Esses estão disponíveis imediatamente, sem necessidade de configuração adicional.

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)

Para outras opções, veja Comece a consultar LLMs no Databricks.

Requirements

Um workspace do Azure Databricks em uma região com suporte ao Gateway de IA Unity.
Unity Catalog habilitado para seu workspace. Consulte Habilitar um workspace para o Unity Catalog.
Permissão do workspace para consultar: Acesso ao Workspace ou Acesso de consumidor com a visualização prévia Acesso de consumidor ao Unity AI Gateway habilitada para sua conta (Versão prévia pública). Veja Gerenciar direitos de acesso e Gerenciar versões prévias do Azure Databricks.

APIs e integrações com suporte

O Gateway de IA do Unity dá suporte às seguintes APIs e integrações:

APIs unificadas: interfaces compatíveis com OpenAI para consultar modelos no Azure Databricks. Alterne perfeitamente entre modelos de diferentes provedores sem alterar a forma como você consulta cada modelo.
APIs nativas: interfaces específicas do provedor para acessar o modelo mais recente e recursos específicos do provedor.
Agentes de codificação: integre seus agentes de codificação ao Gateway de IA do Unity para adicionar governança centralizada e monitoramento aos fluxos de trabalho de desenvolvimento assistidos por IA. Consulte a integração do agente de codificação.
Agentes no Databricks Apps: Crie e implante agentes no Databricks Apps que encaminham o tráfego de LLM por meio do Unity AI Gateway. Consulte a Etapa 4. Controlar o uso de LLM de seus agentes nos Aplicativos do Databricks com o Gateway de IA do Unity.
ai_query: Use ai_query para consultar serviços de modelos fornecidos pelo Azure Databricks a partir do SQL ou do Python para inferência em lote. Consulte Consultar serviços de modelo com ai_query.

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.

API de Conclusões de Chat do MLflow

API de Conclusões de Chat do MLflow

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="<model-service>",
  max_tokens=256
)

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

API REST

curl \
  -u token:$DATABRICKS_TOKEN \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model-service>",
    "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 Azure Databricks e <model-service> pelo nome totalmente qualificado do seu serviço de modelo.

MLflow Embeddings API

MLflow Embeddings API

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)

API REST

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> pela URL do seu workspace do Azure Databricks e <model-service> pelo nome totalmente qualificado do seu serviço de modelo.

Supervisor API

Supervisor API

A API do Supervisor (/mlflow/v1/responses) é uma API compatível com OpenResponses e independente do provedor para criar agentes na Versão Beta. Administradores do espaço de trabalho podem habilitá-lo pela página de Prévias . Consulte Gerenciar visualizações do Azure Databricks. Escolha o melhor modelo para o caso de uso do agente entre provedores, sem alterar seu código.

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)

API REST

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> pela URL do seu workspace do Azure 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 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.

Observação

ai_queryo suporte ao Unity AI Gateway está disponível apenas para modelos fornecidos pelo Azure Databricks. Passe o nome do endpoint do modelo de base do Azure Databricks, que inclui o prefixo databricks- (por exemplo, databricks-claude-sonnet-4-5 ou databricks-gpt-5-6-sol), em vez do nome do serviço de modelo system.ai usado em outras partes desta página. Serviços de modelo que você cria no Gateway de IA do Unity ainda não têm suporte.
Apenas o rastreamento de uso se aplica a cargas de trabalho de inferência em lote ai_query. Outros recursos do Gateway de IA do Unity, como limites de taxas, proteções, tabelas de inferência e fallbacks, não se aplicam.

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

SELECT ai_query(
  'databricks-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.

Consultar serviços de modelo com APIs nativas

As APIs nativas oferecem interfaces específicas do provedor 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.

API de respostas do OpenAI

API de respostas do OpenAI

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/openai/v1"
)

response = client.responses.create(
  model="<model-service>",
  max_output_tokens=256,
  input=[
    {
      "role": "user",
      "content": [{"type": "input_text", "text": "Hello!"}]
    },
    {
      "role": "assistant",
      "content": [{"type": "output_text", "text": "Hello! How can I assist you today?"}]
    },
    {
      "role": "user",
      "content": [{"type": "input_text", "text": "What is Databricks?"}]
    }
  ]
)

print(response.output)

API REST

curl \
  -u token:$DATABRICKS_TOKEN \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model-service>",
    "max_output_tokens": 256,
    "input": [
      {
        "role": "user",
        "content": [{"type": "input_text", "text": "Hello!"}]
      },
      {
        "role": "assistant",
        "content": [{"type": "output_text", "text": "Hello! How can I assist you today?"}]
      },
      {
        "role": "user",
        "content": [{"type": "input_text", "text": "What is Databricks?"}]
      }
    ]
  }' \
  https://<workspace-url>/ai-gateway/openai/v1/responses

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

API de Mensagens da Anthropic

API de Mensagens da Anthropic

Python

import anthropic
import os

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

client = anthropic.Anthropic(
  api_key="unused",
  base_url="https://<workspace-url>/ai-gateway/anthropic",
  default_headers={
    "Authorization": f"Bearer {DATABRICKS_TOKEN}",
  },
)

message = client.messages.create(
  model="<model-service>",
  max_tokens=256,
  messages=[
    {"role": "user", "content": "Hello!"},
    {"role": "assistant", "content": "Hello! How can I assist you today?"},
    {"role": "user", "content": "What is Databricks?"},
  ],
)

print(message.content[0].text)

API REST

curl \
  -u token:$DATABRICKS_TOKEN \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model-service>",
    "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/anthropic/v1/messages

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

Google Gemini API

Google Gemini API

Python

from google import genai
from google.genai import types
import os

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

client = genai.Client(
  api_key="databricks",
  http_options=types.HttpOptions(
    base_url="https://<workspace-url>/ai-gateway/gemini",
    headers={
      "Authorization": f"Bearer {DATABRICKS_TOKEN}",
    },
  ),
)

response = client.models.generate_content(
  model="<model-service>",
  contents=[
    types.Content(
      role="user",
      parts=[types.Part(text="Hello!")],
    ),
    types.Content(
      role="model",
      parts=[types.Part(text="Hello! How can I assist you today?")],
    ),
    types.Content(
      role="user",
      parts=[types.Part(text="What is Databricks?")],
    ),
  ],
  config=types.GenerateContentConfig(
    max_output_tokens=256,
  ),
)

print(response.text)

API REST

curl \
  -u token:$DATABRICKS_TOKEN \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [{"text": "Hello!"}]
      },
      {
        "role": "model",
        "parts": [{"text": "Hello! How can I assist you today?"}]
      },
      {
        "role": "user",
        "parts": [{"text": "What is Databricks?"}]
      }
    ],
    "generationConfig": {
      "maxOutputTokens": 256
    }
  }' \
  https://<workspace-url>/ai-gateway/gemini/v1beta/models/<model-service>:generateContent

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

Marcar solicitações para rastreamento de uso

Você pode anexar marcas de chave-valor personalizadas a solicitações individuais usando o Databricks-Ai-Gateway-Request-Tags cabeçalho HTTP. As tags de solicitação são registradas na coluna request_tags tanto na tabela de sistema de acompanhamento de uso quanto nas tabelas de inferência, permitindo que você acompanhe os custos, atribua o uso e filtre as análises por projeto, equipe, ambiente ou qualquer outra dimensão.

O valor do cabeçalho deve ser um objeto JSON que associa chaves de string a valores de string. Por exemplo:

{ "project": "chatbot", "team": "ml-platform", "environment": "production" }

Use o parâmetro extra_headers (Python) ou passe o cabeçalho diretamente (API REST) para anexar marcas a uma solicitação:

Python (SDK do OpenAI)

from openai import OpenAI
import json
import os

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

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

request_tags = {"project": "chatbot", "team": "ml-platform"}

chat_completion = client.chat.completions.create(
  messages=[
    {"role": "user", "content": "What is Databricks?"},
  ],
  model="<model-service>",
  max_tokens=256,
  extra_headers={
    "Databricks-Ai-Gateway-Request-Tags": json.dumps(request_tags)
  }
)

Python (SDK do Anthropic)

import anthropic
import json
import os

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

request_tags = {"project": "chatbot", "team": "ml-platform"}

client = anthropic.Anthropic(
  api_key="unused",
  base_url="https://<workspace-url>/ai-gateway/anthropic",
  default_headers={
    "Authorization": f"Bearer {DATABRICKS_TOKEN}",
    "Databricks-Ai-Gateway-Request-Tags": json.dumps(request_tags),
  },
)

message = client.messages.create(
  model="<model-service>",
  max_tokens=256,
  messages=[
    {"role": "user", "content": "What is Databricks?"},
  ],
)

API REST

curl \
  -u token:$DATABRICKS_TOKEN \
  -X POST \
  -H "Content-Type: application/json" \
  -H 'Databricks-Ai-Gateway-Request-Tags: {"project": "chatbot", "team": "ml-platform"}' \
  -d '{
    "model": "<model-service>",
    "max_tokens": 256,
    "messages": [
      {"role": "user", "content": "What is Databricks?"}
    ]
  }' \
  https://<workspace-url>/ai-gateway/mlflow/v1/chat/completions

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

Próximas Etapas

Comentários

Esta página foi útil?

Last updated on 2026-08-21

Consultar APIs de modelos (serviços de modelos)

Comece a consultar APIs de modelos

Passo 1: Escolha uma API de modelo pronta para uso

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

Requirements

APIs e integrações com suporte

Serviços de modelo de consulta com APIs unificadas

API de Conclusões de Chat do MLflow

Python

API REST

MLflow Embeddings API

Python

API REST

Supervisor API

Python

API REST

Consultar serviços de modelo com ai_query

Consultar serviços de modelo com APIs nativas

API de respostas do OpenAI

Python

API REST

API de Mensagens da Anthropic

Python

API REST

Google Gemini API

Python

API REST

Marcar solicitações para rastreamento de uso

Python (SDK do OpenAI)

Python (SDK do Anthropic)

API REST

Próximas Etapas

Comentários

Recursos adicionais

Consultar serviços de modelo com `ai_query`