Wiki Notes

Appearance

平台工程 ​

版本：v1.1

最后更新：2026-07-08

这一组内容聚焦的是：怎么把模型能力真正落进系统，而不是只停留在“接口能调通”的 Demo 阶段。

如果说 LLM专题 更偏能力层、AI Agents专题 更偏执行与编排层，那么 平台工程 更偏系统化落地层。它关心的是契约、编排、异步任务、观测、成本、回放、发布和团队协作，目标是把“偶尔能跑通”变成“能长期上线、能稳定维护、能持续演进”。

1. 这组内容主要解决什么问题 ​

很多团队在做 AI 平台化时，最容易踩进这几类误区：

  • 只做统一 SDK，却没有把输出 schema、工具参数、错误语义和超时策略一起标准化。
  • 只看单次调用成功率，却没有把 tracing、回放、成本归因和告警链路补齐。
  • 只想着接更多模型，却没有把路由、回退、灰度和供应商差异治理清楚。
  • 只沉淀 Prompt 文本，却没有把 Prompt、配置、评测和发布做成可维护资产。
  • 只解决“怎么调用”，却没有解决“怎么上线、怎么定位、怎么回滚、怎么协作”。

按 OpenAI 当前的 Production best practices、Structured outputs、Cost optimization、Batch、Background mode 和 Integrations and observability 这些官方资料来看，平台层至少要同时回答六个问题：

  1. 输入输出契约是否足够稳定，能不能被别的系统安全消费。
  2. 长任务、离线任务和异步任务是否有清晰的执行模式。
  3. 每次请求是否可观测、可追踪、可回放、可审计。
  4. 模型、工具和策略选择是否可治理、可降级、可控成本。
  5. Prompt、策略、配置和模型版本是否能作为发布资产演进。
  6. 故障、异常样例和回归结果是否能回流到平台治理闭环。

2. 推荐阅读顺序 ​

2.1 如果你想先搭一套最小可上线骨架 ​

  1. 项目模板与脚手架专题
  2. 结构化输出与函数调用专题
  3. 企业AI交付清单专题
  4. 可观测性与tracing专题

2.2 如果你现在最头疼成本、延迟和模型选择 ​

  1. 推理加速与成本优化专题
  2. 模型路由与策略引擎专题
  3. 多模型回退策略专题
  4. 多模型协同编排专题
  5. 模型能力画像专题

2.3 如果你想把 Prompt 和运行策略做成可维护资产 ​

  1. Prompt工程案例专题
  2. Prompt版本治理专题
  3. MLOps与LLMOps专题
  4. 企业AI交付清单专题

2.4 如果你已经进入多团队协作和平台运营阶段 ​

  1. 可观测性与tracing专题
  2. 模型路由与策略引擎专题
  3. 多模型回退策略专题
  4. 企业AI交付清单专题

3. 这些专题之间是什么关系 ​

你可以把这一组按五层来理解。

3.1 骨架层 ​

这一层解决的是“平台最小骨架要先搭什么”，包括目录约定、环境变量、配置分层、发布入口、运行模式和团队职责边界。

3.2 契约层 ​

这一层解决的是“系统怎么稳定地和模型交互”。在真实工程里，Prompt、输出 schema、工具参数、错误码和重试边界通常需要一起治理，而不是分别散落在不同服务里。

3.3 调度层 ​

这一层回答的是：什么请求走什么模型，什么时候回退，什么时候并发，什么时候切后台处理，什么时候直接拒绝，而不是让这些决策只停留在人脑经验里。

3.4 运行层 ​

这一层更关心线上真实问题，例如 trace 怎么打、成本怎么归因、长任务怎么恢复、缓存怎么用、批量和后台任务怎么拆，以及上线后如何快速定位问题。

3.5 数据与评测协同层 ​

平台不是只做运行时调用。很多关键能力，例如路由策略、回退阈值、质量门禁、能力画像和回归样例，最终都要回到数据和评测资产上。

4. 平台工程里最值得先建立的几个共识 ​

4.1 平台不是统一调用层，而是统一治理层 ​

真正的平台价值，不是包一个统一的 callModel()，而是统一：

  • 调用契约
  • 输出 schema
  • trace 字段
  • 成本字段
  • 风险与审批边界
  • 回放和评测入口

如果只有统一 SDK，没有统一治理口径，那么平台只是“换了个地方调 API”。

4.2 结构化输出通常要早于“更聪明的 Prompt” ​

OpenAI 的 Structured outputs 官方文档当前明确强调对象 schema 与字段约束。对平台工程来说，这意味着很多问题不该先靠“再补一段提示词”解决，而应该先通过输出结构和字段边界固定住。

只要输出结构不稳定，后面的：

  • 自动化编排
  • 工具调用
  • 评测打分
  • 人工审核
  • 回放追责

都会变得脆弱。

4.3 同步、后台和批处理应该是三种不同运行模型 ​

OpenAI 目前把 Background mode 和 Batch 单独作为能力入口，本身就说明平台运行模式不能只靠一个同步接口硬撑。

更实用的划分通常是：

  • 同步模式：适合短请求、强交互、用户等待中的任务。
  • 后台模式：适合长任务、异步工作流、需要恢复或轮询状态的任务。
  • 批处理模式：适合离线回放、批量抽取、低优先级任务和大规模成本优化。

很多平台的成本问题，本质不是模型太贵，而是把不该同步做的任务强行同步化了。

4.4 trace 不是排障附件，而是平台主数据 ​

OpenTelemetry 的 traces 和 context propagation 文档，本质上给了我们跨服务追踪一次请求因果链的通用模型。对 AI 平台来说，trace 不只是“排查时顺手看一眼”的日志，而应该是：

  • 请求级质量复盘入口
  • 成本归因入口
  • 故障回放入口
  • 人工纠偏入口
  • 安全审计入口

如果上线后拿不到完整调用链，再好的 Prompt 和模型也很难稳定运营。

4.5 成本优化最先该做的是减少无效调用 ​

OpenAI 的 Cost optimization、Prompt caching、Batch 和 Background mode 指向同一个现实：很多时候最有效的优化不是单纯换便宜模型，而是减少不必要的请求、稳定可缓存前缀、把可离线任务批量化、把长任务异步化。

所以平台优化优先级通常是：

  1. 减少重复调用
  2. 缩短上下文和噪声
  3. 引入缓存、批量和后台处理
  4. 再去做复杂的模型价格优化

4.6 Prompt、策略和配置应该进入发布资产 ​

很多团队把 Prompt 和策略散落在代码、数据库、表格和 IM 讨论里，导致：

  • 回放时不知道当时用了哪个版本
  • 故障后无法定位是哪次修改导致回归
  • 不同服务对同一任务使用了不同约束

平台工程里，Prompt、schema、工具定义、路由阈值、超时策略和回退规则最好都进入统一版本治理与发布流程。

5. 不同团队阶段更适合先看什么 ​

5.1 刚从 Demo 走向内部试点 ​

优先看：

  1. 项目模板与脚手架专题
  2. 结构化输出与函数调用专题
  3. 企业AI交付清单专题

这个阶段的目标不是“接很多模型”，而是先把最小上线骨架、配置边界和输出契约搭稳。

5.2 已经有多个业务开始共用平台 ​

优先看：

  1. 模型路由与策略引擎专题
  2. 多模型回退策略专题
  3. 可观测性与tracing专题

这个阶段的重点是统一路由口径、故障回退方式和观测口径。

5.3 已经开始遇到成本和质量拉扯 ​

优先看：

  1. 推理加速与成本优化专题
  2. 模型能力画像专题
  3. 数据集构建与标注专题

重点不只是“便宜”，而是把成本、质量和延迟一起纳入可运营的决策。

6. 平台上线前的最小检查清单 ​

  • 是否定义了统一的输入输出契约和 schema。
  • 是否能区分同步、后台和批处理三种任务模式。
  • 是否有请求级 trace、span、错误码和成本字段。
  • 是否能回放失败请求并定位到 Prompt、模型和工具版本。
  • 是否有模型回退和降级策略，而不是只依赖供应商可用性。
  • 是否有 Prompt、路由、超时和策略配置的版本治理。
  • 是否把高频失败样例纳入回归评测，而不是只在线上手工观察。

7. 当前官方资料最值得先建立的四个平台判断 ​

按 2026-07-08 复核可访问的 OpenAI、OpenTelemetry 与 LangSmith 官方资料，比较值得先建立的平台判断有这些：

7.1 平台真正要统一的不是 SDK，而是控制面对象 ​

很多团队说“做平台”，第一反应是封一个统一 SDK。

但从 OpenAI Production best practices、Structured outputs、Deployment checklist、Prompt caching 这些资料放在一起看，更值得统一的其实是这些控制面对象：

  • prompt / system instruction 版本
  • schema / structured outputs
  • tool definitions
  • routing / fallback / timeout policy
  • prompt_cache_key
  • eval / replay / release bundle

如果这些对象仍然散落在不同服务、脚本和数据库里，那么就算表面上只有一个 callModel()，平台也依然很难：

  • 回放
  • 回滚
  • 复盘
  • 统一治理

7.2 prompt_cache_key 和稳定前缀应该是平台能力，不该交给业务各自摸索 ​

OpenAI 当前 Prompt caching 和 API deployment checklist 都很明确地强调了两件事：

  • cache hit 依赖 exact prefix matches
  • 高流量工作流应稳定使用 prompt_cache_key

这背后的平台含义非常直接：

  • 缓存命中不只是 prompt 写法问题
  • 也是平台请求编排和模板治理问题

更稳妥的做法通常是让平台显式管理：

  • 哪些模板前缀必须冻结
  • 哪些字段允许动态变化
  • 哪些业务请求共用同一个 prompt_cache_key
  • 哪些模型 / 路由组合会把缓存打碎

如果这一层不统一，业务方通常只能靠体感猜“为什么这周突然更贵了”。

7.3 trace 要能跨服务串起来，光有本地日志 ID 不够 ​

OpenTelemetry 官方的 Traces 与 Context propagation 资料反复说明：

  • 分布式 tracing 的关键不是多打一份日志
  • 而是把因果链跨服务传播下去

对 AI 平台来说，这意味着一次请求至少要能串起：

  • 网关
  • 编排层
  • 检索层
  • 模型调用
  • 工具调用
  • 审批 / 人工 review
  • 回调 / 异步恢复

如果只有每个服务自己的 request id，而没有真正的 context propagation，线上最常见的问题就是：

  • 你知道每段都发生了什么
  • 但不知道它们是不是同一条用户请求

7.4 同步、background、batch、flex、priority 应该是不同运行 lane ​

OpenAI 现在把：

  • Background mode
  • Batch
  • Flex processing
  • Priority processing

都拆成独立能力入口，本身就说明平台不该只暴露一种同步运行方式。

更贴近生产的心智通常是：

  • sync：用户正在等待的短请求
  • background：长任务、可恢复任务、异步工作流
  • batch：离线大批量处理，接受 24-hour turnaround time
  • flex：更低优先级、更低成本、允许资源偶发不可用
  • priority：高价值、强时延、需要更稳定响应的流量

这不只是“价格选项”，而是任务语义、SLO、错误恢复和资源策略的差异。

8. 平台工程里最容易漏掉的四个控制对象 ​

8.1 请求契约对象 ​

很多系统只定义“调用哪个模型”，却没有把下面这些对象视为正式契约：

  • 输入 schema
  • 输出 schema
  • 工具参数约束
  • 错误语义
  • 超时语义

8.2 运行模式对象 ​

平台如果不显式区分同步、后台、批处理、低优先级和高优先级任务，后面通常就只能把所有问题都往同步接口上堆。

8.3 trace 关联对象 ​

真正要被统一记录的通常不只是 trace id，还包括：

  • model / prompt / tool 版本
  • route decision
  • cost bucket
  • approval state
  • replay id

没有这些对象，trace 就很难直接变成回放和治理入口。

8.4 发布单元对象 ​

很多团队的“发布”其实只发代码，但真实平台更该冻结的是 release bundle：

  • Prompt
  • schema
  • tool definitions
  • 路由阈值
  • timeout / retry policy
  • eval baseline

9. 推荐搭配阅读 ​

10. 重点官方资料 ​

以下入口在 2026-07-08 检查时可访问，适合和本分类一起对照阅读：