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

Faça uma query em um provedor de modelo externo (serviço de provedor de modelo) por meio do Unity AI 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

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

Os caminhos gerenciados disponibilizam a API de cada provedor em um caminho estável do Unity AI Gateway. O Unity AI Gateway traduz entre a solicitação e o provedor, aplica governança como guardrails e limites de taxa, e registra o uso. Esta é a forma recomendada de consultar 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 modelos da OpenAI usando o caminho gerenciado da OpenAI. Como a solicitação usa a API de Conclusão do Chat da OpenAI, é possível direcionar o cliente OpenAI para a URL base do Unity AI 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 do provedor, como um endpoint de arquivo ou de lotes da OpenAI, você poderá passar a solicitação para o provedor sem alterações. O Unity AI 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 AI Gateway não passa os cabeçalhos de solicitação ou parâmetros de consulta do cliente para o provedor upstream. Duas flags de configuração de serviço alteram isso, e elas se aplicam a caminhos gerenciados e não gerenciados:

forward_headers: Quando true, o Unity AI 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 AI Gateway não define para você, como OpenAI-Organization.
forward_query_parameters: Quando true, o Unity AI 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 key-value personalizadas a solicitações individuais usando o cabeçalho HTTP Databricks-Ai-Gateway-Request-Tags. O Unity AI Gateway registra tags de solicitação na coluna request_tags, tanto na tabela do sistema de acompanhamento de uso quanto nas tabelas de inferência. É possível então acompanhar os custos, atribuir o 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​