外部モデルプロバイダーのクエリ(モデルプロバイダーサービス)

Unity AI Gatewayを通じて 外部モデルプロバイダー (モデルプロバイダーサービス)にクエリを送り、保存された認証情報を提供し、リクエストを外部プロバイダーにルーティングするため、呼び出し者がプロバイダーの秘密を扱う必要がありません。

Requirements

• クエリを実行するためのワークスペース権限: ワークスペース アクセス、またはアカウントで Unity AI Gateway へのコンシューマー アクセス プレビューが有効になっている コンシューマー アクセス（パブリック プレビュー）。 「Manage entitlements」および「Manage Azure Databricks previews」をご覧ください。
• 次のアクセス許可が必要です。 「 外部モデルプロバイダーへのアクセスを発見し管理する(モデルプロバイダーサービス)」を参照してください。
  • モデル プロバイダー サービスの EXECUTE
  • カタログの USE CATALOG
  • スキーマの USE SCHEMA

モデル プロバイダー サービスを識別する

Databricks-Model-Provider-Service ヘッダーをサービスの 3 部構成の名前に設定して、リクエストに使用するモデル プロバイダー サービスを選択します。

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

プロバイダーの資格情報ではなく、Azure Databricks トークンで認証します。 ベース URL は、ワークスペースの URL の後に /ai-gateway。

サポートされている API のクエリ

マネージド パスは、安定した Unity AI ゲートウェイ パスで各プロバイダーの API を使用できるようにします。 Unity AI Gateway は、要求とプロバイダーの間で変換され、ガードレールやレート制限などのガバナンスを適用し、使用状況を記録します。 これは、モデル プロバイダー サービスに対してクエリを実行する場合に推奨される方法です。

次の例では、マネージド OpenAI パスを使用して、OpenAI モデル プロバイダー サービスを介してチャットの完了を送信します。 このリクエストでは OpenAI Chat Completions API を使用するため、OpenAI クライアントの接続先を Unity AI Gateway のベース URL に設定できます。

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

呼び出すマネージド パスは、プロバイダーの API によって異なります。

要求本文 (または Gemini パス セグメント) 内のモデルは、モデル プロバイダー サービスが許可するモデルである必要があります。

他の API のクエリ (パススルー)

管理パスがOpenAIファイルやバッチエンドポイントなどのプロバイダーエンドポイントをカバーしていない場合、リクエストを変更せずにプロバイダーに渡すことができます。 Unity AI Gateway は、 /ai-gateway プレフィックスを削除し、格納されている資格情報をアタッチして、残りのパスをプロバイダーに転送します。

アンマネージド パススルーを有効にするには、UI でモデル プロバイダー サービスを作成または更新するときに、[詳細オプション] で [すべての URL パスを転送] を選択します。

パススルーを有効にした後、 /ai-gatewayでプロバイダーのネイティブ パスを呼び出します。 たとえば、OpenAI ファイル エンドポイント上のファイルを一覧表示します。

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

ヘッダーとクエリ パラメーターの転送

既定では、Unity AI Gateway はクライアントの要求ヘッダーまたはクエリ パラメーターをアップストリーム プロバイダーに渡しません。 2 つのサービス構成フラグによってこれを変更し、マネージド パスとアンマネージド パスの両方に適用されます。

• forward_headers trueすると、Unity AI Gatewayはクライアントリクエストヘッダーをプロバイダーに転送します。 OpenAI-Organizationなど、Unity AI Gateway で設定されていないヘッダーがプロバイダーに必要な場合に有効にします。
• forward_query_parameters true時、Unity AI Gatewayはクライアントクエリパラメータをプロバイダーに転送します。

他の構成フィールドと同様に、それらをモデル プロバイダー サービスに設定します。

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

使用状況追跡のタグ要求

Databricks-Ai-Gateway-Request-Tags HTTP ヘッダーを使用して、個々の要求にカスタム キー値タグをアタッチできます。 Unity AI Gateway は、request_tagsシステム テーブルと推論テーブルの両方の列に要求タグをログに記録します。 その後、コスト、属性の使用状況を追跡し、プロジェクト、チーム、環境、または別のディメンションで分析をフィルター処理できます。

ヘッダー値は、文字列値に文字列キーをマッピングする JSON オブジェクトである必要があります。 例えば次が挙げられます。

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

Databricks-Model-Provider-Service ヘッダーと共にタグ ヘッダーを送信します。 extra_headers パラメーター (Python) を使用するか、ヘッダーを直接渡します (REST API)。

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

次のステップ

• 外部モデルプロバイダーへのアクセスを発見し管理する(モデルプロバイダーサービス)
• モデルの使用状況を追跡
• 外部モデルプロバイダーを管理する（モデルプロバイダーサービス）