Azure OpenAI、リクエストヘッダーによるコンテンツフィルター切替の実装ガイド──4つの落とし穴と回避策
デプロイを分けずに x-policy-id ヘッダーで RAI ポリシーを切り替える実務上の仕様と、ドキュメントにない落とし穴を検証する。
リリース: 2026-08-31 · 読了 3 分記事の要約
1. 核心（What）
- Azure OpenAI の API 呼び出しにおいて、x-policy-id ヘッダーを 1 本追加することでリクエストごとにポリシーを動的に差し替えられる
- ポリシー名の値は大文字小文字を厳格に区別するが、HTTP ヘッダー名自体はケースを問わない
- レスポンスボディ内の content_filter_results に含まれるキーの構成変化（例: custom_blocklists の有無）から適用されたポリシーの指紋を検知できる
- blocking: false 設定のポリシーでは検出フラグが true でも HTTP ステータス 200 で正常レスポンスが返る
2. 影響（Why）
- デプロイ管理コストの削減: 従来はポリシーごとにデプロイを分ける必要があったが、ヘッダー 1 本で切り替えられるためモデル容量や管理負荷を抑えられる。
- 国内マルチテナント運用の効率化: [国内 AI アプリ開発企業] のように顧客ごとに異なるセーフティポリシーを適用したい開発現場で、インフラ構成を複雑化させずに要件を満たせる。
3. 根拠・詳細（How）
- レスポンスキーによるポリシー適用確認: レスポンスに適用ポリシー名は返らないため、prompt_filter_results 内の content_filter_results のキー構成（custom_blocklists 等）をアサートして適用を担保する。
- カスタムブロックリストによる検証: severity しきい値ではなくカスタムブロックリスト（禁止語: pancake）を用いて、安全にフィルタリングの挙動とポリシー切替の成否を検証。
4. 展望・課題（Next）
- 散発的なエラーへの対策: 正しいポリシー名でも InvalidContentFilterPolicy が散発的に返る現象に対する、リトライ機構やエラーハンドリングの設計が求められる。