直接 API、Bedrock 与 Vertex AI：共同原理与接入差异

01 / 定义：模型能力与接入平台分开看

直接 API 通常由模型提供方管理访问与计费；云平台路径把模型能力放进该云的账号、身份和区域体系中。相同模型家族在不同平台的可用版本、标识、功能和限制不一定一致。不能因为名称相近就假设请求完全兼容。

Bedrock 与 Google Cloud 的具体入口和 SDK 会随模型代际变化。本文不提供可能失效的固定模型 ID；实际接入时先查当前账号可用资源及对应官方接口，再把选定配置记录下来。

02 / 推导：从现有约束选择入口

选择应由业务与技术条件共同决定。若主要目标是验证一个分类任务，先用最容易获得合规访问的路径；若要进入企业现有系统，则身份、审计与运维整合可能比少写几行代码更重要。费用和数据条款必须按当前合同核对，不能用通用文章替代具体确认。

03 / 应用：完成一张接入检查表再写业务

以已有云账号的只读分类原型为例。整个流程分成访问、单次请求、契约转换和业务验证四步，不先把真实业务数据大量送入服务。

1. 记录目标。需要文本分类、允许的延迟、数据敏感度和预期调用规模。确认使用该服务的授权与预算范围。
2. 确认访问条件。在选定平台核对账号或项目、区域或位置、当前可用模型、凭据方式、配额和必要权限。只授予原型所需权限。
3. 跑最小请求。使用平台当前官方示例与无敏感文本。记录实际模型标识、接口路径、响应形态和请求关联号；示例成功只证明访问链路。
4. 建立适配层。把业务输入转换成该平台请求，把实际响应转换为统一业务结果，同时保留错误和消耗信息。不要强行抹平不支持的功能。
5. 运行同一评估集。用相同脱敏样本比较输出、失败、成本和端到端延迟。模型版本不同应明确记录，不能称为同模型纯平台比较。
6. 验证失败。错误权限、错误模型标识、超时和配额限制分别如何反馈？应用不能把所有错误都显示为“AI 暂时不知道”。

接入记录（填入实际结果）
平台与账号/项目：
区域或位置：
实际模型标识与接口版本：
凭据来源：仅记录方式，不记录密钥值
已验证能力：文本 / 工具 / 结构化输出等
超时、重试与调用上限：
请求关联号与日志位置：
尚未验证的环境和功能：

这张记录让另一个维护者能够复现接入条件。若只能在某个人电脑上运行，却不知道身份从哪里来，接入尚未具备可维护性。

04 / 验收：迁移时重新验证哪些行为

迁移平台不仅是替换 base URL。认证、模型名称、请求结构、内容块、错误码、流式响应和工具能力都可能变化。适配层可以减少业务代码改动，但不能消除语义差异。

• 正常路径：同一业务输入得到符合契约的结果。
• 功能差异：不支持的能力明确拒绝或使用经过验证的替代方案。
• 失败路径：保留可诊断原因；有限重试不造成重复副作用。
• 运行路径：日志、费用、配额和告警能被现有维护流程看到。

自动故障切换到另一平台也属于设计决定。敏感数据是否允许进入备用平台、输出差异是否影响业务、工具是否可用，都要事先确定。不能因为主平台超时就默认把数据发往任意备用服务。

05 / 迁移：不要提前建立过度抽象

如果只有一个稳定入口，先把业务契约与供应商调用分开，未必需要完整多云调度系统。只有确实需要迁移、比较或容灾时，再扩大适配层。抽象也有维护成本，尤其是平台能力并不完全相同时。

接入之后仍需完成应用请求链路和评估。平台选择解决运行条件，业务可靠性仍由完整系统证明。