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.）。请参阅自定义流程变量。
• **工具：**使用终端和文件工具。通过 --help 检查 apigeecli 命令；切勿虚构标志或 API 调用。

功能	参考文档	输出
Vertex AI 聊天目标	Vertex 目标	兼容 OpenAI 的 Gemini 端点、原生 Google 身份验证、运维人员 API/IAM 设置
路由	路由	别名、端点和身份验证映射；捆绑包；路由检查
累积令牌	LLMTokenQuota	基于产品的限额、计数器范围、配对策略、计数器测试
API 密钥和产品配置	API 产品设置	由运维人员执行的产品、开发者、应用和属性设置步骤，并进行读取验证
支出预算	成本预算	API 产品上的价格和预算、成本计算、配对成本计数器、测试
提示词突发流量	PromptTokenLimit	速率、可信身份、完整提示词来源、失败测试
提示词和响应保护	Model Armor	失败约定、模板和身份就绪情况、安全测试
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 target。商定别名和未知模型的错误处理方式；建议明确拒绝，绝不隐式回退。保留现有标识符。
2. 审批并建立基线。 确认项目、所有权、变更、暴露范围和调用限制。分别取得对读取、后端调用、设置与 IAM、部署、持续成本和试用的审批。使用小型合成请求探测已批准的后端，并记录状态、解析后的模型和用量。与用户一起解决身份验证失败；绝不盲目重试。
3. 逐步构建。
   • 保留正常运行的代理和运维人员的变更。编写实际文件，并优先使用原生策略。
   • 在调用后端前验证模型允许列表并转换别名。将调用方身份验证与上游身份验证分开。
   • 对于固定目标 URL，在 TargetEndpoint 请求流中设置布尔值 target.copy.pathsuffix=false。
   • 在每条路由上，先移除调用方凭据标头，再插入后端凭据。
   • 对任何未附带参考资料而编写的文件标记为未验证，并提出询问。
   • 检查策略、附加顺序、XML、引用和 ZIP 结构。
4. 按审批要求导入和部署。 单独取得对运行时凭据的审批。在提供 ZIP 前，提供适用的 Vertex target、Model Armor 和 语义缓存 交接说明。绝不亲自执行人工操作说明。仅部署已批准的修订版本。对于渐进式更新，在运维交接中加入当前部署检查和明确的修订版本替换；对于已批准的替换，使用 override=true，而非要求单独取消部署。每次写入后回读配置并检查就绪状态。
5. 验证并交接。
   • 对于每个 API 密钥代理，都要提供针对生成代理的 API 产品设置说明。对于令牌配额，列出产品的 LLM 操作模型名称，并说明这些是后端模型 ID，而非调用方别名。
   • 对于由运维人员运行的实验，在部署说明后打印可复制的 curl 测试命令，并使用已配置的主机名、基础路径和别名。包含安全的密钥输入方式，确保参数或日志中不含机密；使用小型合成请求、输出令牌限制、预期状态/正文检查，以及在已批准的成本限制内明确的最大调用次数。绝不使用无界循环或自动重试。由运维人员运行这些命令；不要亲自执行。
   • 覆盖每个实验的成功和拒绝场景。说明如何通过掩码诊断信息归因到相应策略，并确定是否调用了后端；仅凭 HTTP 状态不足以作出判断。达到调用次数上限后停止，并将未能重现的场景报告为未验证。
   • 仅在获得单独授权后运行验收用例；否则提供由运维人员运行的命令。分别报告结构检查、直接后端结果和已部署代理结果。
   • 报告已构建和测试的内容、保留的资源及成本，以及存在的缺口。
   • 未经批准，不得清理或发布。

验证边界

• 读取错误响应体，而不只是状态码。 错误格式化策略可以正常运行，但 Apigee 的原生故障仍可能出现在传输内容中，从而泄露调用方身份或策略名称。请参阅错误脱敏。
• 已知限制（能力状态）：未修改的直通测试的是上游路由，而非 Apigee 请求映射；非流式结果无法说明流式处理情况；仅有路由并不能构成完整的网关。