Consultar fornecedores de modelos externos (serviços de fornecedor de modelo)

Consulta um fornecedor de modelos externo (serviço de fornecedor modelo) através do Unity AI Gateway, que fornece as credenciais armazenadas e encaminha o pedido para o fornecedor externo, para que os chamadores não tratem do segredo do fornecedor.

Requirements

• 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.
• São necessárias as seguintes permissões. Consulte Descobrir e regular o acesso a fornecedores modelo externos (serviços de prestadores modelo).
  • EXECUTE no serviço do fornecedor de modelos
  • USE CATALOG no catálogo
  • USE SCHEMA no esquema

Identificar um serviço de prestador modelo

Seleciona um serviço de fornecedor modelo para um pedido com o Databricks-Model-Provider-Service cabeçalho, definido para o nome em três partes do serviço:

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

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

Consultar APIs Suportadas

Os caminhos geridos disponibilizam a API de cada fornecedor sob um caminho estável do Unity AI Gateway. O Unity AI Gateway traduz entre o pedido e o fornecedor, aplica governação como proteções e limites de taxa, e regista a utilização. Esta é a forma recomendada de consultar um serviço modelo de prestador.

O exemplo seguinte envia uma conclusão de chat através de um serviço fornecedor de modelos OpenAI usando o caminho gerido do OpenAI. Como o pedido utiliza a API OpenAI Chat Completions, pode apontar o cliente OpenAI para a URL base do Unity AI Gateway.

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 gerido a que recorre depende da API do fornecedor:

O modelo no corpo do pedido (ou segmento do caminho Gemini) deve ser um modelo que o serviço do fornecedor de modelos permite.

Consultar outras APIs (Passthrough)

Se um caminho gerido não abranger um ponto de extremidade do fornecedor, como um ponto de extremidade de ficheiros ou de lotes da OpenAI, pode encaminhar o pedido para o fornecedor sem alterações. O Unity AI Gateway remove o /ai-gateway prefixo, anexa a credencial armazenada e encaminha o caminho restante para o fornecedor.

Para ativar a passagem não gerida, selecione Encaminhar todos os caminhos de URL em Opções Avançadas quando criar ou atualizar o serviço de fornecedor de modelos na interface.

Depois de ativar o passthrough, utilize o caminho nativo do fornecedor em /ai-gateway. Por exemplo, listar ficheiros no endpoint de ficheiros 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 defeito, o Unity AI Gateway não transmite os cabeçalhos de pedido ou parâmetros de consulta do cliente para o fornecedor a montante. Duas flags de configuração de serviço alteram isto, e aplicam-se tanto a caminhos geridos como não geridos:

• forward_headers: Quando true, o Unity AI Gateway encaminha os cabeçalhos dos pedidos do cliente para o fornecedor. Ative isto quando um fornecedor precisar de um cabeçalho que o Unity AI Gateway não define para si, como OpenAI-Organization.
• forward_query_parameters: Quando true, o Unity AI Gateway encaminha os parâmetros da consulta do cliente para o fornecedor.

Defina-os no serviço de fornecedor 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 } }'

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. O Unity AI Gateway regista as etiquetas do pedido na coluna request_tags tanto na tabela de sistema de rastreio de utilização como nas tabelas de inferência. Pode então acompanhar custos, atribuir o uso de atributos e filtrar análises por projeto, equipa, ambiente ou 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" }

Envie o cabeçalho de etiquetas juntamente 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?"}]
  }'

Passos seguintes

• Descubra e regule o acesso a fornecedores modelo externos (serviços de prestadores modelo)
• Monitorizar a utilização do modelo
• Gerir fornecedores externos de modelos (serviços de fornecedores de modelos)