query provedores de modelos externos (serviços de provedor de modelo)

Faça query em um provedor de modelo externo (serviço de provedor de modelo) por meio do Unity Gateway, que fornece as credenciais armazenadas e encaminha a solicitação para o provedor externo, para que os chamadores não manipulem o segredo do provedor.

Requisitos

Direito do Workspace para fazer query: Acesso ao Workspace ou Acesso do consumidor com a prévia Acesso do consumidor ao Unity Gateway habilitada para sua conta (Pré-visualização pública). Consulte Gerenciar direitos e Gerenciar prévias do Databricks.
As seguintes permissões são necessárias. Consulte Descobrir e governar o acesso a provedores de modelos externos (serviços de provedor de modelos).
- EXECUTE no serviço de provedor de modelo
- USE CATALOG no catálogo
- USE SCHEMA no esquema

Identifique um serviço de provedor de modelos

Selecione um serviço de provedor de modelos para uma solicitação com o cabeçalho Databricks-Model-Provider-Service, definido para o nome de três partes do serviço:

Text
Databricks-Model-Provider-Service: main.default.openai_prod

Autentique-se com seu token Databricks, não com a credencial do provedor. A URL base é sua URL de workspace seguida por /ai-gateway.

Consultar APIs Suportadas

Caminhos gerenciados disponibilizam a API de cada provedor sob um caminho estável do Unity Gateway. O Unity Gateway traduz entre a solicitação e o provedor, aplica governança, como proteções e limites de taxa, e registra o uso. Esta é a maneira recomendada de fazer query de um serviço de provedor de modelo.

O exemplo a seguir envia uma conclusão de chat por meio de um serviço de provedor de modelo OpenAI usando o caminho gerenciado da OpenAI. Como a solicitação usa a API de Conclusão de Chat da OpenAI, você pode apontar o cliente OpenAI para a URL base do Unity Gateway.

Python
REST

Python
from openai import OpenAI

client = OpenAI(
    api_key="<databricks-token>",
    base_url="https://<workspace-url>/ai-gateway/openai/v1",
    default_headers={&quot;Databricks-Model-Provider-Service&quot;: &quot;main.default.openai_prod&quot;},
)

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Say hello in exactly 3 words."}],
)
print(response.choices[0].message.content)

Bash
curl https://<workspace-url>/ai-gateway/openai/v1/chat/completions \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  -H "Databricks-Model-Provider-Service: main.default.openai_prod" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "Say hello in exactly 3 words."}]
  }'

O caminho gerenciado que você chama depende da API do provedor:

API do Provedor	Caminho gerenciado
OpenAI (conclusões de chat)	`/ai-gateway/openai/v1/chat/completions`
OpenAI (respostas)	`/ai-gateway/openai/v1/responses`
OpenAI (incorporações)	`/ai-gateway/openai/v1/embeddings`
Anthropic (mensagens)	`/ai-gateway/anthropic/v1/messages`
Gemini (gerar conteúdo)	`/ai-gateway/gemini/v1beta/models/<model>:generateContent`
Gemini (gerar conteúdo com respostas de transmissão)	`/ai-gateway/gemini/v1beta/models/<model>:streamGenerateContent`

API do Provedor	Caminho gerenciado
OpenAI (conclusões de chat)	`/ai-gateway/openai/v1/chat/completions`
OpenAI (respostas)	`/ai-gateway/openai/v1/responses`
OpenAI (incorporações)	`/ai-gateway/openai/v1/embeddings`
Anthropic (mensagens)	`/ai-gateway/anthropic/v1/messages`
Gemini (gerar conteúdo)	`/ai-gateway/gemini/v1beta/models/<model>:generateContent`
Gemini (gerar conteúdo com respostas de transmissão)	`/ai-gateway/gemini/v1beta/models/<model>:streamGenerateContent`

O modelo no corpo da solicitação (ou o segmento de caminho do Gemini) deve ser um modelo que o serviço de provedor de modelo permite.

Consultar Outras APIs (Passagem)

Se um caminho gerenciado não cobrir um endpoint de provedor, como um arquivo da OpenAI ou um endpoint de lotes, você poderá encaminhar a solicitação para o provedor sem alterações. O Unity Gateway remove o prefixo /ai-gateway, anexa a credencial armazenada e encaminha o caminho restante para o provedor.

Para habilitar o passthrough não gerenciado, selecione **Encaminhar todos os caminhos de URL** em **Opções avançadas** ao criar ou atualizar o serviço de provedor de modelo na UI.

nota

O token de uso e o acompanhamento de custo, os limites de taxa baseados em tokens, o controle de acesso a modelos e as políticas de serviço não se aplicam a solicitações de passthrough.

Depois de habilitar o passthrough, chame o caminho nativo do provedor em /ai-gateway. Por exemplo, liste arquivos no endpoint de arquivos do OpenAI:

Bash
curl https://<workspace-url>/ai-gateway/files \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  -H "Databricks-Model-Provider-Service: main.default.openai_prod"

Encaminhamento de cabeçalhos e parâmetros de query

Por default, o Unity Gateway não passa os cabeçalhos de solicitação ou parâmetros de query do cliente para o provedor upstream. Dois sinalizadores de configuração de serviço alteram isso, e eles se aplicam a caminhos gerenciados e não gerenciados:

forward_headers: Quando true, o Unity Gateway encaminha os cabeçalhos de solicitação do cliente para o provedor. Habilite isso quando um provedor exigir um cabeçalho que o Unity Gateway não define para você, como OpenAI-Organization.
forward_query_parameters: Quando true, o Unity Gateway encaminha os parâmetros de query do cliente para o provedor.

Configure-os no serviço de provedor de modelo como qualquer outro campo de configuração:

Bash
curl https://<workspace-url>/api/2.1/unity-catalog/model-provider-services/main.default.openai_prod \
  -X PATCH \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  -H "Content-Type: application/json" \
  -G \
  --data-urlencode "update_mask=config.forward_headers,config.forward_query_parameters" \
  --data '{ "config": { "forward_headers": true, "forward_query_parameters": true } }'

Solicitações de tag para acompanhamento de uso

Você pode anexar tags personalizadas de chave-valor a solicitações individuais usando o cabeçalho HTTP Databricks-Ai-Gateway-Request-Tags. O Unity Gateway Logs tags de solicitação na coluna request_tags tanto na tabela do sistema de acompanhamento de uso quanto nas tabelas de inferência. Você pode então acompanhar custos, atribuir uso e filtrar a analítica por projeto, equipe, ambiente ou outra dimensão.

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

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

Envie o cabeçalho de tags junto com o cabeçalho Databricks-Model-Provider-Service. Use o parâmetro extra_headers (Python) ou passe o cabeçalho diretamente (API REST):

Python
REST

Python
from openai import OpenAI
import json

client = OpenAI(
    api_key="<databricks-token>",
    base_url="https://<workspace-url>/ai-gateway/openai/v1",
    default_headers={&quot;Databricks-Model-Provider-Service&quot;: &quot;main.default.openai_prod&quot;},
)

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

response = client.chat.completions.create(
    model="gpt-5.5",
    messages=[{"role": "user", "content": "What is Databricks?"}],
    extra_headers={&quot;Databricks-Ai-Gateway-Request-Tags&quot;: json.dumps(request_tags)},
)

Bash
curl https://<workspace-url>/ai-gateway/openai/v1/chat/completions \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  -H "Databricks-Model-Provider-Service: main.default.openai_prod" \
  -H "Content-Type: application/json" \
  -H 'Databricks-Ai-Gateway-Request-Tags: {"project": "chatbot", "team": "ml-platform"}' \
  -d '{
    "model": "gpt-5.5",
    "messages": [{"role": "user", "content": "What is Databricks?"}]
  }'

Requisitos​

Identifique um serviço de provedor de modelos​

Consultar APIs Suportadas​

Consultar Outras APIs (Passagem)​

Encaminhamento de cabeçalhos e parâmetros de query​

Solicitações de tag para acompanhamento de uso​

Próximos os passos​