apigee-x-ai-gateway

Apigee X AI ゲートウェイ

使用する場面

• Apigee X AI ゲートウェイプロキシを構築、変更、または調査します。プロキシファイル、オペレーター向けセットアップ手順、テスト計画を提供します。
• オペレーターによるデプロイや、インポート前の準備を支援します。組織の作成を含むインフラストラクチャの変更には、承認が必要です。
• Anthropic 形式への変換とストリーミングは実装されていません。ストリーミングリクエストは明示的に拒否してください。

依存関係とツール

• プロキシ作業全体を通じて、ピン留めされた apigee-x-proxy-development スキルを使用してください。見つからない場合は作業を中止し、ユーザーにインストールを依頼してください。
• 各ポリシー、フロー、条件を作成する前に、ピン留めされた依存関係マップを使用して、該当する正確なリファレンスを開いてください。引き継ぎ時には、各ファイルと、その作成時に開いたリファレンスを一覧にしてください。
• 構文はリファレンスに従ってください。ゲートウェイのリファレンスと開発スキルは、ポリシー XML、フロー、条件、変数の信頼できる情報源です。利用可否、利用資格、クォータ、料金は時間とともに変わるため、最新の公式ドキュメントまたはユーザーに確認してください。開発スキルと公式ドキュメントに相違がある場合は、競合時の指針に従ってください。
• 選択したワークフローで説明されているものだけを構築してください。まずワークフローを最後まで読んでください。リクエストや詳細が記載されていない場合は、その旨を伝えて確認してください。
• カスタムフロー変数の先頭に、Apigee が所有するプレフィックス（request., response., message., route., target., proxy., client., system., fault., error., apiproxy., environment., organization.）を付けてはいけません。カスタムフロー変数を参照してください。
• **ツール：**ターミナルとファイルのツールを使用してください。apigeecli のコマンドは --help で確認し、フラグや API 呼び出しを決してでっち上げないでください。

機能	リファレンス	成果物
Vertex AI チャットターゲット	Vertex ターゲット	OpenAI 互換の Gemini エンドポイント、Google ネイティブ認証、オペレーターによる API／IAM セットアップ
ルーティング	ルーティング	エイリアス、エンドポイント、認証のマッピング、バンドル、ルートチェック
累積トークン数	LLMTokenQuota	API Product に基づく上限、カウンターのスコープ、ペアのポリシー、カウンターのテスト
API キーとプロダクト設定	API Product のセットアップ	オペレーターが実施するプロダクト、デベロッパー、アプリ、属性の手順と読み戻し
支出予算	コスト予算	API Product の価格と予算、コスト計算、ペアのコストカウンター、テスト
プロンプトのバースト	PromptTokenLimit	レート、信頼できる ID、プロンプトの完全な情報源、障害テスト
プロンプトとレスポンスの保護	Model Armor	障害時の契約、テンプレートと ID の準備状況、安全性テスト
FAQ の再利用	セマンティックキャッシュおよび試験運用チェックリスト	固定構成、すべての呼び出し元に安全な回答、ゲート付きバンドル
Vertex の依存関係が不足している場合	オペレーターのセットアップ	ガイド付き作成、ZIP の作成前に正確な ID と URL を確認

共通の確認事項

コマンド実行前にロケーションを確認

• 各リージョン依存関係の処理場所と保存場所について合意します。リージョンを推測してはいけません。合意するまでは __APPROVED_REGION__ と __APPROVED_TEMPLATE_LOCATION__ をそのまま使用してください。
• 各モデル、フィルター、埋め込みモデル、Vector Search の利用可否を個別に確認し、クォータと接続性も確認します。承認済みの読み取りアクセス権がある場合は、正確なリソース名とロケーションを読み取って確認します。
• 共有リソースを移動・変更したり、データ所在地の要件やフィルターを弱めたりしてはいけません。Model Armor については、ロケーションマッピングに従ってください。

プライバシー

• 設定情報、認証情報、プライベートエンドポイント、テストの生出力は Git の外部に保管します。
• チャットでシークレットを尋ねたり、XML、JavaScript、properties にキーを埋め込んだりしてはいけません。トークンをコマンド引数や詳細トレースに含めないでください。
• 取得前に、コピーしたネイティブ変数をマスキングします。認証ヘッダー、機密性の高いプロンプト、生のレスポンスをログに記録してはいけません。レスポンスから内部ルーティングメタデータを削除します。

手順

1. 確認します。 提供された設定を読み、不足している項目をすべてまとめて質問し、それぞれに推奨案を示します。組織、環境、プロキシ名、ベースパス、エンドポイント、モデル、形式、呼び出し元とバックエンドの認証、ストリーミング、テスト予算を確認します。外部/KVM または Vertex AI を明示的に選択します。Vertex AI の場合は、セットアップファイルまたはターゲットファイルを生成する前にVertex ターゲットを読みます。エイリアスと未知のモデルに対するエラーを合意し、暗黙のフォールバックは決して行わず、明示的な拒否を推奨します。既存の識別子は維持します。
2. 承認を得て、ベースラインを確立します。 プロジェクト、所有者、変更内容、公開範囲、呼び出し上限を確認します。読み取り、バックエンド呼び出し、セットアップと IAM、デプロイ、継続的に発生するコスト、試行について、それぞれ個別の承認を得ます。承認されたバックエンドに対して、小規模な合成呼び出しで確認し、ステータス、解決されたモデル、使用量を記録します。認証エラーはユーザーとともに解決し、確認せずに再試行することは決してありません。
3. 段階的に構築します。
   • 動作中のプロキシとオペレーターによる変更は維持します。実ファイルを作成し、まずネイティブポリシーを使用します。
   • バックエンド呼び出しの前に、モデルの許可リストを検証し、エイリアスを変換します。呼び出し元の認証とアップストリームの認証は分離します。
   • ターゲット URL が固定の場合は、TargetEndpoint のリクエストフローで Boolean の target.copy.pathsuffix=false を設定します。
   • すべてのルートで、バックエンドの認証情報を挿入する前に、呼び出し元の認証情報ヘッダーを削除します。
   • 参照先を確認せずに書き込んだファイルには未検証の印を付け、確認を求めます。
   • ポリシー、適用順序、XML、参照、ZIP 構造を確認します。
4. 承認されたとおりにインポートしてデプロイします。 ランタイム認証情報について個別の承認を得ます。ZIP を作成する前に、該当するVertex ターゲット、Model Armor、セマンティックキャッシュの引き継ぎ情報を提示します。手動手順を自分で実行することは決してありません。承認されたリビジョンのみをデプロイします。段階的な更新では、オペレーター向けの引き継ぎに現在のデプロイの確認と明示的なリビジョン置き換えを含めます。個別のアンデプロイを求めるのではなく、承認された置き換えには override=true を使用します。各書き込みの後に、設定と準備状況を読み戻して確認します。
5. 検証して引き継ぎます。
   • API キーを使用するすべてのプロキシについて、生成したプロキシ用のAPI プロダクトのセットアップ手順を提示します。トークンの割り当て上限を設定する場合は、プロダクトの LLM 操作に関するモデル名を一覧にし、それらは呼び出し元のエイリアスではなくバックエンドのモデル ID であることを説明します。
   • オペレーターが実行するラボでは、デプロイ手順の後に、設定済みのホスト名、ベースパス、エイリアスを使用した、コピー可能な curl テストコマンドを表示します。引数やログにシークレットを含めない安全なキー入力、小規模な合成リクエスト、出力トークン数の上限、期待されるステータスと本文の確認、承認済みのコスト上限内に収まる明示的な最大呼び出し回数を含めます。上限のないループや自動再試行は決して使用しません。これらのコマンドはオペレーターが実行します。自分では実行しません。
   • 各ラボの成功ケースと拒否ケースを網羅します。マスキングされた診断情報によって、ポリシーをどのように特定し、バックエンドが呼び出されたかどうかをどのように確認できるかを説明します。HTTP ステータスだけでは不十分です。呼び出し上限に達したら停止し、再現できなかったケースは未検証として報告します。
   • 受け入れテストは個別に承認された場合にのみ実行します。それ以外の場合は、オペレーターが実行するコマンドを提示します。構造チェック、バックエンドへの直接呼び出しの結果、デプロイ済みプロキシの結果を分けて報告します。
   • 構築してテストした内容、保持されるリソースとコスト、不足事項を報告します。
   • 承認なしでクリーンアップや公開を行うことはありません。

検証の境界

• ステータスコードだけでなく、エラーボディを確認してください。 エラー形式設定ポリシーが実行されても、Apigee のネイティブエラーがそのままワイヤー上に残り、呼び出し元の ID やポリシー名が漏れることがあります。サニタイズ済みエラーを参照してください。
• 既知の制限（機能のステータス）：変更されていないパススルーで検証できるのはアップストリームのルーティングであり、Apigee のリクエストマッピングではありません。非ストリーミングの結果からストリーミングについては何もわかりません。また、ルーティングだけでは完全なゲートウェイにはなりません。