Azure AI FoundryでAzure OpenAIを使っている管理者・開発者がまず確認すべき点は、「日付付きのapi-versionを追い続ける設計」から「/openai/v1/を中心にした設計」へ移行できるかです。2026年5月14日に更新されたMicrosoft Learnの「Azure OpenAI in Microsoft Foundry Models v1 API」は、認証の簡略化、api-versionパラメーター不要化、OpenAIクライアントの利用、DeepSeekやGrokなどを含むクロスプロバイダーモデル呼び出しを整理した公式情報です。既存システムをすぐ全面改修するというより、SDK・エンドポイント・RBAC・モデルデプロイ・APIゲートウェイ設定を棚卸しし、v1 APIへ段階的に寄せるのが現実的な対応です。(Microsoft Learn)
Azure AI Foundryのv1 APIで何が変わるのか
今回のポイントは、Azure OpenAIの使い方が「Azure専用のAPIバージョン管理」から、よりOpenAI API互換の形に近づいたことです。従来は新機能を使うたびに2024-xx-xx-previewのようなAPIバージョンを指定し、SDKや環境変数も更新する必要がありました。v1 APIでは、OpenAI()クライアントを使い、Azure側のエンドポイントに/openai/v1/を付けたbase_urlを指定する形が基本になります。(Microsoft Learn)
| 観点 | 従来のよくある構成 | v1 APIでの考え方 | 実務上の影響 |
|---|---|---|---|
| APIバージョン | api-version=2024-xx-xx-previewを明示 | v1 GA APIではapi-version指定が必須ではない | 月次のAPIバージョン追従作業を減らせる |
| SDKクライアント | AzureOpenAI()などAzure専用クライアント | OpenAI()クライアントを利用 | OpenAI API互換コードとの差分を小さくできる |
| エンドポイント | APIバージョン付きのAzure OpenAIエンドポイント | https://<resource>.openai.azure.com/openai/v1/など | ルーティング、プロキシ、APIM設定の見直しが必要 |
| 認証 | APIキーまたはAzure向けクライアント依存 | APIキーまたはMicrosoft Entra IDトークン | 本番環境ではIDベース認証とRBAC設計が重要 |
| モデル呼び出し | 主にAzure OpenAIモデル単位 | Azure OpenAIモデルに加え、v1構文対応の他プロバイダーモデルも呼び出せる | モデルごとの互換性テストが必要 |
| レスポンス | 固定項目を前提にしがち | 新しい応答オブジェクトが追加される可能性あり | 必要なフィールドだけを解析する実装にする |
特に注意したいのは、v1 APIになっても「すべての機能が同じタイミングで本番利用できる」という意味ではないことです。公式ドキュメントでは、初期のv1 GA APIでは推論・オーサリングAPI機能のサブセットのみがサポートされ、プレビュー機能は機能固有のヘッダーやAPIパスでオプトインする形と説明されています。(Microsoft Learn)
影響範囲はアプリ本体だけではない
Azure OpenAI in Microsoft Foundry Models v1 APIの影響は、単なるコード変更にとどまりません。社内Copilot、チャットボット、RAG、業務自動化、評価パイプラインなどでAzure AI Foundryを使っている場合、以下の範囲をまとめて確認する必要があります。
| 対象 | 確認すべきこと | 見落とすと起きやすい問題 |
|---|---|---|
| アプリケーションコード | api-version、AzureOpenAI()、古いエンドポイント指定の有無 | v1 APIへ移行したつもりでも旧ルートへ送信される |
| SDK・依存パッケージ | openaiパッケージへの移行可否 | サンプルコードと実行環境のSDKが合わずエラーになる |
| 認証方式 | APIキー継続か、Microsoft Entra IDへ寄せるか | 権限が広すぎるキー運用が残る |
| RBAC | API利用権限とFoundry管理権限の分離 | 開発者に不要な管理権限を与えてしまう |
| モデルデプロイ | デプロイ名、モデルバージョン、リージョン、更新ポリシー | 本番と検証で出力や可用性がずれる |
| APIゲートウェイ | APIM、WAF、社内プロキシのパス・ヘッダー制御 | 404、401、429が切り分けにくくなる |
| 監視・運用 | レート制限、トークン使用量、429対応 | リリース後に遅延や失敗が増える |
Microsoftは、Foundryとアプリケーションの統合パターンとして、コネクター利用、REST API直接呼び出し、APIゲートウェイ経由の3パターンを示しています。OpenAI APIの形を期待するSDKや外部ツールではOpenAI v1互換ルートを使い、モデルプロバイダーに依存しないFoundry APIやエージェント系のstateful APIとは使い分ける必要があります。(Microsoft Learn)
管理者が最初に確認すべき設定
リソース、リージョン、モデルデプロイを確認する
v1 APIを使う前提として、Azureサブスクリプション、サポートされるリージョンに配置されたFoundryリソースまたはAzure OpenAIリソース、少なくとも1つのモデルデプロイが必要です。つまり、コードだけをv1 API向けに変えても、対象モデルが未デプロイ、リージョン非対応、クォータ不足であれば呼び出しは成功しません。(Microsoft Learn)
管理者は、FoundryポータルまたはAzureポータルで次の順に確認すると切り分けが早くなります。
| 確認項目 | 判断基準 |
|---|---|
| リソース種別 | FoundryリソースまたはAzure OpenAIリソースが対象環境にあるか |
| リージョン | 使いたいモデルとResponses APIなどの機能がそのリージョンで利用可能か |
| モデルデプロイ | アプリで指定するmodelが実際のデプロイ名と一致しているか |
| クォータ | 検証・本番それぞれのRPM/TPMや容量が足りるか |
| ネットワーク | APIM、Private Endpoint、社内プロキシで/openai/v1/が許可されているか |
クォータはテナント単位ではなくAzureサブスクリプションを上位スコープとして扱われ、制限値はモデルやデプロイ種類によって変わる可能性があります。429エラーや遅延増加が出る場合は、再試行ロジック、負荷の段階的な増加、クォータ引き上げ、必要に応じたPTUの検討が実務上の対策になります。(Microsoft Learn)
RBACは「API呼び出し」と「Foundry管理」を分けて考える
Microsoft Entra ID認証を使う場合、v1 APIの公式ドキュメントではIDにCognitive Services OpenAI Userロールが必要とされています。一方、Microsoft Foundryのプロジェクト管理やポータル操作では、Foundry User、Foundry Project Manager、Foundry OwnerなどのFoundry向けロールを使うのが基本です。API実行権限と管理権限を混同すると、開発者に過剰な権限を付与しやすくなります。(Microsoft Learn)
本番運用では、APIキーよりもMicrosoft Entra ID認証を優先して検討する価値があります。RBACドキュメントでは、キー認証はロール制限なしにフルアクセスを与えるため、きめ細かな制御にはEntra ID認証が推奨されています。キーを使う場合でも、Key Vaultでの保管、ローテーション、環境別キー分離、ログへの出力禁止は最低限の運用ルールにしてください。(Microsoft Learn)
開発者向けの移行手順
既存コードの棚卸しから始める
最初にやるべき作業は、いきなりコードを書き換えることではありません。リポジトリ、CI/CD変数、IaC、APIMポリシー、アプリ設定を横断して、旧APIや旧SDKに依存している箇所を洗い出します。
grep -R "api-version\|AzureOpenAI\|azure-ai-inference\|/models\|/openai/deployments" .特にazure-ai-inferenceパッケージやhttps://<resource>.services.ai.azure.com/modelsパスを新規統合で使い続けるのは避けるべきです。Microsoftは新規統合ではFoundry Model Inference APIの/modelsパスを使わず、OpenAI v1互換ルートを使うよう案内しており、azure-ai-inferenceパッケージは2026年5月30日にリタイア予定とされています。(Microsoft Learn)
エンドポイントを/openai/v1/に寄せる
Pythonの例では、従来のAzureOpenAI()からOpenAI()へ寄せ、base_urlにAzure側のv1エンドポイントを指定します。公式ドキュメントでは、base_urlとしてopenai.azure.com形式とservices.ai.azure.com形式の両方が示されていますが、利用しているリソース種類、プロジェクト構成、社内ゲートウェイ設計に合わせて統一してください。(Microsoft Learn)
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["AZURE_OPENAI_API_KEY"],
base_url="https://<your-resource>.openai.azure.com/openai/v1/"
)
response = client.responses.create(
model="<your-deployment-name>",
input="社内FAQの要点を3行で要約してください。"
)
print(response.output_text)ポイントは、modelに指定する値を「基盤モデル名」ではなく、実際にAzure AI FoundryまたはAzure OpenAI側で作成したデプロイ名として扱うことです。検証環境と本番環境でデプロイ名が違う場合は、コードに直書きせず環境変数や設定ファイルで切り替えます。
Microsoft Entra ID認証ではトークン更新を前提にする
v1 APIでは、OpenAI()クライアントでトークンベース認証と自動トークン更新を扱えるようになり、従来のAzure専用クライアントへの依存を減らせます。ローカル開発ではDefaultAzureCredential、本番ではマネージドIDやサービスプリンシパルを使い、どのIDにどのロールを付与したかを構成管理に残してください。(Microsoft Learn)
実装時の失敗で多いのは、APIキー向けの設定とBearerトークン向けの設定を混ぜることです。401が出たら「キーが間違っている」と決めつけず、トークンスコープ、ロール割り当て、ヘッダー名、ゲートウェイ側でのヘッダー転送を順に確認しましょう。
Responses APIとChat Completionsの使い分け
Azure OpenAIモデルでは、公式ドキュメント上はResponses APIの利用が推奨されています。一方で、v1 APIはOpenAI v1のChat Completions構文をサポートするDeepSeekやGrokなど、他プロバイダーのモデル呼び出しにも対応します。つまり、今後の標準はResponses APIを軸にしつつ、外部プロバイダーモデルや既存チャット実装ではChat Completionsを併用する形が現実的です。(Microsoft Learn)
| 利用シーン | 優先したいAPI | 理由 |
|---|---|---|
| 新規のAzure OpenAIアプリ | Responses API | 今後の機能拡張を取り込みやすい |
| 既存のチャットUI | Chat CompletionsまたはResponses API | 既存コード量と移行コストで判断 |
| DeepSeekやGrokなどのクロスプロバイダー呼び出し | Chat Completions対応を確認 | モデル側がv1チャット構文をサポートする必要がある |
| エージェント、評価、ツール統合 | Responses API中心 | Foundryの新しい機能群と相性がよい |
ただし、モデルが変わると出力の粒度、ツール呼び出しの挙動、安全性フィルター、トークン消費が変わることがあります。モデル横断の呼び出しを有効にする場合は、同じプロンプトセットで品質評価、レイテンシ、コスト、失敗率を比較してから本番へ展開してください。
プレビュー機能を使う場合の注意点
v1 APIでは、プレビュー機能にアクセスするために毎回APIバージョンを切り替えるのではなく、機能固有のプレビュー用ヘッダーや、alphaなどを含むAPIパスでプレビュー状態を示す方式が採用されています。たとえば、過去にプレビューだった/openai/v1/evalsは現在プレビューではなくなり、/openai/v1/fine_tuning/alpha/graders/はパス上のalphaでプレビュー扱いを示します。(Microsoft Learn)
管理者・開発者が気を付けるべきなのは、プレビュー機能を本番依存にしすぎないことです。プレビューAPIは仕様変更の可能性があり、APIゲートウェイや監視ツールがヘッダーやパスを正しく扱えない場合もあります。特にAPI Managementを使っている環境では、2025-04-01-previewのAzure OpenAI仕様がOpenAPI 3.1を使っており、Azure API Managementで完全にはサポートされていない既知の問題がある点も確認しておきましょう。(Microsoft Learn)
モデルバージョンとAPIバージョンを混同しない
移行計画でよくある誤解は、「APIをv1にすればモデルの挙動も固定される」と考えることです。Microsoft Foundry Modelsでは、モデル自体のバージョンと、モデルデプロイを呼び出すAPIバージョンは別物です。モデルデプロイにはアップグレードポリシーがあり、新しい既定バージョンへ自動更新する設定、現在のバージョンの期限切れ時に更新する設定、自動アップグレードをオプトアウトする設定などがあります。(Microsoft Learn)
実務では、次のように分けて管理すると事故を減らせます。
| 管理対象 | 管理方法 | チェックタイミング |
|---|---|---|
| APIバージョン | v1 APIルート、SDK、APIMルーティングで管理 | SDK更新時、API仕様変更時 |
| モデルバージョン | Foundryポータルのデプロイ詳細やREST APIで確認 | モデル更新通知時、本番リリース前 |
| デプロイ名 | 環境変数・設定ファイルで管理 | 環境追加時、Blue/Green切替時 |
| 出力品質 | 評価データセットで回帰テスト | モデル変更時、プロンプト変更時 |
| コスト・容量 | クォータ、RPM/TPM、使用量メトリックで監視 | 負荷試験時、本番運用中 |
モデルの提供終了日を迎えた場合、自動アップグレードをオプトアウトしているデプロイは要求の受け入れを停止し、エラーを返す可能性があります。重要なワークロードでは、モデル更新通知、Service Healthアラート、廃止スケジュールを運用プロセスに組み込んでください。(Microsoft Learn)
移行時によくあるエラーと切り分け
v1 API移行では、エラーの原因がコード、認証、ネットワーク、モデルデプロイ、クォータのどこにあるかを素早く切り分けることが重要です。
| エラー | 主な原因 | 確認ポイント |
|---|---|---|
| 401 Unauthorized | APIキー不備、期限切れトークン、ロール不足 | キー、Bearerトークン、RBAC、マネージドID |
| 404 Not Found | エンドポイントパス、リソース名、デプロイ名の誤り | /openai/v1/の有無、デプロイ名、APIMルート |
| 429 Too Many Requests | レート制限、クォータ不足、急な負荷増 | 再試行、バックオフ、負荷平準化、クォータ申請 |
| DNS resolution failure | ドメイン指定ミス | openai.azure.comとservices.ai.azure.comの使い分け |
| 期待と違う出力 | モデルバージョン変更、プロンプト差分 | モデルバージョン、デプロイ設定、評価データ |
Microsoftの統合ガイドでも、401、404、429、DNS解決失敗が代表的なトラブルとして整理されています。移行後の初回リリースでは、エラー率だけでなく、応答時間、トークン使用量、モデル別の失敗率、ゲートウェイでの拒否件数もダッシュボード化しておくと、原因調査が早くなります。(Microsoft Learn)
本番展開前のチェックリスト
v1 APIへの移行は、小さく検証してから段階的に展開するのが安全です。特に社内Copilotや業務アプリに組み込んでいる場合、API変更がユーザー体験に直結します。
| フェーズ | 実施内容 |
|---|---|
| 棚卸し | api-version、AzureOpenAI()、azure-ai-inference、旧エンドポイントを洗い出す |
| 設計 | OpenAI v1互換ルート、Foundry API、プロジェクトエンドポイントの使い分けを決める |
| 権限 | Entra ID、RBAC、マネージドID、APIキー運用を見直す |
| 実装 | OpenAI()クライアント、base_url、環境変数、レスポンス解析を更新する |
| 検証 | 代表プロンプト、RAG、ツール呼び出し、ストリーミング、エラー処理をテストする |
| 負荷試験 | 429、レイテンシ、トークン消費、クォータ余力を確認する |
| 展開 | カナリアリリースや環境別デプロイで段階的に切り替える |
| 運用 | モデル更新、クォータ、エラー率、コストを継続監視する |
v1 APIへの移行で最も大切なのは、APIの書き換えを「開発チームだけの作業」にしないことです。Azure管理者はリージョン、RBAC、クォータ、ゲートウェイを確認し、開発者はSDK、エンドポイント、レスポンス解析、リトライ処理を更新します。まずは既存コードを棚卸しし、検証環境で/openai/v1/ルートを使った最小構成の呼び出しを成功させるところから始めてください。
コメント