konnect-ai-gateway

Konnect AI Gateway 排查

目标

诊断 Konnect AI Gateway 故障具体发生在哪一层：请求路径、提供商目标、AI 策略或 AI 运行时可见性。

此技能适用于 AI Gateway 运维工作流，不适用于通用提示词工程、提供商 SDK 调试或模型质量评估。

工具选择

• 优先使用共享的 kong-konnect MCP 服务，实时检查控制平面、Gateway 实体和 LLM 分析界面。
• 如果用户询问 Token 用量、延迟或 AI 请求健康状况，请优先使用 LLM 专属分析。如果真正的问题在于 AI 运行时数据，而非通用 API 分析，请使用 LLM 分析 MCP／查询界面。
• 实施时保留代码库选定的声明式工具链：使用 deck-gateway 管理 Gateway 实体 GitOps，使用 terraform-konnect 管理由 HCL 管理的 Konnect AI Gateway 资源，使用 terraform-kong-gateway 管理自托管 HCL；只有当周边 Konnect 代码库已采用 kongctl-declarative 路径时，才使用该工具。
• 如果实时 Konnect 状态很重要，但 kong-konnect MCP 未连接，请尽早说明，并继续检查代码库配置或用户提供的材料。
• 如果阻碍在于通用 Gateway 可达性、发布或路由／服务健康状况，而非 AI 专属层，请尽早转交给 konnect-gateway-triage。

要加载的参考资料

加载第一个匹配的参考资料。默认情况下不要全部加载：

• references/provider-routing.md
  • 当主要问题涉及模型／提供商选择、路由目标、故障回退或提供商特定的请求行为时加载。
• references/guardrails-and-policy-intent.md
  • 当流量在技术层面正常，但策略意图、提示词塑造或治理行为看起来不正确时加载。
• references/observability-and-cost-signals.md
  • 当问题涉及 Token、延迟、AI 专属分析或运维可见性，而非请求构造时加载。

检查顺序

1. 选择层级前，先对问题分类

将首个症状归入以下某个分支：

• 提供商路由或模型目标
• AI 流量的服务／路由设置
• AI Proxy 或 AI Proxy Advanced 行为
• 提示词或响应护栏
• 提示词装饰或模板行为
• 语义缓存行为
• LLM 用量、延迟或 Token 可见性
• 仅碰巧影响 AI 流量的通用 Gateway 可达性或配置发布问题

不要把所有 AI Gateway 问题都归结为“插件坏了”。

如果问题本质上是常规路由或服务健康状况，请在诊断 AI 控制项之前转交给 konnect-gateway-triage。

2. 验证 AI 流量路径的基线

首先验证：

• AI 请求到达预期的服务和路由
• AI 代理层已按运维人员预期的方式附加
• 提供商身份验证要求明确
• 预期的提供商和模型目标已确认，而非仅凭假设

只有完成上述验证后，才能分析提示词防护或模板等更高层级的 AI 策略。

如果请求未能顺利到达提供商路径，请停留在护栏层以下，并继续考虑提供商路由或 Gateway 健康状况分支。

3. 先解决提供商或模型目标问题，再处理策略

对于受治理的 LLM 流量，按以下顺序检查各层：

• 基础 AI 代理
• 路由及模型／提供商选择
• 身份验证与访问控制
• 提示词装饰或模板注入
• 提示词／响应护栏
• 语义缓存或其他加速层

这样可以避免在路由或提供商层出错时，却追查护栏症状。

当运维人员询问流量被路由到了哪里、是否发生了故障回退，或响应的是不是错误的模型／提供商时，请加载 references/provider-routing.md。

4. 只有在确认代理正常后，才评估策略层

确认基线代理和目标选择可信后，再区分以下问题：

• 提示词装饰或模板注入错误
• 提示词或响应护栏不匹配
• 语义缓存行为
• Kong 侧无法控制的提供商/模型行为

当操作员需要区分技术上有效的流量与符合策略的流量时，加载 references/guardrails-and-policy-intent.md。

5. 使用 LLM 分析功能排查 AI 专属运行时问题

如果问题涉及用量、令牌、延迟或类似成本的行为，优先使用 LLM 分析功能，而非通用 API 分析功能。

使用 AI 专属可观测性功能回答以下问题：

• 请求是否到达 AI Gateway
• 令牌用量是否符合预期
• 延迟或错误率是否集中在特定路由、提供商或模型上

如果实际问题是运行时可见性、令牌行为或延迟集中，加载 references/observability-and-cost-signals.md。

6. 区分 Kong 侧治理与提供商行为

如果请求已到达提供商，但行为仍不正确，请区分：

• Kong 侧路由和策略意图
• 提供商侧模型行为
• 提示词构建的影响
• 授权或密钥管理方面的假设

不要声称每个不良模型响应都是 Gateway 漏洞。

7. 将 AI 故障归入最具体的故障域

将问题分类为：

• 路由或服务配置问题
• AI 代理/提供商配置问题
• 身份验证或密钥管理问题
• 提示词装饰/模板问题
• 护栏策略问题
• 语义缓存或加速问题
• 分析/可见性问题，而非流量故障
• 应由本技能处理范围之外的通用网关运行状况问题

Konnect 专属注意事项

• AI Gateway 首先仍是一个 Gateway 层：路由、服务和插件的配置位置仍然重要。
• 提示词和响应护栏是在正常工作的 AI 代理路径上扩展的功能，不能取代该路径。
• 应将 LLM 分析功能视为与通用 API 分析不同的运行时层。
• 技术上成功的提供商响应仍可能违背策略意图。
• 提供商侧的拒绝、配额限制或模型行为可能会通过正常工作的 AI Gateway 路径传递；将其称为 Gateway 缺陷前，请先确认 Kong 侧的意图。
• 快速入门有助于验证基础能力，但不能替代持久的 AI Gateway 运营模式。

验证清单

回答前，请确认你能够说明：

• 哪个 AI Gateway 层发生故障
• 在启用更高层级的 AI 控制之前，基线代理是否正常工作
• 请求预期访问哪个服务/路由以及哪个提供商/模型目标
• 回退或选择其他提供商是有意为之还是意外发生
• 问题属于 Kong 侧路由、身份验证、护栏、提示词塑形、缓存、提供商行为还是分析功能
• LLM 分析功能或其他可观测性层是否是下一步的正确选择
• 应由哪个声明式工具技能负责实施相应变更

移交

• 如果主要问题是数据集可见性，而非 AI Gateway 本身的行为，请使用 konnect-observability-triage。
• 如果真正的阻碍是通用 Gateway 连接或配置发布，而非 AI 专属层，请使用 konnect-gateway-triage。
• 如果操作员希望将 AI Gateway 变更编码为配置或应用配置，请使用 deck-gateway、terraform-konnect、terraform-kong-gateway 或 kongctl-declarative。