把 AI 接进现有代码库:最小可落地改造的七个步骤
不是从零建 AI 应用,而是在一个成熟项目里加入 AI 能力——这是 2026 年绝大多数工程师的真实任务,也是文档最少的场景。本文给出从可行性判断到灰度上线的七步路线,含每一层的接口设计与回滚方案。
这类任务为什么比从零开始更难
从零建 AI 应用,你可以决定一切:技术栈、数据格式、部署方式。往成熟系统里加 AI,你什么都不决定——已有的事务边界、已有的权限模型、已有的性能预算、已有的监控体系,都要兼容。
而且还有一个隐藏难度:成熟系统的正确性已经被验证过,加入一个概率性组件后,原本”确定正确”的部分变成了”大概率正确”,这种信任的损失是工程上最难处理的。
所以这件事要按步骤做,每一步都能停下来。
第一步:先证明”不用 AI 做不到”
这一条听起来像废话,但它能省掉 30% 的项目。
写下来三件事:
- 现有规则/算法方案的最优效果能达到多少?
- 差距在哪里?(是覆盖率?是长尾?是自然语言输入?)
- 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
拿到响应后必须校验,校验失败的处理策略是三段式:
- 第一次失败:把错误信息回传给模型要求修正(成功率约 60%)
- 第二次失败:降级模板/规则方案
- 仍然失败:抛业务异常,走原有人工流程
绝不允许”解析失败就返回 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 小时。
观察三个东西:
- 业务指标:AI 功能的实际采纳率(用户是否点了”采用 AI 建议”)
- 失败分布:降级率、校验失败率、超时率
- 下游影响:AI 功能是否让某个旧接口的 QPS 或错误率变化
第三项最容易漏。AI 生成的摘要变长了,会不会撑爆下游的数据库字段?AI 触发的操作变多了,会不会撞上某个老系统的限流?这些在下游监控里才看得见。
常见失败模式清单
- AI 模块直接引用了业务实体,无法测试
- 输出没校验,异常在深层业务逻辑里爆炸
- 没有降级路径,模型 API 抖动等于业务全挂
- 成本不可见,某天发现账单是预期的 20 倍
- 评估集在上线后就不更新,三个月后与实际脱节
- 灰度过快,出问题时无法定位是哪个改动
这六条里踩中任何一条,项目都会在 3~6 个月内进入”AI 功能没人敢动”的状态。改造的目标不是一次做对,而是让这个功能以后还能被安全地改。