konnect-ai-gateway

Konnect AI Gateway のトリアージ

目標

リクエスト経路、プロバイダーのターゲティング、AI ポリシー、AI ランタイムの可視性のうち、Konnect AI Gateway の障害が発生している最も限定的なレイヤーを診断します。

このスキルは AI Gateway のオペレーター向けワークフローに使用し、一般的なプロンプトエンジニアリング、プロバイダー SDK のデバッグ、モデル品質の評価には使用しないでください。

ツールの選択

• コントロールプレーン、Gateway エンティティ、LLM 分析の画面をリアルタイムに調査するには、まず共有の kong-konnect MCP サーバーを使用します。
• ユーザーがトークン使用量、レイテンシ、AI リクエストの健全性について尋ねている場合は、LLM に特化した分析を優先します。一般的な API 分析ではなく、AI ランタイムのデータが本題の場合は、LLM 分析の MCP／クエリ画面を使用します。
• 実装には、リポジトリで採用されている宣言型ツールチェーンを維持します。Gateway エンティティの GitOps には deck-gateway、HCL で管理する Konnect AI Gateway リソースには terraform-konnect、セルフマネージドの HCL には terraform-kong-gateway を使用します。kongctl-declarative は、周辺の Konnect リポジトリですでにその方法が採用されている場合にのみ使用します。
• ライブの Konnect 状態が重要で、kong-konnect MCP が接続されていない場合は、そのことを早い段階で伝え、リポジトリの設定またはユーザー提供の成果物を使って調査を続けます。
• 問題が AI 固有のレイヤーではなく、一般的なゲートウェイへの到達性、ロールアウト、またはルート／サービスの健全性にある場合は、早めに konnect-gateway-triage へ引き継ぎます。

読み込むリファレンス

最初に該当するリファレンスを読み込みます。デフォルトでは3つすべてを読み込まないでください。

• references/provider-routing.md
  • 主な質問がモデル／プロバイダーの選択、ルートのターゲティング、フォールバック、またはプロバイダー固有のリクエスト動作に関する場合に読み込みます。
• references/guardrails-and-policy-intent.md
  • トラフィックは技術的に機能しているものの、ポリシーの意図、プロンプトの調整、またはガバナンスの動作に問題がある場合に読み込みます。
• references/observability-and-cost-signals.md
  • リクエストの構築ではなく、トークン、レイテンシ、AI 固有の分析、または運用上の可視性についての質問の場合に読み込みます。

調査の順序

1. レイヤーを選ぶ前に報告内容を分類する

最初の症状を次のいずれかに分類します。

• プロバイダーのルーティングまたはモデルのターゲティング
• AI トラフィック向けのサービス／ルート設定
• AI Proxy または AI Proxy Advanced の動作
• プロンプトまたは応答のガードレール
• プロンプトの装飾またはテンプレートの動作
• セマンティックキャッシュの動作
• LLM の使用状況、レイテンシ、またはトークンの可視性
• AI トラフィックにたまたま影響しているだけの、一般的なゲートウェイへの到達性または設定のロールアウト

AI Gateway の問題をすべて「プラグインの不具合」と一括りにしないでください。

問題の本質が通常のルートまたはサービスの健全性にある場合は、AI 制御を診断する前に konnect-gateway-triage へ引き継ぎます。

2. AI トラフィックの基本経路を確認する

まず、次の点を確認します。

• AI リクエストが想定どおりのサービスとルートに到達している
• オペレーターが想定する場所に AI プロキシレイヤーが適用されている
• プロバイダー認証に関する要件が明確になっている
• 想定するプロバイダーとモデルのターゲットが、推測ではなく把握されている

それから、プロンプトガードやテンプレートなどの上位レベルの AI ポリシーについて考えます。

リクエストがプロバイダーの経路に正常に到達していない場合は、ガードレールより下のレイヤーに留まり、プロバイダーのルーティングまたはゲートウェイの健全性に関する分岐を検討し続けます。

3. ポリシーより先にプロバイダーまたはモデルのターゲティングを解決する

ガバナンス対象の LLM トラフィックについては、次の順序でスタックを調査します。

• 基本的な AI プロキシ
• ルーティングとモデル／プロバイダーの選択
• 認証とアクセス制御
• プロンプトの装飾またはテンプレートの挿入
• プロンプト／応答のガードレール
• セマンティックキャッシュまたはその他の高速化レイヤー

これにより、ルートまたはプロバイダーレイヤーに問題があるのに、ガードレールの症状を追い続けてしまうことを防げます。

オペレーターがトラフィックの行き先、フォールバックの発生有無、または誤ったモデル／プロバイダーが応答したかどうかを尋ねている場合は、references/provider-routing.md を読み込みます。

4. プロキシ動作を確認してからポリシーレイヤーを評価する

ベースラインのプロキシ動作とルーティング先が適切だと確認できたら、次の問題を切り分けます。

• プロンプトへの装飾やテンプレートの挿入に関するエラー
• プロンプトまたはレスポンスのガードレールの不一致
• セマンティックキャッシュの動作
• Kong 側では制御できないプロバイダー／モデルの動作

運用担当者が技術的に有効なトラフィックとポリシーに適合したトラフィックを区別する必要がある場合は、references/guardrails-and-policy-intent.md を読み込みます。

5. AI 固有のランタイムに関する疑問には LLM アナリティクスを使用する

使用量、トークン、レイテンシ、またはコストに関する動作が問題の場合は、汎用 API アナリティクスよりも LLM アナリティクスを優先します。

AI 固有のオブザーバビリティを使って、次の点を確認します。

• リクエストが AI Gateway に到達しているか
• トークン使用量が想定どおりか
• レイテンシやエラー率が、ルート、プロバイダー、モデルのいずれかに集中しているか

実際の問題がランタイムの可視性、トークンの動作、またはレイテンシの集中に関するものであれば、references/observability-and-cost-signals.md を読み込みます。

6. Kong 側のガバナンスとプロバイダーの動作を区別する

リクエストがプロバイダーに到達しているにもかかわらず、正しく動作しない場合は、次の点を切り分けます。

• Kong 側のルーティングとポリシーの意図
• プロバイダー側のモデルの動作
• プロンプト構築の影響
• 認証またはキー管理に関する想定

モデルの不適切なレスポンスをすべて Gateway のバグだと断定しないでください。

7. AI の障害ドメインを最も限定して特定する

問題を次のいずれかに分類します。

• ルートまたはサービスの設定の問題
• AI プロキシ／プロバイダー設定の問題
• 認証またはシークレット管理の問題
• プロンプトへの装飾／テンプレートの問題
• ガードレールポリシーの問題
• セマンティックキャッシュまたはアクセラレーションの問題
• トラフィック障害ではなく、アナリティクス／可視性の問題
• このスキルの範囲外で対応すべき、汎用 Gateway の健全性の問題

Konnect 固有の注意点

• AI Gateway はあくまで Gateway を基盤とする機能です。ルート、サービス、プラグインの配置は引き続き重要です。
• プロンプトとレスポンスのガードレールは、動作中の AI プロキシ経路を拡張するものであり、その代わりにはなりません。
• LLM アナリティクスは、汎用 API アナリティクスとは別個のランタイム機能として扱う必要があります。
• 技術的に成功したプロバイダーのレスポンスでも、ポリシーの意図に反する場合があります。
• プロバイダー側の拒否、クォータ、またはモデルの動作は、正常な AI Gateway 経路を通過する可能性があります。Gateway の欠陥だと判断する前に、Kong 側の意図を確認してください。
• クイックスタートはベースラインの機能を確認するのに役立ちますが、長期的に運用可能な AI Gateway の運用モデルの代わりにはなりません。

検証チェックリスト

回答する前に、次の点を明確に説明できることを確認してください。

• AI Gateway のどのレイヤーで障害が発生しているか
• 高度な AI 制御を追加する前に、ベースラインのプロキシ動作が機能しているか
• リクエストが到達する想定のサービス／ルートとプロバイダー／モデル
• フォールバックまたは代替プロバイダーの選択が、意図的か偶発的か
• 問題が Kong 側のルーティング、認証、ガードレール、プロンプトの形成、キャッシュ、プロバイダーの動作、アナリティクスのどれに該当するか
• 次の手順として、LLM アナリティクスと他のどのオブザーバビリティ機能を使うべきか
• 変更を担当すべき宣言型ツールスキル

引き継ぎ

• 主な問題が AI Gateway 自体の動作ではなくデータセットの可視性である場合は、konnect-observability-triage を使用します。
• 実際の障害要因が AI 固有のレイヤーではなく、汎用 Gateway の接続性または設定の展開である場合は、konnect-gateway-triage を使用します。
• 運用担当者が AI Gateway の変更を設定として記述または適用したい場合は、deck-gateway、terraform-konnect、terraform-kong-gateway、または kongctl-declarative を使用します。