Consulta fornitori di modelli esterni (servizi di fornitori di modello)

Interroga un fornitore di modelli esterno (servizio provider modello) tramite Unity AI Gateway, che fornisce le credenziali memorizzate e instrada la richiesta al provider esterno, così i chiamanti non gestiscono il segreto del fornitore.

Requisiti

• Autorizzazione dell'area di lavoro per la query: Accesso all'area di lavoro oppure Accesso Consumer con l'anteprima Accesso Consumer a Unity AI Gateway abilitata per il tuo account (Anteprima pubblica). Vedi Gestire i diritti e Gestire le anteprime di Azure Databricks.
• Sono necessarie le autorizzazioni seguenti. Vedi Scopri e regola l'accesso a fornitori modello esterni (servizi di fornitori modello).
  • EXECUTE nel servizio del fornitore di modelli
  • USE CATALOG sul catalogo
  • USE SCHEMA sullo schema

Identifica un servizio di fornitura di modelli

Si seleziona un servizio provider di modelli per una richiesta con l'intestazione Databricks-Model-Provider-Service , impostato sul nome in tre parti del servizio:

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

Eseguire l'autenticazione con il token di Azure Databricks, non con le credenziali del provider. L'URL di base è l'URL dell'area di lavoro seguito da /ai-gateway.

Eseguire query sulle API supportate

I percorsi gestiti rendono disponibile l'API di ogni provider in un percorso stabile del gateway di intelligenza artificiale Unity. Unity AI Gateway funge da intermediario tra la richiesta e il provider, applica criteri di governance quali guardrail e limiti di velocità, e registra l'utilizzo. Questo è il modo consigliato per eseguire query su un servizio provider di modelli.

L'esempio seguente invia un completamento della chat tramite un servizio provider di modelli OpenAI usando il percorso OpenAI gestito. Poiché la richiesta usa l'API OpenAI Chat Completions, è possibile puntare il client OpenAI all'URL di base del gateway di intelligenza artificiale 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."}]
  }'

Il percorso gestito chiamato dipende dall'API del provider:

Il modello nel corpo della richiesta (o nel segmento di percorso Gemini) deve essere un modello consentito dal servizio provider di modelli.

Interrogare altre API (inoltro)

Se un percorso gestito non copre un endpoint fornitore, come un file OpenAI o un endpoint batch, puoi trasmettere la richiesta al provider senza modifiche. Unity AI Gateway rimuove il /ai-gateway prefisso, collega le credenziali archiviate e inoltra il percorso rimanente al provider.

Per abilitare il pass-through non gestito, selezionare Inoltra tutti i percorsi URL in Opzioni avanzate quando si crea o si aggiorna il servizio provider di modelli nell'interfaccia utente.

Dopo aver abilitato la modalità pass-through, richiama il percorso nativo del provider sotto /ai-gateway. Ad esempio, elencare i file nell'endpoint dei file OpenAI:

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

Inoltro di intestazioni e parametri di query

Per impostazione predefinita, il gateway IA di Unity non inoltra al provider a monte né le intestazioni della richiesta del client né i parametri di query. Due flag di configurazione del servizio modificano questo valore e si applicano sia ai percorsi gestiti che non gestiti:

• forward_headers: Quando true, Unity AI Gateway inoltra le intestazioni delle richieste del client al provider. Abilitare questa opzione quando un provider richiede un'intestazione non impostata da Unity AI Gateway, ad esempio OpenAI-Organization.
• forward_query_parameters: Quando true, Unity AI Gateway inoltra i parametri delle query client al provider.

Impostarli nel servizio provider di modelli come qualsiasi altro campo di configurazione:

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

Contrassegna le richieste di rilevamento dell'utilizzo

È possibile associare tag chiave-valore personalizzati a singole richieste usando l'intestazione Databricks-Ai-Gateway-Request-Tags HTTP. Unity AI Gateway registra i tag delle richieste nella colonna request_tags sia nella tabella di sistema di monitoraggio dell'utilizzo sia nelle tabelle di inferenza. È quindi possibile tenere traccia dei costi, dell'utilizzo degli attributi e filtrare l'analisi in base a progetto, team, ambiente o un'altra dimensione.

Il valore dell'intestazione deve essere un oggetto JSON che associa chiavi stringa a valori stringa. Per esempio:

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

Inviare l'intestazione dei tag insieme all'intestazione Databricks-Model-Provider-Service. Usare il extra_headers parametro (Python) o passare direttamente l'intestazione (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?"}]
  }'

Passaggi successivi

• Scopri e regola l'accesso a fornitori modello esterni (servizi fornitori modello)
• Monitora l'utilizzo del modello
• Governare i fornitori di modelli esterni (servizi di fornitori di modello)