API产品化入门

3.1 为什么直接调模型 API 不够#

直接调用模型 API 的方式很快，适合验证想法。但当 AI 功能进入多个业务流程，就会暴露结构性问题。

例如客服、商品文案、合同摘要、需求抽取都要用模型。如果每个业务团队自己拼 Prompt、自己选模型、自己处理错误、自己记日志，就会形成一堆不可治理的小烟囱。

典型问题：

所以 AI API 产品化的第一条原则是：

业务系统不要直接散乱调用模型供应商 API，而要通过统一 AI 编排层调用。

3.2 三层架构：业务系统、AI 编排层、模型 API#

一个基础架构可以这样理解：

1
业务系统
2
  -> AI 编排层
3
      -> Prompt 模板管理
4
      -> 输入校验
5
      -> 权限和风控
6
      -> 模型路由
7
      -> RAG 检索
8
      -> 调用模型 API
9
      -> 输出校验
10
      -> 日志和指标
11
  -> 模型供应商 API / 私有模型

三层职责不同。

产品经理设计 AI 功能时，要明确这三层边界。很多线上事故来自边界混乱：模型在做规则系统的事，业务系统在硬编码 Prompt，AI 层没有日志，出错后没人知道该修哪里。

3.3 AI 编排层的核心模块#

一个最小可用的 AI 编排层，至少包含 10 个模块。

这不是一开始都要做成复杂平台，但 PRD 中必须有最小闭环。尤其是日志、错误码和成本统计，很多团队上线后才补，代价很高。

3.4 鉴权：谁能调，能调什么#

鉴权回答两个问题：

1
谁在调用？
2
他有权调用哪个 AI 能力？

企业内部常见调用方包括：

• 客服系统。

• 商品运营系统。

• OA/IM 助手。

• 数据分析平台。

• 合同管理系统。

• 需求管理系统。

不同调用方权限不同。客服系统可以调用客服回复能力，但不应该调用合同摘要能力；普通员工可以调用制度问答，但不能读取高管薪酬制度；运营可以生成商品文案，但不能自动发布高风险内容。

鉴权要记录：

• app_id。

• user_id。

• tenant_id。

• role。

• permission_scope。

• request_id。

这些字段不仅用于权限，也用于日志、计费和审计。

3.5 限流：防止成本和系统被打穿#

AI 调用比普通接口更贵，也更容易受模型供应商限流影响。限流是必须项。

限流维度包括：

• 单用户每分钟调用次数。

• 单应用每日调用量。

• 单租户预算上限。

• 单接口并发数。

• 单请求最大输入 Token。

• 单请求最大输出 Token。

例如：

1
商品文案生成：每个商品最多生成 3 次
2
客服回复草稿：单会话每分钟最多 5 次
3
合同摘要：单文档最大 50 页，超出走异步任务
4
内部问答：普通员工每日 100 次，管理员可配置额度

限流不是为了限制用户，而是为了保护成本、延迟和服务稳定性。

3.6 日志：没有日志就没有复盘#

AI 系统的日志比传统接口更重要。因为 AI 出错时，原因可能来自 Prompt、输入、检索、模型、采样参数、业务数据、权限或后处理。

基础日志字段：

日志要平衡可复盘和隐私。敏感字段应脱敏，必要时只记录片段 ID，不直接存储全文。

3.7 错误码：让失败可处理#

模型调用失败不能只返回“生成失败”。业务系统需要知道失败类型，才能决定重试、降级、转人工还是提示用户补充信息。

常见错误码：

错误码是 API 产品化的重要部分。没有错误码，前端只能显示笼统失败，运营和研发也无法统计问题。

3.8 重试：不是失败就无限重跑#

大模型调用可能因为超时、限流、网络波动、输出格式错误而失败。重试有必要，但要有策略。

重试规则：

• 模型超时：可重试 1-2 次。

• 限流：应退避重试或排队。

• 输出格式错误：可用格式修复 Prompt 重试。

• 输入缺失：不能重试，应提示补充。

• 高风险拦截：不能重试，应转人工或拒答。

• 供应商错误：可切换备用模型。

错误的重试会放大成本。例如输出格式错误无限重跑，会让 Token 成本迅速上升。产品经理要在 PRD 里写明重试条件和最大次数。

3.9 计费和成本归因#

内部能力也要计量。否则 AI 成本会变成无法归因的公共开支。

计费维度可以包括：

• 调用次数。

• 输入 Token。

• 输出 Token。

• 模型类型。

• RAG 检索次数。

• 重排次数。

• 多模态处理次数。

• 人工复核成本。

即使不对内部团队收费，也要做成本看板：

1
按业务线看调用量
2
按功能看成本
3
按用户或租户看异常用量
4
按模型看平均成本
5
按错误类型看浪费成本

这会直接影响商业化和预算管理。

3.10 同步接口、异步任务与流式输出#

不同 AI 功能适合不同交互方式。

例如：

• 客服回复草稿：同步或流式。

• 合同摘要：异步任务更稳。

• 商品批量文案：异步批处理。

• 企业知识问答：流式输出 + 引用。

产品经理要根据用户等待场景设计接口形态，而不是所有功能都用同步接口。

3.11 API 产品化的 PRD 要点#

一个 AI API PRD 至少要写：

1. API 名称和适用场景。

2. 调用方和权限。

3. 输入字段和字段限制。

4. 输出字段和格式。

5. Prompt 版本和模型策略。

6. 是否需要 RAG 或业务系统。

7. 错误码和异常处理。

8. 限流和预算。

9. 日志和审计。

10. 指标和验收标准。

11. 灰度策略和回滚条件。

如果只是写“调用大模型返回结果”，就不是可上线 PRD。

业务背景#

一家中型企业多个团队都想接入 AI：客服要智能回复，商品团队要文案生成，法务要合同摘要，HR 要制度问答，产品团队要访谈需求抽取。

如果每个团队自己接模型，会造成重复建设、成本失控和安全风险。企业决定建设内部 AI 能力中台。

相关角色#

• 平台产品经理：定义 AI 能力中台范围和接口。

• 业务产品经理：提出具体业务功能。

• AI 工程师：实现模型调用、路由、Prompt 管理。

• 后端研发：接入业务系统和权限。

• 安全/合规：定义数据和审计策略。

• 财务/采购：关注成本、供应商和预算。

• 运营团队：维护 Prompt、知识库和评估集。

原始流程#

1
各业务团队各自选模型
2
-> 各自拼 Prompt
3
-> 各自调用供应商 API
4
-> 各自处理失败和日志
5
-> 成本和风险分散

问题：

• 模型采购重复。

• Prompt 难复用。

• 安全策略不统一。

• 日志不可比。

• 供应商切换成本高。

• 业务方不知道调用成本。

AI 改造流程#

1
业务系统
2
-> 统一 AI 网关
3
-> 鉴权和限流
4
-> 能力路由
5
    -> 客服回复
6
    -> 文案生成
7
    -> 合同摘要
8
    -> 制度问答
9
    -> 需求抽取
10
-> Prompt 和模型管理
11
-> 模型供应商 / 私有模型
12
-> 统一日志、成本、评估

数据与系统依赖#

• 企业统一身份和权限系统。

• 业务系统 API。

• 模型供应商 API。

• 私有模型部署环境。

• Prompt 配置库。

• 向量库和知识库。

• 日志平台。

• 成本看板。

• 评估样本集。

方案架构#

1
业务应用
2
  -> AI API Gateway
3
      -> App 鉴权
4
      -> 用户鉴权
5
      -> 限流和预算
6
  -> AI Orchestration
7
      -> Prompt 模板
8
      -> 模型路由
9
      -> RAG 检索
10
      -> 风险控制
11
      -> 输出校验
12
  -> Model Adapter
13
      -> 模型 A
14
      -> 模型 B
15
      -> 私有模型
16
  -> Observability
17
      -> 日志
18
      -> Token 成本
19
      -> 延迟
20
      -> 错误码
21
      -> 反馈

关键指标#

• 接入业务数量。

• 单功能调用成功率。

• 平均响应时间。

• 单次调用成本。

• Prompt 版本回归通过率。

• 错误码分布。

• 高风险拦截率。

• 供应商异常切换成功率。

• 业务团队接入周期。

主要风险#

• 平台过度复杂，业务接入慢。

• 只做网关，不做 Prompt 和评估治理。

• 成本看板缺失，预算不可控。

• 高风险能力没有权限分级。

• 模型供应商切换没有适配层。

• 业务方绕过中台直接接模型。

复盘结论#

AI 能力中台的价值不是把所有模型调用集中起来，而是建立统一的安全、成本、质量和治理能力。最小版本可以先覆盖 2-3 个高频场景，但架构上要保留 Prompt 版本、模型路由和日志评估能力。

业务背景#

电商平台要把 AI 客服回复接入客服工作台。一线客服点击“生成回复”，系统根据用户问题、订单状态和售后政策生成草稿。

原始 Demo#

1
前端传 user_message
2
-> 后端拼 Prompt
3
-> 调模型 API
4
-> 返回 reply

Demo 能用，但上线前缺少：

• 订单和政策输入。

• 高风险识别。

• 错误码。

• 日志。

• 重试。

• 成本统计。

• 人工接管标记。

产品化 API#

接口：POST /ai/customer-service/reply-draft

输入：

1
{
2
  "app_id": "cs_console",
3
  "user_id": "u_123",
4
  "session_id": "s_456",
5
  "user_message": "我的订单还没发货，今天不发我就退款",
6
  "order_status": "paid_not_shipped",
7
  "logistics_status": "none",
8
  "policy_chunks": [
9
    {
10
      "id": "refund_001",
11
      "text": "未发货订单支持用户申请退款，到账时间以支付渠道为准"
12
    }
13
  ]
14
}

输出：

1
{
2
  "request_id": "ai_req_001",
3
  "intent": ["催发货", "退款意向"],
4
  "risk_level": "medium",
5
  "reply": "理解您的着急。目前订单仍未发货，您可以在订单页申请退款，到账时间以支付渠道处理为准。",
6
  "need_human": false,
7
  "references": ["refund_001"],
8
  "model": "model_x",
9
  "prompt_version": "cs_reply_v3"
10
}

错误处理：

数据与系统依赖#

• 客服工作台。

• 订单系统。

• 售后知识库。

• 风险规则。

• 模型 API。

• 日志平台。

• 质检系统。

关键指标#

• 回复草稿生成成功率。

• AI 草稿采用率。

• 人工修改率。

• 错误承诺率。

• 高风险接管率。

• 平均响应时间。

• 单会话 AI 成本。

• 客服满意度。

主要风险#

• 模型承诺退款或赔付。

• 工具查询失败后仍生成确定回复。

• 输出格式不稳定，前端解析失败。

• 重试造成成本放大。

• 客服直接发送未经确认的草稿。

复盘结论#

客服回复 API 的核心不是“生成一段回复”，而是把输入字段、风险边界、引用、错误码、日志和人工接管设计完整。否则 Demo 看起来顺，线上会不可控。

任务：画出“业务系统 -> AI 编排层 -> 模型 API”的调用链路#

请选择一个场景：

1. 客服回复。

2. 商品文案生成。

3. 合同摘要。

4. 企业知识库问答。

5. 用户访谈需求抽取。

画出调用链路，并写清：

• 业务系统输入什么。

• AI 编排层做什么。

• 是否需要 RAG 或业务系统查询。

• 调用哪个模型策略。

• 输出如何返回业务系统。

• 失败时如何处理。

• 如何记录日志和成本。

参考模板：

1
业务系统
2
-> 鉴权
3
-> 输入校验
4
-> Prompt 模板
5
-> RAG/业务数据查询
6
-> 风险控制
7
-> 模型路由
8
-> 模型 API
9
-> 输出校验
10
-> 返回结果
11
-> 日志和指标

验收标准#

合格：

1. 链路至少包含 8 个节点。

2. 写出输入和输出字段。

3. 写出至少 5 个错误码或异常处理。

4. 写出至少 5 个监控指标。

优秀：

1. 能区分同步、异步或流式输出。

2. 能写出限流和成本策略。

3. 能说明哪些判断不应该由模型承担。

理解题#

1. 为什么业务系统不应该直接散乱调用模型 API？ 参考答案：会导致 Prompt 分散、日志缺失、成本不可控、错误处理不统一、安全策略不一致、模型切换困难。

2. AI 编排层的核心职责是什么？ 参考答案：统一管理鉴权、输入校验、Prompt、模型路由、RAG、风控、输出校验、错误处理、日志和成本指标。

3. 为什么 AI API 需要错误码？ 参考答案：业务系统需要根据失败类型决定补充输入、重试、降级、转人工或拒答，不能只返回“生成失败”。

4. 哪些失败不能简单重试？ 参考答案：输入缺失、高风险拦截、权限不足、资料缺失、业务规则不满足等不应简单重试。

5. 为什么 AI 调用必须做成本归因？ 参考答案：模型调用成本高且随用量增长，必须知道哪个业务、功能、用户消耗成本，才能做预算、限流和优化。

应用题#

6. 合同摘要 API 应该用同步还是异步？为什么？ 参考答案：通常适合异步，因为合同长、解析和模型处理耗时，异步可支持排队、重试、进度查询和结果回看。

7. 客服回复 API 至少需要哪些输入？ 参考答案：用户问题、会话 ID、订单状态、物流状态、政策片段、风险标签、调用方和用户身份。缺少关键业务状态时不应让模型硬答。

8.1 API 产品架构草图#

1
业务系统
2
  -> AI API Gateway
3
      -> 鉴权
4
      -> 限流
5
      -> 输入校验
6
  -> AI 编排层
7
      -> Prompt 模板
8
      -> RAG 检索
9
      -> 模型路由
10
      -> 风险控制
11
      -> 输出校验
12
  -> 模型适配层
13
      -> 供应商模型
14
      -> 私有模型
15
      -> 备用模型
16
  -> 日志与指标
17
      -> Token
18
      -> 延迟
19
      -> 错误码
20
      -> 成本
21
      -> 用户反馈

8.2 AI API PRD 模板#

8.3 错误码设计表#