1. 托管部署的公开边界

同一家厂商可能同时提供 API、开权重、云 marketplace 和企业私有化方案，它们公开的信息并不相同。下表只写官方文档中终端用户能验证的契约；开权重 runtime 另见自部署页。

提供方公开可观察控制面可以得出的工程结论不能得出的结论
OpenAIResponses/Chat、Batch、prompt cache、gpt-oss 自部署文档。请求级缓存、异步批处理和模型 lifecycle 要纳入客户端。GPT 托管模型的 GPU、KV 物理放置、网络图。
GoogleGemini Batch / Context Cache、Vertex quota / Provisioned Throughput、Gemma self-host。容量承诺有 project-region-model-version 控制面作用域。PT 作用域不等于某个 GPU 集群拓扑。
xAIprompt cache、x-grok-conv-id / prompt_cache_key、rate limits、Agent Tools。用会话身份与稳定前缀提高 cache 机会，处理 429。闭源 Grok 的 self-host 或全区域能力。
DeepSeekOpenAI/Anthropic compatible endpoint、模型切换、rate limit、user_id 逻辑隔离。工具、1M/API context、缓存/调度的接口语义可测试。user_id 能证明物理 KV 在何处。
Z.ai / Kimi / MiniMax / Hunyuan各家 API、工具、模型 ID、streaming / 兼容层和公开配额。建立 provider adapter、模型版本 pin 和重试策略。产品集成页面所对应的内部集群。

2. 把托管模型看成状态机，而不是一个无状态 HTTP 函数

client request → model/version selection → quota / queue admission → prefix/cache identity → generation / tool-call rounds → stream / completion / usage record → retry, fallback, audit 可观察的是契约和结果；内部 worker、KV page、NIC 与机架通常不可观察。

这些公开状态已经足够约束客户端：固定版本，保持缓存前缀稳定，为流式中断准备幂等恢复，给工具 schema 做版本管理，对限流和 transient failure 退避，并在模型退役前跑回归。API benchmark 测到的是整项服务，不能当成某厂 GPU 吞吐的直接证据。

3. Batch、prompt cache 和 prefix routing：能省什么，不能保证什么

OpenAI 和 Gemini 公开了异步 Batch 与 cache，xAI、DeepSeek、MiniMax 也各有缓存或上下文管理接口。这些能力要分别处理：

  • Batch：把非交互任务移出低延迟通道，通常使用单独限额和完成窗口。它会改变排队与成本，不保证单条任务立即完成。
  • Prompt/prefix cache：稳定前缀可能复用计算状态。是否命中取决于模型、region、TTL、请求形状、模板和平台策略；不少平台明确只作 best effort。
  • sticky routing:prompt_cache_key 或会话 ID 可以提高相邻请求落到可复用状态的机会。这是路由提示，不是数据库事务，也不承诺数据的物理位置。
  • 上下文压缩：压缩可能改变后续 token 和可解释性，评测时要检查任务语义，不能只看费用。

容量计划要保留 cache-miss 基线。缓存驱逐或请求发生微小变化时，p99 会回到这条基线。

4. 多供应商客户端应统一什么，不应伪统一什么

内部可以统一一层 provider adapter。输入侧规范 messages、media、tool schema、effort 和 stream policy；输出侧规范 finish reason、usage、tool call、request id、retryability 与 cache diagnostics。适配器只统一业务需要的字段，不能假定各平台的 reasoning、cache、batch 或多模态语义相同。

统一字段为什么不能强行统一的字段
model revision / date防止供应商切换模型后静默回归模型内部 context/attention 实现
idempotency / request trace支持流式断开和 retry 审计供应商 worker identity
tool schema + validation避免 parser 差异进入业务层隐藏 CoT / reasoning token 政策
token and cost accounting比较实际请求，而非宣传价硬件运行成本或电耗
rate-limit telemetry做 backoff / circuit breaker队列内部优先级算法

5. 区域、数据驻留与预留容量：措辞必须精确

OpenAI 的数据控制文档明确：regional storage 不等于 regional processing。因此合规设计应引用官方适用模型/特性表，不能因为数据驻留承诺而推断每个 token 都在同一物理区域推理。Google Vertex Provisioned Throughput 的公开作用域是 project-region-model-version：它说明容量预留在控制面怎样绑定，不是 GPU rack topology。xAI 等平台的区域可用性也应只按具体公告的时间和产品写，不能外推出整个公司服务。

容量设计应至少有三层：交互请求用 SLO + fallback；可延迟请求用 Batch；关键业务用可验证的预留/配额和跨 provider 降级。没有公开 SLA 的 provider，最稳妥的做法是压测当前 API 并预留退路，而不是用模型排行榜估算可用性。

6. 托管 API 的部署验收清单

  1. 为每个模型保存产品名称、version/date、API endpoint、区域、最大 context、费用和变更公告。
  2. 测试 cache hit 和 miss 两类请求，分别记录 TTFT、TPOT、cost、使用量和 p95/p99。
  3. 针对 429、5xx、stream drop、tool parse error、content filter 和 model migration 写可重放测试。
  4. Batch 验证完成窗口、幂等性、partial failure 与大批量回填。
  5. 多供应商 fallback 要测 prompt/template 差异、tool schema 差异和安全规则差异，不能只改 model id。
  6. 合规/区域要求引用适用文档和日期，且在文档没有披露时写‘未知’。

7. 缓存友好的路由与多供应商 fallback

稳定前缀、会话 key、model pin 与 region 选择共同影响 cache 机会；在有公开 sticky-routing hint 时可使用它，但应用仍要接受 cache miss。fallback 不应在一个 stream 已生成半截时盲切模型：应以请求类型、工具副作用、结构化输出和可接受语义差异为条件，必要时返回可重试状态而非悄悄合并两家结果。

8. 工具、数据和审计：API adapter 的最小安全边界

每次调用应记录 provider request id、model/version、权限、token/cost、tool schema version 和必要的输入输出摘要。工具执行要在模型生成之后单独授权、校验和隔离；模型返回的 JSON 只是候选参数，不是可信指令。对数据驻留、日志和 cache 的承诺要链接到具体产品文档及日期，而不是使用一个模糊的“全球 API”标签。

9. 一手来源

一手来源使用范围
OpenAI Batch / Prompt caching异步容量与 cache/routing 公开语义。
Gemini Batch / Gemini caching / Vertex PTGoogle API、cache、容量控制面。
xAI cache / rate limitsxAI 会话 cache 与限流。
DeepSeek rate limits / updatesDeepSeek API 模型/隔离与版本迁移。
Z.ai API、MiniMax API、Hunyuan API中国模型厂的公开接口层。