Consultar serviços de provedor de modelo

info

Beta

este recurso está em Beta. Os administradores de conta podem gerenciar o acesso a esse recurso na página **Prévias** do console da conta. Consulte Gerenciar prévias do Databricks.

Esta página descreve como consultar um serviço de provedor de modelo através do Unity AI Gateway. O Unity AI Gateway fornece as credenciais armazenadas e encaminha a solicitação ao provedor externo, para que os chamadores não precisem lidar com o segredo do provedor.

Requisitos

• Prévia do Unity AI Gateway ativada para sua account. Consulte Gerenciar prévias do Databricks.
• As seguintes permissões são necessárias. Consulte Descobrir e governar o acesso a serviços de provedores de modelo.
  • 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

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)

REST

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

O modelo no corpo da solicitação (ou o segmento de caminho Gemini) deve ser um modelo que o serviço de provedor de modelos permite. Consulte Crie e gerencie serviços de provedor de modelo para allow_all_targets e targets.

Consultar Outras APIs (Passagem)

Se um caminho gerenciado não cobrir um endpoint de provedor — por exemplo, um arquivo OpenAI ou endpoint de lotes —, você pode passar a solicitação diretamente para o provedor sem alterações. Unity AI Gateway remove o prefixo /ai-gateway, anexa a credencial armazenada e encaminha o caminho restante para o provedor.

A passagem não gerenciada está desativada por default. Habilite-o no serviço de provedor de modelo definindo forward_unmanaged_paths como true na configuração do serviç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_unmanaged_paths" \
  --data '{ "config": { "forward_unmanaged_paths": true } }'

Depois de ativar a passagem, chame o caminho nativo do provedor em /ai-gateway:

Bash

curl https://<workspace-url>/ai-gateway/v1/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

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)},
)

REST

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?"}]
  }'

Próximos os passos

• Descubra e governe o acesso a serviços de provedores de modelos
• Uso do modelo para serviços do Unity AI Gateway
• Serviços de provedor de modelo no Unity Catalog