这两年我陆续带了三四个 AI 软件开发的全链路项目从最开始的用一个模型 API 包一层壳到后来真正把检索、评测、监控、成本全部串起来最大的感受是AI 软件开发的全链路难点根本不是模型本身而是传统软件工程里那套确定性思维被打碎了以后需求、架构、测试、运维每一层都要重新找抓手。这篇文章想把我在项目里走通的一整条路拆开讲清楚包括每个环节为什么这么设计、哪些地方容易踩坑、以及一些常规文档里不会写的取舍希望能给正准备从零做一个 AI 应用的同学省下几个月的弯路。1. 需求阶段的反直觉工作先定义 AI 的能力边界再谈功能1.1 一个看起来简单的问题判断文档语气到底是分类问题还是生成问题我在接手第一个 AI 项目的时候PM 给的原始需求只有一句给用户上传的文档做一个智能助手能回答文档里的问题。这个需求听起来非常明确但落到工程上第一件事根本不是画原型图而是把所有涉及 AI 的行为拆成一个个可验证的原子能力。比如回答文档里的问题这句话背后至少藏着三种完全不同的技术路径一是把整篇文档塞进上下文做问答二是把文档切成片段做检索增强生成三是先对文档做结构化摘要再基于摘要回答。三条路径对算力、延迟、准确率、成本的影响天差地别。最典型的反直觉案例是判断文档语气这个需求。看起来这是个文本分类问题两行代码就能调一个情感分析接口。但当你追问下去用户想要的语气到底是褒贬、正式程度、情绪烈度还是面向对象的措辞风格定义完全不同。如果答案是帮我判断这段产品文案是不是适合发给老客户本质上是一个生成式改写任务的前置条件而不是一个分类任务如果答案是群聊记录里哪些消息语气不好那就是一个需要上下文窗口的序列标注任务。分类和生成的工程链路完全不同前者可以用轻量模型 规则兜底后者必须走大模型 API 加提示词约束。我在项目里养成的习惯是接到任何带 AI 的活先逼着需求方把所有模糊形容词换成可观测的输出样例。不说要智能一点而是说给这段文字打三个标签置信度低于 0.6 就显示不确定性不说要准确而是说回答里必须引用文档原文编号引用不到就明确答不知道。这一轮做完AI 的功能边界才算真正存在。1.2 用输入-处理-输出模板拆解每个 AI 功能需求澄清阶段我用的工具非常朴素就是一张表格每一行是一个 AI 功能点列名是输入来源、输入示例、处理链路、输出格式、失败兜底。这张表比起任何高大上的架构图都管用。比如文档问答这个功能在我的全链路模板里会拆成三行第一行是问题理解输入是用户query和会话历史输出是一个重写后的检索query第二行是证据召回输入是重写query输出是文档片段列表和相关性分数第三行是答案生成输入是证据片段加原始query输出是带引用的回答。拆到这一步你会发现问题理解其实是最容易被低估的环节用户问第三页那个方案到底行不行单独拿这句去向量检索基本是废的必须结合文档标题和上一轮上下文先做 query 改写。这个模板还有一个隐藏作用它会逼你确认每个环节的失败表现。一个文档问答功能如果上游检索没召回任何片段处理链路要输出未找到相关信息还是继续让模型硬答这个兜底策略必须在需求阶段就定掉而不是等用户真问了才发现模型在编造。我见过太多项目把失败兜底留到测试阶段再补结果就是上线后被几个刁钻问题打得毫无还手之力。1.3 识别高风险场景什么时候不该用 AI全链路实战里最值钱的经验其实是判断哪些环节根本不该用 AI。我在某个项目里要做一个合同关键条款抽取功能刚开始想当然地走大模型 API让模型从合同文本里抽出租期、金额、违约条款。实测打了几十条格式确实漂亮但总有几条抽错金额或租期而且错得毫无规律。后来我让团队把需求改了先做规则模板匹配提取把能确定的字段用正则锁死只把规则覆盖不到的长尾描述交给模型做二次补充最后再过一道人工校验。准确率瞬间从 92% 提到 99% 以上成本还降了一半。这背后的逻辑是AI 是概率系统适合处理开放式、长尾、非标准化的内容而签合同这种场景关键是确定性一个数字错了就是事故。所有能用枚举、正则、查表、简单统计解决的子问题都优先用传统代码解决只有当传统方法覆盖率实在上不去才引入模型。把非 AI 优先写进需求评审清单会让整个项目稳定性和成本都上一个台阶。2. 技术选型为什么我选了 RAG 路线而不是微调以及模型 API 的关键参数2.1 通用大模型 API 与开源模型的取舍逻辑选型阶段全团队吵得最凶的就是用大模型 API 还是部署开源模型。我的结论基于三条非常朴素的约束项目上线时间、数据隐私边界、团队运维能力。如果是内部工具文档要喂给模型做问答数据基本都能脱敏到合理程度那就直接用成熟的模型 API把精力放在提示词、检索、评测上。真要微调绝大多数场景里微调一个几 B 的开源模型能力上大概率打不过当代最强的 API 模型还多出一支算法工程师的维护成本。如果是必须本地部署的强隐私场景再考虑开源模型但这时候你就得接受上下文窗口变小、指令遵循能力变弱、GPU 资源要长期占用的现实。我在全链路项目里实际走的是一条混合路线对外交互的智能问答用 API 模型保证质量和迭代速度内部一个纯规则场景先用开源小模型做降本验证效果不达标再切回 API由开关控制流量切分。这样既能把成本控制在预算里又不会因为模型质量卡住产品上线。2.2 检索增强生成RAG的技术架构与向量检索细节选型时我没有直接上微调因为业务核心是基于私有文档回答本质是一个检索问题而不是一个知识内化问题。RAG 的架构一句话就能讲清楚把文档切成小块向量化后存进向量库用户提问时先把问题向量化在库里搜最相似的一批片段再把片段和问题一起扔给生成模型做回答。但架构听起来简单工程落地的细节极其多我踩过的坑按权重排序大概是这样第一是切分粒度直接按固定 500 个字符切分会把一个完整的条款或论证切得七零八落检索出来的片段语义不完整模型自然答不对。我最后用的是标题层级 段落边界 最大长度三重切分逻辑优先保证语义完整性。第二是向量检索的召回数量太少则证据不足太多则把无关片段塞进上下文干扰模型我一般从 top5 起步结合评测集调整。第三是相关性重排纯向量相似度排在有些场景不可靠我习惯加一个轻量级重排步骤把向量后的前 20 个候选重新算一遍相关性分数取最高的 5 个进上下文这一步对回答准确率提升非常明显。这一整套链路如果用一张图来表示输入是文档原始文件输出是带引用的答案中间经过了文件解析、清洗、切分、向量化、召回、重排、上下文拼接、模型生成八个阶段任何一个阶段出问题最终答案质量都会整体崩掉。2.3 Prompt 设计在同一环节中的定位不是文案是代码很多团队把提示词工程当成写作文觉得只要描述得清楚就行。我在全链路项目里把提示词当成一份带测试用例的代码来管理模板进 Git每次修改必须跑同一个评测集对比通过率。提示词模板我的结构固定是五段角色定位、任务目标、输入数据格式说明、输出格式约束、失败兜底指令。其中失败兜底指令是最容易被忽略的例如明确写如果提供的参考片段不足以回答问题直接回复信息不足无法回答禁止猜测这一句话能把幻觉比例砍掉一大半。输出格式约束我倾向于用 JSON Schema 而不是自然语言描述实测模型对结构化指令的遵循率明显更高。同时提示词和代码一样要有版本。我在修改提示词后吃过一次大亏某次为了提升回答的详细程度加了一句请尽可能展开说明结果评测集通过率从 88% 降到了 72%因为模型开始把不确定的内容也展开编造了。从那以后提示词的任何改动都必须跑完整评测集不跑不许上线。3. 核心链路落地从文档解析到流式问答的后端实现3.1 文档预处理与向量化的工程细节到了编码阶段我的后端代码分四层数据预处理层、检索层、模型接入层、会话管理层。数据预处理层是所有下游质量的地基这块偷懒后面全白干。我在项目里接的文档格式包括 PDF、Word、Markdown 和扫码图片 PDF最让人头疼的是后者纯文本提取出来全是乱码必须先走一步 OCROCR 结果还要做错字纠正和段落还原。处理链路我定义成一个流水线原始文件进来先做格式识别再走文本抽取再做清洗去页眉页脚、去目录、去掉表格中的死文本然后按文档结构切块最后逐批向量化入库。每一批向量化都要记录对应的文档 ID、块序号、原文、来源页码目的是将来排查问题的时候能回溯这个回答到底引用的是哪一段原文。向量化的模型选择也很关键直接决定检索效果的上限。我用的策略是 embedding 模型和生成模型彻底分离embedding 选了一个性价比很高的中文向量模型生成走更强的 API 模型。这里有一个很容易踩的坑千万不要用同一个 embedding 服务既向量化文档又向量化用户 query因为文档往往是长文本、query 往往是短句二者分布完全不同检索效果会大打折扣。我实际的做法是给 query 加一个轻量改写层把短问句扩写成一句和文档风格相近的陈述句式再做向量化。3.2 大模型 API 接入层超时、重试、流式响应的处理模型接入层是全链路里最需要工程素养的地方因为对外部 API 的调用本质上是一个不可控的远程 IO你必须把它当成一个随时会失败的第三方服务来设计。我封装模型调用时的标准配置是连接超时 5 秒读超时 60 秒流式场景下放宽到首包 15 秒、包间隔 60 秒重试次数 2 次重试要带指数退避。更重要的是要区分错误类型限流错误可以重试鉴权错误和参数错误重试一万次也没用必须立刻抛给上层处理。我见过太多团队在模型 API 返回限流之后不管三七二十一重试三次结果三倍速触发更高级别的限流最后直接把服务拖垮。我写了一个简单的接入类用队列缓冲请求限流时先让请求排一秒队再重发实测能把可用性从 96% 提到 99% 以上。流式响应是问答体验的关键。后端对接 API 的流式接口时我用的方案是用异步生成器把模型返回的 token 块逐块推给前端同时每一块都检查是否包含引用标记等流式结束后再拼接完整的引用索引列表。有一个细节是流式场景下的超时处理比非流式复杂得多你不能光看总耗时要监控两个 chunk 之间的间隔一旦超过阈值就主动断开并给前端一个回答生成超时请重试的信号避免用户盯着一个永远不再动的光标干等。3.3 提示词模板动态拼接的代码实现提示词永远不要在前端拼也不要直接在业务代码里用字符串拼接正确做法是建一个专门的模板目录每个模板是一个独立的文件由渲染引擎填充变量。我在项目里的代码如下核心是两层模板外层是系统模板定义角色和任务内层是用户模板按功能拆成不同片段运行时根据意图动态拼接。我抽了一段实际代码结构大概是这样的from string import Template SYSTEM_TPL Template(你是一个严谨的文档问答助手。回答必须基于给定的参考片段。 如果参考片段不足以回答问题请直接回复信息不足无法回答。) QA_TPL Template(参考片段如下 $context 用户问题$question 请严格按照以下 JSON 格式回答 {answer: 你的回答, citations: [片段编号]}) def build_prompt(context: str, question: str) - list[dict]: return [ {role: system, content: SYSTEM_TPL.safe_substitute()}, {role: user, content: QA_TPL.safe_substitute( contextcontext, questionquestion )}, ]这段代码看着简单但背后有个很容易忽略的原则所有动态内容必须做转义和截断。我在项目里吃过一次亏文档内容里带了一段包含大括号的 JSON 示例直接把模板炸了。从那以后所有进入上下文的文本都要统一做格式转义并且设定单条片段最大长度上限超长部分宁可截断也不能破坏模板结构。另外上下文变量填充时如果检索结果为空也要走一个专门的空上下文模板而不是把空字符串硬塞进去否则模型会开始自由发挥。3.4 会话管理多轮上下文如何控制 Token 开销会话管理是后端最容易因为想当然而翻车的地方。新手第一版往往把每轮问答的完整历史全部塞进模型请求结果用户随便聊了几段长文档Token 直接破万慢不说模型反而被旧内容干扰开始答非所问。我最终采用的策略是分层管理短期记忆保存最近 6 轮对话的完整内容用于多轮指代消解长期记忆只保存用户问题的重写结果和对应答案的摘要每次构造请求时把长期摘要 短期窗口 当前检索片段拼在一起。这样做的好处是上下文里的旧问题旧答案压缩成了几句话给当前检索片段留出了充足的 Token 空间。其实大部分业务问答根本不需要完整历史用户不关心你上一轮答了什么他只关心当轮问题有没有被答准历史的作用只是帮模型理解它这个方案指代的是什么。我还做了一层敏感逻辑当用户问题变化主题时主动清空短期记忆窗口只保留系统提示词。这个判断我用的是一个简单的向量相似度阈值新问题和上一轮问题的相似度低于 0.3 就判定为新话题。这个小优化对多轮体验的提升非常明显否则用户刚聊完 A 文档里的问题转头问 B 文档里的事模型还在努力结合 A 的上下文强行作答。4. 前端体验层的真实门槛流式打字、连接状态与异常感知4.1 流式响应在 Web 端的实现思路我负责的项目前端技术栈相对主流但 AI 场景给它提出了一个传统后端渲染时代完全没有的要求接口不是一次性返回完整 JSON而是持续推送文本片段。对接流式接口不能在 fetch 里等 response.json()必须直接读 response.body 的 ReadableStream边读边把文本块追加到消息气泡里。实际写起来大概是这个形态前端先发起 POST 请求后端返回 200 后立刻开始推送 SSE 格式的数据块前端用 reader 循环读取每一块按行解析出 data 前缀的 payload再把 payload 里的文本增量插入到当前消息的末尾。这里有一个体验细节即使 AI 生成的速度不受前端控制你在插入文本时也要做一次简单的节流合并不要每收到一个 token 就更新一次 React state否则页面会频繁重渲染尤其长回答时直接卡成幻灯片。我在项目里把收到的文本先累积到一个临时 buffer用 requestAnimationFrame 每帧只 flush 一次整个交互瞬间丝滑。另一个常被忽略的点是流式过程里的生成状态指示。模型生成不是匀速的有时会停顿好几秒思考用户就会以为挂了。我做的处理是在最后一个 chunk 超过 2 秒没来时在打字光标处显示一个小状态提示正在整理回答而不是任由界面沉默。这个提示要放在消息气泡内部避免用户误以为系统卡死然后疯狂点重试。4.2 接口超时、模型幻觉和答非所问的前端兜底前端兜底逻辑是我在公司内部项目评审时被问得最多的一部分因为前端不像后端能看到完整日志它只能通过有限的信号做判断。我在前端统一封装了一个 AI 请求管理器把网络错误、接口超时、业务限流、内容为空、引用缺失这五种失败信号映射成五种用户可感知的提示。网络错误对应网络不稳定请检查连接接口超时对应回答生成超时请重试业务限流对应当前询问量大请稍后再试内容为空和引用缺失则对应未找到相关内容建议换个问法。其中引用缺失这个信号最有价值。我的问答接口返回结构里有一个 citations 数组如果 answer 存在但 citations 为空几乎可以肯定模型在凭记忆硬答即使答得看起来对也不能信任。前端拿到这种结果不会展示成功而是用黄色警示条挂在答案上方本条回答未引用文档片段仅供参考。这个设计救了项目一次——有用户拿模型硬答的结果当文档事实去走业务流程差点出事故。4.3 演示 Demo 与生产系统的差距在哪里前端在全链路里的另一堂课是Demo 级交互和生产级交互隔着一个维度的差距。Demo 只要能跑通一个理想链路输入问题、有答案、流式展示就算成功。生产系统要处理的是弱网下首包迟迟不来、用户连续多个问题导致并发连接数上涨、浏览器切后台再回来时流式连接已断开、以及回答中间插入的图表或公式格式一塌糊涂。我在交付前专门做了一轮相信用户手很滑的测试连续快速提交三个问题、问题输入框粘贴 10KB 文本、回答进行中直接刷新页面、切换浏览器标签页让连接假死。每一轮都暴露出新的问题最典型的就是流式中断后重新连接时前端怎么恢复之前的输出内容。最后我用了一个笨但可靠的办法后端每轮问答生成完会把完整答案存进会话记录前端在流式中断后发起一次补拉请求直接把完整答案一次性渲染出来替代残缺的半截流式文本。这个兜底不复杂却实打实地把用户流失率压下来一大截。5. 测试与评测AI 系统的断言到底怎么写5.1 传统单元测试为什么 cover 不住 AI 行为全链路里最让传统背景的开发同学不适应的就是测试。写单元测试时你已经习惯了输入 X 应该返回 Y但 AI 接口的同一句输入这次返回的是正确答案下次可能因为模型更新变成一句更啰嗦的正确答案再过段时间可能变成带有不同表述的错误答案。所以 AI 系统的测试核心不是断言返回什么而是断言返回的内容满足什么条件。我定义的第一类测试是结构断言返回必须是合法 JSON、必须含 answer 字段、citations 数组必须非空且每个编号都能对应到真实片段。这类测试用传统单元测试框架就能写也是所有 AI 测试里最容易也最该先写的。第二类是稳定性断言连续调用模型 20 次统计 answer 字段里出现关键实体的频率实体出现率低于 90% 就要报警。第三类是质量断言这类没法用代码自动跑只能靠人工评测集打分。5.2 建立最小评测集20 个问题跑一遍的基线方法很多团队做 AI 项目最痛苦的是没有评测基准每次改完提示词全凭感觉撑。我在项目启动第二周就建了一个最小评测集规则很简单找业务方要 20 个真实用户可能问的问题覆盖简单查询、跨段落推理、否定式提问、包含歧义指代、完全超出文档范围这五类。每类 4 问每个问题配一个标准答案要点列表几分制由我一个人先打分后续拉上两个同事交叉打分。这 20 个问题听起来少但它承担了三个关键职责第一是回归基线每次改提示词、换模型、调整切分参数都要跑一遍通过率低了就不允许合入第二是差异发现模型 API 发布新版本后第一时间跑一轮看哪些问题变好、哪些变差第三是上线守门员新版上线前必须跑到预设阈值。后期我们会把评测集逐步扩充到 200 条但普通团队不需要一开始就搞大而全20 条精挑细选的问题比 100 条随手凑的问题有用得多。5.3 回归测试Prompt 调整后的副作用排查只盯着通过率会有一个盲区就是通过率不变但回答行为漂移了。我在一次调整里把回答必须简洁改成先给结论再给论据通过率稳定在了 90%但上线后发现用户开始抱怨答案太干、没有展开细节。单独看通过率完全看不出来因为评测集里的标准答案只判定了正确性没有判定详细程度是否匹配用户预期。所以我的做法是评测集不光记录对错还要给每个回答打三个附加标签是否多余展开、是否过于简短、是否缺少引用。每次提示词变更后不只比较正确率还要比较这三个标签的分布一旦分布位移就要警惕。另外一个很实用的动作是保留每次改动的历史回答样本把老版本的回答和新版本的回答放在一起 diff而不是只看分数。AI 的输出是方差很大的你容易把一次偶然变好当成改动有效多跑几轮、多看 diff才能区分出真实增益还是随机波动。5.4 线上数据采集与人工标注闭环评测集终究是静态的真正的分布都在线上。我在全链路里很早就加了线上数据埋点记录每一次请求的用户问题、检索到的片段 ID、模型返回的回答、用户是否点击了有帮助按钮以及用户是否在收到回答后立刻重问了同主题问题。这个重问是一个很强的隐式负反馈信号哪怕没有评级也能反映出上轮回答可能没满足用户。每周我有一件固定的事挑出所有被标记为负反馈的问题导出一份表格逐条看检索结果片段和模型回答标注失败原因。归因也有一套模板问题 rewrite 失败、向量检索没召回、召回片段不完整、模型忽略召回片段、模板拼接错误、纯粹是模型幻觉。归因完成后对应的修法完全不同这比笼统地说效果不好管用得多。这个闭环跑三个月以后项目里最有效的质量提升手段反而不是更漂亮的提示词而是把高频失败的 30 个问题逐条解剖、逐条修掉。6. 部署、成本与长期维护上线只是全链路的起点6.1 部署环境的资源估算与模型 API 的容错部署阶段首先要破除一个误解AI 应用后端本身并不一定需要 GPU除非你本地化了模型。用 API 模型的架构里后端主要消耗的是 CPU 和内存真正的算力花在外部接口。所以资源估算要看两件事一是向量检索的 QPS二是模型 API 调用链路的并发数。我的实践是给后端服务设两个独立的连接池一个连接外部 API 的并发池一个连接向量数据库的并发池两个池子的水位相互独立谁都不能把对方拖死。限流一定要做在服务入口而不是压在模型接入层。我在网关层给每个用户设置了每分钟 10 次的调用上限超了就返回友好提示否则一旦某个用户疯狂刷问题直接打爆整条链路。API 提供商那边还有一层硬配额两层的配额系数我要留 30% 的余量因为流式请求的持续连接时间远比普通接口长平均并发和峰值并发的比例不一样余量不足会在流量小幅上涨时直接触发限流雪崩。6.2 Token 成本优化缓存、上下文压缩、模型分级AI 项目上线后第一个月最容易失控的就是成本账单把团队吓一跳几乎是全链路标配。Token 成本要拆成两部分来看检索部分的费用是固定的大头在生成部分而生成的成本又和输入 Token 长度、输出 Token 长度强相关。我的降本三板斧是缓存、压缩、分级。缓存是在问答层做的对完全相同或向量相似度超过 0.95 的问题直接复用历史答案不再调用生成模型。实测在文档问答场景用户高频问题重复度能到 30%一块缓存至少省下两成成本。压缩是控制输入 Token检索片段做去重和加权重排、把每轮历史对话摘要化、引用原文超过上限时按段落裁剪。分级则是引入一个轻量路由规则简单问答直接走便宜的小模型疑难问题才走贵的高阶模型。判定方式不复杂先用分类模型判断问题类型再设定一个是否超出基础模型能力的阈值两条路分流整体成本能再降两成体验几乎没有损失。6.3 日志结构化记录哪几个字段才能复现一次失败问答做 AI 项目做久了你会发现线上排查问题的成本远远大于开发成本而排查难的核心原因是日志设计得烂。普通接口日志记录返回码和时间就够了AI 问答的日志必须能完整复现一次失败的推理过程。我在项目里的规范是每条问答日志至少包含用户问题原文、重写后的问题、检索命中的片段 ID 列表及相似度分数、拼接后的完整 Prompt 前 500 字摘要、模型返回的完整回答、流式耗时与首个 token 耗时、Token 用量、失败码和重试次数。只有把这些字段都记完整才能在用户投诉答错了之后一次性定位是检索阶段没召回、提示词拼接炸了、模型跑偏、还是用户问题本身无解。有一半的答错了查到最后其实是用户问题超出了文档范围这时候你拿着日志去跟业务方对齐比空口解释高效得多。日志还会顺带解决另一个问题审计。文档问答系统如果涉及内部信息合规要求每一条 AI 回答都追溯得到引用来源结构化日志正好满足这个需求。我在部署时特意加了日志保留策略问答链路日志保留至少一年并且禁止任何清洗过程删掉 prompt 摘要字段。6.4 合规与安全的底线检查最后聊一聊合规与安全的底线这是全链路里最容易被人嫌烦、但绝不能省的一环。AI 系统最怕的不是模型能力不够而是模型把不该说的内容说得头头是道。我上线前强制走一套检查第一所有进入模型的文档内容先过一遍敏感信息识别手机号、身份证号、企业内部密钥这类直接脱敏或拒采第二Prompt 里内置输出约束禁止回答包含任何未经引用支持的内容这个在生成层面挡住一部分幻觉第三回答展示层再做一次关键词过滤即使模型输出了敏感词也不直接上屏。还有一条容易被忽略的不要在日志里原样记录用户上传的完整文档。文档内容可能很敏感日志里只保留文档 ID、文件名和片段摘要完整内容只存在于被加密的对象存储里查询权限单独审批。这个做法确实会让排查问题时麻烦一点但换来的是出事时你不会心惊肉跳。上线一段时间回头看全链路项目的成败不取决于哪段提示词写得妙而是这些挂在边上的脏活有没有踩实踩实了模型的那点不稳定性才不会酿成大事故。最后再分享一个小技巧如果你正在为 AI 项目建评测集别只找顺手的标准答案专门放几个故意刁难的边界问题进去比如文档里没写但你可能推断得出的结论到底能不能答。我一开始不愿放这种问题因为知道答不好但正是这种问题逼着我把信息不足必须拒答的兜底逻辑真正做进系统里。后来所有看似更花哨的优化都不如这一步带来的稳定性提升大。