Consultar provedores de modelo externos (serviços de provedores modelo)

Consulte um provedor de modelo externo (serviço de provedor modelo) através do Unity AI Gateway, que fornece as credenciais armazenadas e direciona a solicitação para o provedor externo, para que os chamadores não lidam com o segredo do provedor.

Requirements

• 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.
• As permissões a seguir são necessárias. Veja Descobrir e regular o acesso a provedores modelo externos (serviços de provedores modelo).
  • EXECUTE no serviço do provedor de modelos
  • USE CATALOG no catálogo
  • USE SCHEMA no esquema

Identificar um serviço de provedor de modelos

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

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

Autentique com o token Azure Databricks, não com a credencial do provedor. A URL base é a URL do seu espaço de trabalho seguida por /ai-gateway.

Consultar APIs compatíveis

Os caminhos gerenciados disponibilizam a API de cada provedor em um caminho estável do Gateway de IA do Unity. O Unity AI Gateway faz a mediação entre a solicitação e o provedor, aplica políticas de governança, como guardrails e limites de requisições, e registra o uso. Essa é a maneira recomendada de consultar um serviço de provedor de modelos.

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

Python

from openai import OpenAI

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

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

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:

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

Consultar outras APIs (passagem)

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

Para habilitar a passagem não gerenciada, selecione Encaminhar todos os caminhos de URL em opções avançadas ao criar ou atualizar o serviço de provedor de modelos na interface do usuário.

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

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 consulta

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

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

Defina-os no serviço do provedor de modelos como qualquer outro campo de configuração:

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 } }'

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. O Unity AI Gateway registra tags de solicitação na coluna request_tags tanto na tabela de sistema de rastreamento de uso quanto nas tabelas de inferência. Em seguida, você pode acompanhar os custos, o uso de atributos e a análise de filtro por projeto, equipe, ambiente ou 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" }

Envie o cabeçalho de tags junto com o cabeçalho Databricks-Model-Provider-Service. Use o extra_headers parâmetro (Python) ou passe o cabeçalho diretamente (API 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={"Databricks-Model-Provider-Service": "main.default.openai_prod"},
)

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={"Databricks-Ai-Gateway-Request-Tags": json.dumps(request_tags)},
)

REST

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óximas Etapas 

• Descubra e regule o acesso a provedores modelo externos (serviços de provedores-modelo)
• Rastrear o uso do modelo
• Gerenciar provedores externos de modelos (serviços de provedores de modelos)