把 AI 接进现有代码库:最小可落地改造的七个步骤

📅 2026/11/22 ✍️ 小文 📖 约 1 分钟

不是从零建 AI 应用,而是在一个成熟项目里加入 AI 能力——这是 2026 年绝大多数工程师的真实任务,也是文档最少的场景。本文给出从可行性判断到灰度上线的七步路线,含每一层的接口设计与回滚方案。

这类任务为什么比从零开始更难

从零建 AI 应用,你可以决定一切:技术栈、数据格式、部署方式。往成熟系统里加 AI,你什么都不决定——已有的事务边界、已有的权限模型、已有的性能预算、已有的监控体系,都要兼容。

而且还有一个隐藏难度:成熟系统的正确性已经被验证过,加入一个概率性组件后,原本”确定正确”的部分变成了”大概率正确”,这种信任的损失是工程上最难处理的。

所以这件事要按步骤做,每一步都能停下来。

第一步:先证明”不用 AI 做不到”

这一条听起来像废话,但它能省掉 30% 的项目。

写下来三件事:

  1. 现有规则/算法方案的最优效果能达到多少?
  2. 差距在哪里?(是覆盖率?是长尾?是自然语言输入?)
  3. AI 方案能补上多少这个差距?

如果规则方案能到 85%,AI 方案能到 92%,那么要问:这 7 个百分点值不值得引入一个概率组件、一套新的成本模型、一个新的运维对象?

通常答案是”值得”,但前提是你能说清这 7 个百分点值多少钱。说不清,就先别做。

第二步:把 AI 能力定义成一个纯函数

这是整个改造里最重要的架构决策。

反例:在业务代码里直接调用模型 SDK,散落在十几个 service 里。三个月后你想换模型、加缓存、加评估,会发现无处下手。

正例:定义单一入口。

def infer(task: str, payload: dict, *, trace_id: str) -> Result:
    """所有 AI 能力的唯一入口。
    - task: 能力标识,如 "summarize_ticket"
    - payload: 结构化输入,不含业务对象
    - 返回: 结构化输出 + 元数据(模型、耗时、成本、置信度)
    """

这个函数内部负责:拼提示、选模型、调 API、校验 schema、重试、记录 trace、计费。业务代码只关心输入输出。

必须做到的边界:payload 里不允许出现数据库对象或 ORM 实体。只传扁平数据。否则半年后你会发现 AI 模块和业务模型纠缠在一起,无法独立测试。

第三步:结构化输出 + 严格校验

不要返回自由文本然后让业务代码解析。

class TicketSummary(BaseModel):
    category: Literal["billing", "bug", "feature", "other"]
    severity: Literal["p0","p1","p2","p3"]
    summary: str = Field(max_length=200)
    needs_human: bool

拿到响应后必须校验,校验失败的处理策略是三段式:

  1. 第一次失败:把错误信息回传给模型要求修正(成功率约 60%)
  2. 第二次失败:降级模板/规则方案
  3. 仍然失败:抛业务异常,走原有人工流程

绝不允许”解析失败就返回 None 让上层处理”——上层永远不会正确处理 None。

第四步:设计降级开关,粒度为”能力”

上线前必须能在一分钟内关掉 AI。

features.ai.ticket_summary = on
features.ai.ticket_summary.rollout = 10%   # 灰度比例
features.ai.ticket_summary.fallback = rule

三个层次缺一不可:总开关、灰度比例、降级目标。

经验:降级路径必须每个月真的跑一次,否则它一定已经坏了。把它加进每月的演练清单,和其他容灾演练放在一起。

第五步:把成本放进已有的计量体系

不要把 AI 成本当成一个独立的、每月看一次的账单。它应该和 CPU、存储一样,出现在你的成本看板里,细化到”每个业务功能”。

最简做法:在 infer() 返回的元数据里带 tokens_in、tokens_out、cost_usd,业务层把它记到自己的 metric 上。

ai_cost_usd{feature="ticket_summary", model="fast"} 0.00042

有了这个,你才能在某个功能被滥用时立刻发现——这在 AI 系统里是高频事故,因为调用成本对使用者完全不可见。

第六步:搭最小评估集,挂在 CI 里

不要等到第一版上线后再做评估。上线前先攒 40~80 条:

  • 20 条最常见的正常输入
  • 10 条边界(空、超长、多语言、格式异常)
  • 10 条对抗/越界(超出能力范围的请求)
  • 10 条历史 bug 复现

用两条判据:是否返回合法结构(自动)+ 关键字段是否正确(人工标注的关键字段,可自动比对)。

在 CI 里跑:每次 prompt 或模型变更必须通过,通过率低于基线的 5% 就阻止合并。这是对抗”改了一处坏了另一处”的唯一有效手段。

第七步:灰度、观测、复盘

灰度按用户维度(不是按请求维度)分批:1% → 5% → 20% → 50% → 100%,每档至少观察 48 小时。

观察三个东西:

  1. 业务指标:AI 功能的实际采纳率(用户是否点了”采用 AI 建议”)
  2. 失败分布:降级率、校验失败率、超时率
  3. 下游影响:AI 功能是否让某个旧接口的 QPS 或错误率变化

第三项最容易漏。AI 生成的摘要变长了,会不会撑爆下游的数据库字段?AI 触发的操作变多了,会不会撞上某个老系统的限流?这些在下游监控里才看得见。

常见失败模式清单

  • AI 模块直接引用了业务实体,无法测试
  • 输出没校验,异常在深层业务逻辑里爆炸
  • 没有降级路径,模型 API 抖动等于业务全挂
  • 成本不可见,某天发现账单是预期的 20 倍
  • 评估集在上线后就不更新,三个月后与实际脱节
  • 灰度过快,出问题时无法定位是哪个改动

这六条里踩中任何一条,项目都会在 3~6 个月内进入”AI 功能没人敢动”的状态。改造的目标不是一次做对,而是让这个功能以后还能被安全地改。

📤 分享到