APIs de consulta de modelos (serviços de modelos)

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

Note

Quando um serviço de modelo encaminha para um destino de serviço de fornecedor de modelos, apenas se aplicam as funcionalidades do Unity AI Gateway do serviço de modelo (como limites de débito, proteções, tabelas de inferência e alternativas de recurso). Todas as funcionalidades do Unity AI Gateway que estejam configuradas no próprio serviço do fornecedor de modelos são ignoradas.

Comece a consultar APIs de modelos

Consulte uma API de modelo em dois passos:

Passo 1: Escolha uma API de modelo pronta a usar

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

Passo 2: Enviar um pedido usando a API unificada compatível com OpenAI

Utilize a API MLflow Chat Completions com o SDK de 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, consulte Introdução à consulta de LLMs no Databricks.

Requirements

Um espaço de trabalho Azure Databricks numa região suportada por Unity AI Gateway.
Unity Catalog ativado para o seu espaço de trabalho. Consulte Habilitar um espaço de trabalho para o Unity Catalog.
Permissão do espaço de trabalho a consultar: Acesso ao espaço de trabalho ou Acesso de consumidor com a pré-visualização Acesso de consumidor ao Unity AI Gateway ativada para a sua conta (Pré-visualização pública). Veja Gerir direitos de acesso e Gerir versões de pré-visualização do Azure Databricks.

APIs e integrações suportadas

O Unity AI Gateway suporta as seguintes APIs e integrações:

APIs unificadas: interfaces compatíveis com OpenAI para consultar modelos no Azure Databricks. Alterna perfeitamente entre modelos de diferentes fornecedores sem alterar a forma como consultas cada modelo.
APIs nativas: Interfaces específicas do fornecedor para aceder ao modelo mais recente e funcionalidades específicas do fornecedor.
Agentes de programação: Integre os seus agentes de codificação com o Unity AI Gateway para adicionar governação centralizada e monitorização aos seus fluxos de trabalho de desenvolvimento assistidos por IA. Veja integração com agentes de codificação.
Agentes nas Apps Databricks: Criar e implementar agentes nas Apps Databricks que encaminham o tráfego LLM através do Unity AI Gateway. Ver Passo 4. Regule o uso de LLMs pelos seus agentes nas aplicações Databricks com o Unity AI Gateway.
ai_query: Use ai_query para consultar serviços de modelo fornecidos pelo Azure Databricks a partir de SQL ou Python para inferência em lote. Veja 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 facilmente entre modelos de diferentes fornecedores sem alterar o seu código.

MLflow Chat Completions API

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

Supervisor API

Supervisor API

A API Supervisor (/mlflow/v1/responses) é uma API compatível com OpenResponses, independente do fornecedor, para construir agentes em Beta. Os administradores do espaço de trabalho podem ativar isso a partir da página de Pré-visualizações . Ver Gerir as pré-visualizações de Azure Databricks. Escolha o melhor modelo para o caso de uso do seu agente entre os fornecedores, sem alterar o 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> pelo URL do seu workspace do Azure Databricks e <model-service> pelo nome totalmente qualificado do seu serviço modelo.

Consultar serviços de modelo com `ai_query`

Pode usar a ai_query função para consultar serviços de modelo diretamente a partir de SQL ou Python. Isto permite-lhe captar informação de rastreamento de utilização para as suas cargas de trabalho de inferência em lote.

Note

ai_queryo suporte para o Unity AI Gateway está disponível apenas para modelos fornecidos pelo Azure Databricks. Introduza o nome do endpoint do modelo base do Azure Databricks, que inclui um 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 utilizado noutras partes desta página. Os serviços de modelo que cria no Unity AI Gateway ainda não são suportados.
Apenas o rastreamento de utilização aplica-se a ai_query cargas de trabalho de inferência em lote. Outras funcionalidades do Unity AI Gateway, como limites de pedidos, mecanismos de salvaguarda, tabelas de inferência e mecanismos de recurso, não se aplicam.

Para consultar um serviço modelo com ai_query, executa 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 do sistema de rastreamento de utilização (system.ai_gateway.usage) captura pedidos feitos aos ai_query serviços do modelo. Estes pedidos também aparecem no painel de utilização incorporado.

Para sintaxe completa ai_query e referência de parâmetros, veja ai_query função. Para conhecer as melhores práticas e os modelos suportados, consulte Utilizar ai_query.

Consultar serviços de modelos com APIs nativas

As APIs nativas oferecem interfaces específicas de fornecedores para consultar modelos no Azure Databricks. Use APIs nativas para aceder às funcionalidades mais recentes específicas de cada fornecedor.

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

Use a API OpenAI Responses para consultar serviços de modelos apoiados por modelos OpenAI (GPT).
Utilize a API Messages da Anthropic para consultar serviços de modelos suportados pelos modelos Claude.
Use a API do Google Gemini para consultar serviços de modelos apoiados por modelos Gemini.

Para consultar um serviço de modelo, independentemente do modelo em que assenta, utilize as APIs unificadas em alternativa.

API de Respostas OpenAI

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

Anthropic Messages API

Anthropic Messages API

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

Pedidos de etiquetas para monitorização de utilização

Pode anexar etiquetas-chave-valor personalizadas a pedidos individuais usando o Databricks-Ai-Gateway-Request-Tags cabeçalho HTTP. As etiquetas de pedido são registadas na request_tags coluna tanto na tabela do sistema de rastreio de utilização como nas tabelas de inferência, permitindo-lhe acompanhar custos, utilização de atributos e filtrar análises por projeto, equipa, ambiente ou qualquer outra dimensão.

O valor do cabeçalho deve ser um objeto JSON que mapeia chaves de cadeia para valores de cadeia. Por exemplo:

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

Use o parâmetro extra_headers (Python) ou passe diretamente o cabeçalho (API REST) para anexar etiquetas a um pedido:

Python (SDK 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 (Anthropic SDK)

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

Passos seguintes

Comentários

Esta página foi útil?

Last updated on 2026-08-21

APIs de consulta de modelos (serviços de modelos)

Comece a consultar APIs de modelos

Passo 1: Escolha uma API de modelo pronta a usar

Passo 2: Enviar um pedido usando a API unificada compatível com OpenAI

Requirements

APIs e integrações suportadas

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 modelos com APIs nativas

API de Respostas OpenAI

Python

API REST

Anthropic Messages API

Python

API REST

Google Gemini API

Python

API REST

Pedidos de etiquetas para monitorização de utilização

Python (SDK OpenAI)

Python (Anthropic SDK)

API REST

Passos seguintes

Comentários

Recursos adicionais

Consultar serviços de modelo com `ai_query`