Corebyte
日本語
English简体中文繁體中文日本語한국어
調達プランを相談
メニュー
← ドキュメント一覧に戻る

Microsoft Foundry・Azure OpenAI API 接続ガイド

デプロイ、v1エンドポイント、認証を確認し、呼び出しとストリーム・使用量を検証します。

対象範囲と前提条件

権限を持つ Azure サブスクリプション、リソース、モデルのデプロイがある状態から始めます。OpenAI Python SDK で Microsoft の v1 チャット API を呼び出す手順です。リソースの作成や、全モデルで同じ機能を使えることは前提にしません。ポータルでリソース名、実際のモデルの版、デプロイ名、種類、クォータ、ネットワーク経路を記録します。model には他社のカタログ名ではなく、自分のデプロイ名を指定します。

Chat Completions と例の max_completion_tokens に対応するデプロイを選んでください。Responses、ツール、画像、推論用パラメーター、ストリーミングは個別に確認します。Responses 非対応のモデルは URL を変えて再試行しても使えるようにはなりません。Azure OpenAI と Foundry の非 OpenAI モデルでは、機能と権限が異なります。プロジェクト管理のエンドポイントも推論用ではありません。

エンドポイントと権限を確認する

v1 の base_url はリソースの /openai/v1/ 経路を使います。対応する services.ai.azure.com のリソースドメイン形式も利用できます。ポータルの設定を確認し、プロジェクト URL や旧 /deployments/... 経路と混在させないでください。v1 は日付形式の api-version を必要としませんが、旧 API には固有のバージョン要件があります。

処理場所はデプロイの種類に依存します。Global、Data Zone、地域デプロイの境界をリソース名だけで判断しないでください。管理者に必要な範囲の推論権限を割り当ててもらいます。Azure OpenAI では Cognitive Services OpenAI User、Foundry の非 OpenAI モデルでは該当する Cognitive Services User の要件を確認します。Owner や Contributor が自動的に推論権限になるわけではありません。プロキシ、プライベートエンドポイント、DNS、ファイアウォールも確認します。

インストールと最小リクエスト

python3 -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade openai

以下の仮の値を実際のリソースとデプロイに置き換えます。AZURE_OPENAI_API_KEY は許可されたサーバー実行環境から安全に供給してください。ブラウザー、リポジトリ、共有する端末記録にキーを含めないでください。

export AZURE_OPENAI_BASE_URL='https://YOUR-RESOURCE.openai.azure.com/openai/v1/'
export AZURE_OPENAI_DEPLOYMENT='YOUR-DEPLOYMENT-NAME'

次を azure_chat.py に保存し、費用とテスト権限を確認してから python azure_chat.py を実行します。128 の出力制限と30秒のクライアントタイムアウトは例の設定であり、サービスのクォータや対応保証ではありません。最初は自動再試行を0にし、元のエラーを確認しやすくしています。

import os
from openai import OpenAI

client = OpenAI(
    base_url=os.environ["AZURE_OPENAI_BASE_URL"],
    api_key=os.environ["AZURE_OPENAI_API_KEY"],
    timeout=30.0,
    max_retries=0,
)
request = {
    "model": os.environ["AZURE_OPENAI_DEPLOYMENT"],
    "messages": [{"role": "user", "content": "Reply with one short greeting."}],
    "max_completion_tokens": 128,
}
answer = client.chat.completions.create(**request)
if not answer.choices:
    raise RuntimeError("No completion choice returned")
print(answer.choices[0].message.content or "")
print(answer.usage.model_dump() if answer.usage else "usage unavailable")

Entra ID に置き換える

サーバーではマネージド ID など、承認された Entra 認証チェーンを利用できます。依存パッケージを追加し、上の client 初期化を次に置き換えます。先にロールを割り当て、実行時の ID を確認してください。アクセストークンを表示してはいけません。現在の公式 v1 例の scope は https://ai.azure.com/.default です。

python -m pip install --upgrade azure-identity

from azure.identity import DefaultAzureCredential, get_bearer_token_provider

token_provider = get_bearer_token_provider(
    DefaultAzureCredential(), "https://ai.azure.com/.default"
)
client = OpenAI(
    base_url=os.environ["AZURE_OPENAI_BASE_URL"],
    api_key=token_provider,
    timeout=30.0,
    max_retries=0,
)

ストリームとエラーを処理する

ストリーミング対応を確認したら、非ストリーミングの呼び出しを次に置き換えます。添字を使う前に choices を確認し、差分のテキストを読みます。usage があれば別に取得します。対応する使用量オプションが必要なデプロイもあり、usage がないことは料金ゼロを意味しません。Responses のイベント構造には別の解析処理が必要です。

usage = None
with client.chat.completions.create(**request, stream=True) as events:
    for part in events:
        if part.usage is not None:
            usage = part.usage
        if not part.choices:
            continue
        text = part.choices[0].delta.content
        if text:
            print(text, end="", flush=True)
print()
print(usage.model_dump() if usage else "usage unavailable")
  • 401/403：認証元、リソース範囲、ロール、ネットワークを確認し、キーやトークンをログに残さない。
  • 404：ドメイン、v1 経路、デプロイ名を確認し、管理用 URL との混同を避ける。
  • 400：モデルの API、パラメーター、内容制限を確認し、任意パラメーターを減らして原因を絞る。
  • 429：クォータと同時実行数を確認し、応答の待機指示と有限のバックオフを使う。タイムアウトや5xxを無限に再試行しない。

受入確認、費用、データの扱い

機密情報を除いたリクエスト番号、モデルとデプロイの版、finish reason、時間、使用量を残して請求と照合します。出力打ち切り、拒否、接続切断の動作も確認します。出力、キャッシュ、予約容量、第三者サービスの費用は実際の契約条件で調べ、別の経路の単価を流用しないでください。

保存、コンテンツ安全処理、Global デプロイの処理範囲は適用される条件で確認します。アプリのログとアクセスは別に制御します。本例はオフラインの構文確認のみです。サブスクリプションの利用、秘密情報の読み取り、実モデル呼び出しは行っていません。利用可否、品質、費用は承認された環境で検証してください。

Claude：ネイティブ API と購入資格を確認する

Claude は独立した Messages API を使います。AnthropicFoundry の接続先にはリソースの https://YOUR-RESOURCE.services.ai.azure.com/anthropic を指定し、HTTP Messages の送信先は /anthropic/v1/messages です。リクエストの model は実際のデプロイ名であり、カタログのモデル ID と異なる場合があります。前述の OpenAI v1 の例は、その API に明示的に対応するデプロイに適用されます。Foundry のプロジェクト管理 URL、OpenAI v1 のパス、Claude のネイティブパスは、それぞれ用途が異なります。パートナーモデルのカタログに掲載されているだけでは、OpenAI API との互換性は確認できません。

クライアントを設定する前に、次の順に確認してください。

  1. 対象が利用資格のある Azure の有料サブスクリプションで、請求先の国が対応範囲に含まれ、Marketplace オファーを購入する権限があることを確認します。現在の Microsoft の Claude ドキュメントは、Cloud Solution Provider（CSP）サブスクリプションを対象外と明記しています。ほかのサブスクリプション制限もあるため、Azure アカウントがあるだけでは購入資格の証明になりません。
  2. モデルカードとデプロイの詳細から、モデル、ホスティングのバージョン、デプロイの種類、現在対応しているデプロイリージョンを記録します。バージョン 1 は Anthropic のインフラで稼働し、バージョン 2 は Azure 上でホストされます。どちらも Global Standard に対応し、Data Zone Standard（US）は Azure 上でホストされる一部のモデルバージョンに限られます。リソースの所在国から推測せず、モデル、バージョン、種類の正確な組み合わせを確認します。
  3. ネイティブエンドポイントとデプロイ名をコピーします。Entra で推論を行う場合は、Foundry リソースのスコープに Cognitive Services User ロールが割り当てられていることと、実際の実行 ID を確認します。Azure OpenAI 専用ロールやリソース管理ロールでは、この確認を代替できません。ネットワークアクセスも別途確認します。
  4. デプロイが対応する認証方式、Messages のパラメーター、ストリーミング、クォータを確認します。利用が制限された一部のモデルは Entra ID のみを受け付けます。Files、Skills、ツールなどの高度な機能はホスティングとモデルバージョンによって異なるため、別の Claude デプロイのパラメーターをそのまま流用しないでください。

Anthropic がホストする v1 のリクエストは、Azure および選択した Azure リージョンの外で処理される場合があります。Azure がホストする v2 でも、Global または Data Zone の処理範囲と、保存データの所在地を分けて確認します。どちらの構成でも、Anthropic が販売者、運営者であり、プロンプトと出力の独立したデータ処理者です。Claude の Marketplace 条件とデータ処理条件を適用してください。Azure OpenAI の保持期間や SLA の説明が、自動的に Claude に適用されるわけではありません。

Claude：API キーを使う独立した最小リクエスト

API キーを受け付けるデプロイでは、権限を持つサーバー環境に依存パッケージをインストールし、次のプレースホルダーを設定します。キーは安全なサーバーのシークレット環境から供給し、ブラウザーのコードやコピーするサンプルに書き込まないでください。次の Python は、独立した Claude の例として保存します。今回実施したのはオフラインの確認のみで、パッケージのインストールやクラウドへのリクエストは行っていません。出力上限とタイムアウトは例示の制御値であり、SDK の自動再試行は無効にしています。

以下の API キー方式と Entra 方式は、どちらも base_url を明示します。SDK は ANTHROPIC_FOUNDRY_RESOURCE も自動的に読み込むため、設定前にこの環境変数を解除してください。別の方法として resource で初期化する場合は、base_url を渡さず、自動読込用の ANTHROPIC_FOUNDRY_BASE_URL も解除します。

python -m pip install --upgrade anthropic azure-identity
# Explicit base_url must not be combined with the SDK resource-name fallback.
unset ANTHROPIC_FOUNDRY_RESOURCE
# Copy both values from your actual Foundry deployment in the console.
export FOUNDRY_CLAUDE_BASE_URL='https://YOUR-RESOURCE.services.ai.azure.com/anthropic'
export FOUNDRY_CLAUDE_DEPLOYMENT='YOUR-CLAUDE-DEPLOYMENT-NAME'
# Supply FOUNDRY_CLAUDE_API_KEY through the approved server secret environment.

import os
from anthropic import AnthropicFoundry

client = AnthropicFoundry(
    base_url=os.environ["FOUNDRY_CLAUDE_BASE_URL"],
    api_key=os.environ["FOUNDRY_CLAUDE_API_KEY"],
    timeout=30.0,
    max_retries=0,
)
message = client.messages.create(
    model=os.environ["FOUNDRY_CLAUDE_DEPLOYMENT"],
    max_tokens=128,
    messages=[{"role": "user", "content": "Reply with one short greeting."}],
)
for block in message.content:
    if block.type == "text":
        print(block.text)
print(message.stop_reason)
print(message.usage.model_dump())

レスポンスは型付きの content ブロックを返します。テキストブロックだけを出力し、stop_reason と usage を確認してから結果を受け入れてください。ネイティブ HTTP は x-api-key と anthropic-version: 2023-06-01 を使用し、OpenAI の choices レスポンス形式は使いません。thinking やツールのパラメーターは、デプロイが対応する組み合わせを確認してから追加します。

Claude：API キーを Entra ID に置き換える

前例の import os、AnthropicFoundry、Messages リクエストを残し、クライアントの初期化だけを次のコードに置き換えます。承認された資格情報チェーンを使い、可能ならアプリケーションのマネージド ID を選び、リソースのロールを先に確認してください。azure_ad_token_provider は https://ai.azure.com/.default のスコープに対するトークンを取得します。ネイティブ HTTP では Authorization: Bearer ... に相当します。認証方式は一つに限定し、この provider を使う場合は、明示的な API キーと SDK が自動的に読み込む ANTHROPIC_FOUNDRY_API_KEY の設定を除いてください。トークンは出力しません。

from azure.identity import DefaultAzureCredential, get_bearer_token_provider

token_provider = get_bearer_token_provider(
    DefaultAzureCredential(), "https://ai.azure.com/.default"
)
client = AnthropicFoundry(
    base_url=os.environ["FOUNDRY_CLAUDE_BASE_URL"],
    azure_ad_token_provider=token_provider,
    timeout=30.0,
    max_retries=0,
)

Claude：ストリーミング、障害、受入確認

対応するデプロイでは、Messages に stream=True を指定すると SSE を受信できます。ネイティブのイベントは message_start、インデックス付きの content_block_start / content_block_delta / content_block_stop、続いて message_delta と message_stop の順に進みます。テキスト差分は delta.type == "text_delta" を使い、ツールや thinking は別のブロック型を使います。ping、未知のイベント、エラーを別々に処理し、最終的な使用量と停止情報を保存してください。完了前に接続が切れたストリームは未完了として扱います。OpenAI の choices[].delta や Responses のイベントパーサーでは、このプロトコルを解析できません。HTTP ステータスが成功でも、ストリームの正常完了は保証されません。

Claude の 401/403 では、選択した認証方式、トークンのスコープ、リソースのロールを確認します。404 では /anthropic と正確なデプロイ名を確認します。400 は未対応のパラメーターやモデル固有のデータ保持要件が原因の場合があり、後者は適用条件に従って確認が必要です。購入やリージョンのエラーでは、サブスクリプションの資格とモデルバージョンの可用性を確認します。429 では、サブスクリプション、モデル、バージョンのクォータを確認し、再試行回数を制限します。別リージョンにリソースを作っても、同じ Global クォータプールを共有する場合があります。前述の OpenAI デプロイの料金を流用せず、実際の Marketplace の Claude Consumption Unit（CCU）メーターと入出力、キャッシュ使用量を請求と照合してください。承認された環境で機密情報を含まない正常出力、出力の打ち切り、ストリーム切断をそれぞれ試してから、接続を受け入れます。

公式資料

確認日：2026-10-17。使用前に最新の資料とポータルを再確認してください。