说实话“ai-engineering-from-scratch”这个标题我第一眼看到就想起了自己半年前在团队里啃过的硬骨头手上只有一堆模型 API 和一份“先做个 demo”的需求真正上手才发现从零开始搭一套能跑、能测、能上线的 AI 工程系统和写几个 prompt 玩一玩完全是两码事。这个项目后来被我整理成了一个内部工程实践笔记今天把它展开成文正好也帮那些停留在“调用 OpenAI/Claude 接口”阶段的同学补上一课完整工程视角。这篇文章的定位很明确不是教你训练模型而是带你走一遍 AI 工程ai-engineering的完整闭环——从需求拆解、技术选型、数据管道、检索增强、Agent 循环到评估体系和可观测性。适合正在搭建企业级 AI 应用、或想系统掌握 LLM 工程化能力的后端工程师、算法工程师和技术负责人。你会看到每一种选型背后的原因也会看到那些只有踩过坑才会知道的细节。1. 项目整体设计为什么值得从零开始攒一套 AI 工程栈1.1 核心需求解析别急着调 API先想清楚系统长什么样很多团队拿到 LLM API 第一件事就是写 Prompt、调温度参数然后丢给业务方看效果。我不是说这不对这确实是验证 idea 最快的方式。但 ai-engineering-from-scratch 这个标题里真正关键的不是 ai-engineering而是 from-scratch——它意味着你要亲手设计整条链路的每一层而不是把什么都塞给平台方。我接到这个项目时业务需求是做一个企业内部的文档问答助手。表面看就是一个“喂文档问问题出答案”的玩具。但往深了拆你会发现至少五个子系统文档接入与数据清洗层用户上传的 PDF、Word、网页链接格式杂表格和扫描件都有需要统一抽取和清洗。语义检索层问题进来要能找到最相关的文档片段这在 10 份文档和 10 万份文档之间完全是两个量级的问题。上下文组装层怎么把检索出来的片段拼成一个模型可用、不超窗口、不丢关键信息的上下文。生成与工具调用层模型不仅要回答还可能要去查数据库、调内部 API这就涉及 Function Calling 和 Agent 循环。评估、观测与安全层你怎么知道系统回答得好不好模型输出有没有泄露敏感信息延迟和成本怎么控制在动手写任何代码之前我花了整整两天把上面这张图在脑海里反复推演。这套流程我想称之为“先画架构图再写 CRUD”——AI 工程和传统后端工程最大的区别在于模型的不可控性会让上层每个环节都变成一道风险点你的系统设计必须围着不确定性展开而不是追求静态稳定。1.2 从零搭建的工程分层思路用毛坯房来类比我经常用一个类比来解释 from-scratch 和直接用平台工具的差别前者相当于自己装修毛坯房结构、水电、防水都得盯着后者相当于买精装房入住的省心但出了问题你根本不知道管线埋在哪个墙里。当时我评估过一些现成的端到端框架和云平台确实能让你上传文档自动帮你做切片、向量化、问答甚至自带 UI。但最终还是选了从零搭理由很实在透明性每一步数据怎么流动、在哪一层丢的信息我都需要可见、可控、可排错。定制化企业内部文档有强权限体系嵌入到检索层之前就要完成 ACL 过滤现成平台很难做细粒度。成本账平台按托管的向量数据库、检索次数、模型调用分别收费规模化之后比自己部署开源组件贵几倍。团队能力既然团队定位是长期做 AI那搭建一套内部工程能力比采购一个“黑盒”更有复利价值。但我必须诚实地说from-scratch 不等于所有组件都自己造轮子。我的选择是“业务流程和编排自己写底层存储和模型能力用成熟组件拼装”。这个度很关键——如果你连 Embedding 模型都非要从头训练那这个项目就不是 3 个月能交付的了。2. 技术选型与方案取舍每一层选择背后的原因很多文章讲技术选型喜欢直接甩清单看得人眼花缭乱。我这里反过来先列出我在每一层真正纠结过的决策再告诉你我当时是怎么拍板的。2.1 模型接入层大模型 API 与本地模型的取舍第一层是核心的生成模型。说实话在 2024 年之后“要不要自己部署模型”已经不那么值得纠结。真正让我纠结的是主链路用商用 API还是本地私有化模型。我们最后采用了“双轨策略”主问答链路用 OpenAI 的 GPT 系列或 Claude API因为指令跟随能力、长上下文理解、工具调用稳定性确实是目前的开源模型比不了的。业务对效果敏感与其省那点 token 钱不如先把体验做好。在数据脱敏严格、网络隔离要求高的内部流程里走本地部署的 Qwen 或者 Llama 系列速度慢一点但敏感信息不出内网。有没有成本优化的技巧有。我们给不同任务分了不同模型规格——简单分类任务用 mini 型号长文件总结用带长上下文的旗舰型号日常问答用中档型号。这不是偷懒是 Ai 工程里非常经典的成本分层策略。一个单点教训不要在代码里把所有调用写死成同一个 model 变量你会为了一个小任务付大模型的冤枉钱的。2.2 检索与知识库向量存储选型对比说到 RAG检索增强生成最绕不开的就是向量数据库。我在项目里真实筛选过以下方案方案部署成本扩展性过滤能力成熟度适合场景Chroma极低嵌入式一般弱中个人/原型项目FAISS低库形态强自己实现较高离线批量检索pgvector中复用 Postgres良好强可用 SQL 过滤高已有 PG 的团队Milvus高独立集群强中较高大规模生产环境云托管向量库高按量计费强中高不想运维的团队我们团队内部已经重度使用 PostgreSQL所以最终选了 pgvector。理由很朴素不用额外运维一套新系统还能把业务权限过滤、元数据筛选直接写进 SQL 里。比如用户问“上个季度的销售制度”检索语句里天然带一条WHERE department salesORtenant_id ...的过滤条件这种细粒度控制在纯向量库里反而要绕好几层。不过 pgvector 的索引有讲究我顺手补充一个经验数据量超过 10 万条向量时必须建 HNSW 索引并且m邻居数和ef_search检索范围要按召回率实测调我一开始偷懒没建索引单次检索秒级延迟直接让用户体验崩了。这事提醒了我向量检索和普通数据库一样索引设计是命根子。2.3 编排层框架与手写循环Agent 编排层一直比较有争议LangChain、LlamaIndex、AutoGen 等等框架迭代速度极快社区经验也两极分化。我自己的真实感受是用框架的早期阶段非常爽Chain、Retriever、Tool 这些抽象让复杂逻辑代码量骤减。但一旦涉及企业内部的特殊逻辑细粒度权限、长流程分支、审计日志框架的抽象反而是束缚出了 bug 你要去看框架源码成本比直接写循环高得多。最终定调核心 Agent 执行循环完全手写大概 300 行核心代码把“模型调用 → 工具执行 → 结果返回 → 再次推理”这个循环写成可控的业务代码。只在零散工具场景用了框架的轻量封装。实际效果是调试效率明显提升——因为每一步的日志都是我自己的代码打的出了问题我可以直接定位而不是在框架玄学的 abstract 之间猜来猜去。手写循环的另一个优点是你可以精确控制“最大迭代次数”。Agent 一旦在复杂工具链上绕圈子LLM 的 token 消耗是爆炸性增长的我在系统里强制加了一个死循环检测器连续重复同一个工具调用超过 3 次就直接终止。这个功能在很多框架里反而不好配置。2.4 可观测性与评估上线前的最后一公里这个环节是我认为 from-scratch 工程里被忽视得最严重的。很多人把 AI 应用上线后问题排查全靠用户截图反馈这是很原始的。我的建议是项目一开始就要同时搭三套东西结构化日志每次 LLM 调用的 prompt、completion、token 数、延迟全部落库。方便事后复盘。回放机制能按 request_id 把某一次回答的完整链路检索到哪几个片段、模型怎么推理的、最终输出什么重现出来这是定位问题的最强工具。评估集准备 100 到 300 条“黄金问题集”每条有标准答案或参考片段每次改 Prompt 或调参数就在这个集上跑回归防止修了 A 问题搞坏 B 问题。当时我劝团队不要迷信开源的可观测性全家桶而是先用“日志表 定时评估脚本”跑两周等真正摸清需求再上完整平台。结果证明这个决定很省钱因为初期我们对“到底要观测什么”完全没概念贸然上平台只会配置一堆用不上的面板。3. 核心实操从数据管道到 Agent 循环的完整落地理论知识说得再多不动手等于零。这一部分我把项目里最关键的四步实操完整展出来每个步骤都标注了当时实测过的参数和踩过的坑。3.1 第一步构建可检索的数据管道数据管道是整个 AI 应用的地基这部分做得越糙上层 RAG 的召回就越烂。我们的数据源主要是三种PDF 合同、Word 制度、内部网页。当时的处理流程是格式解析统一走 OCR 版面分析。PDF 里大量扫描件一开始直接按文本抽取结果一篇合同能抽出一半乱码。后来先用 PaddleOCR 跑了一遍版面识别把标题、段落、表格边界标记出来再按区块抽取。清洗阶段做三件事去页眉页脚、去重复空行、统一日期和金额格式。这一步看着不起眼但直接影响后面分块质量和检索命中率。分块Chunking用“固定大小 重叠窗口 结构感知”的组合策略。纯按字符硬切会把段落腰斩语义断裂严重。我们按 Markdown 标题和段落边界优先切单块控制在 256-512 token 之间块与块之间重叠 32 token。为每一块生成 chunk_id、来源文档 ID、权限标签、更新时间等元数据后面过滤全靠它。Embedding 模型我们也小测一轮。开源榜单里榜首的模型不一定是你的最优解。我们实际业务偏财务和法务中英混合测试了 4 个候选模型后选了一个在专业词相似度上表现稳的通用模型。选模型这件事我的建议是不要只看 MTEB 跑分下载 200 条你自己领域的问题来实测一来一回差很多。顺便提个参数细节我们所有文档统一用max_tokens512作为 embedding 输入窗口太长直接截断不然计算成本上去了精度并不会因此提升。3.2 第二步RAG 检索与上下文工程数据入库不是终点检索才是决定回答质量的生死线。我在这个环节重构了三次核心教训就是“检索不能只靠一次向量相似度”。完整链路是这样的问题改写Query Rewriting用户问“那个文件什么时候发的”如果直接拿原句去检索召回效果一塌糊涂。先用一次轻量模型调用把它改写成“文件发布时间查询”这类信息量更完整的检索词。多路召回同时做向量检索语义相似和关键词检索BM25把两路结果合并。纯向量检索对名词和编号不敏感比如查“合同编号 SW-2024-001”BM25 保你命中向量检索未必。重排序Rerank合并后的候选片段有 50 条左右全部塞进上下文让模型去读不现实。用 bge-reranker 这类排序模型把候选按相关性重新打分只保留 top 5。权限过滤在最终组装上下文前按当前用户的 ACL 过滤避免出现越权文档片段。组装上下文有个死角总 token 控制。我们当时的系统最大窗口是 128k但你不能真把 128k 全部塞满要给模型留推理空间。经验值是填入不超过窗口的 60%-70%例如 128k 的窗口检索片段加上系统提示词控制在 60k 以内。超出后按相关性从低往高丢片段而不是简单按长度截断——直接截断容易把最关键的答案切掉。说到上下文工程很多人忽略“指令与片段之间的分隔明确性”。我不会用一句话让模型区分数段来源而是用 XML 标签把每段原文包起来并且在 Prompt 里写明“请只根据doc标签内的上下文回答如果上下文不充分直接回答‘知识库中未找到相关信息’。”这个简单的结构化设计直接让幻觉率降低了一大截。3.3 第三步设计一个带工具的 Agent 执行循环当业务复杂度上升单纯问答就不够了。我们的业务里用户可能会问“对比一下上季度和前季度销售数据并输出一份 Markdown 报表”这需要模型去查询数据库、计算数据、再生成答案。这个场景下我手写了一个工整的 Agent 执行循环核心逻辑如下def run_agent(user_query, tools, max_iterations5): messages [{role: user, content: user_query}] for step in range(max_iterations): response call_llm(messages, toolstools) assistant_msg response[message] if assistant_msg.get(tool_calls): messages.append(assistant_msg) for tool_call in assistant_msg[tool_calls]: result execute_tool(tool_call) messages.append({ role: tool, tool_call_id: tool_call[id], content: result }) continue # 没有工具调用说明可以结束并返回最终答案 return assistant_msg[content] raise AgentTooManyIterations(user_query)这个循环简单到有点“幼稚”但恰恰是这套简单结构在生产环境里异常稳定。我给它配备的工具包括查数据看板、查合同库、抽取某个文件关键信息每个工具都用一个 JSON Schema 描述输入输出模型通过 Function Calling 来调用。我提出几个工程化细节特别容易踩工具描述里要写清楚“什么时候用、什么时候不要用”。比如查合同工具的描述是“当用户询问合同条款、金额、期限时使用当用户只是在闲聊时不要使用”。模型比你想象的更吃这个。工具执行超时必须有硬限制我们给每个工具调用加 15 秒超时超时返回一个固定文案“工具执行超时请重新描述需求”。结果返回给模型之前要做截断。数据库查询可能返回 5 万行模型根本读不完我们在工具内部先做聚合只给模型返回摘要指标。每次迭代都要把当前 step 数暴露给模型比如在工具返回里带上“当前已经执行第 4/5 步请精简动作”有效减少 Agent 陷入循环的概率。3.4 第四步成本、延迟与护栏设计模型调用不像 SQL 查询每次执行都是真金白银尤其在 Agent 场景一次问题可能偷偷调用 10 次模型。我在成本上控制得很细三个手段第一是语义缓存Semantic Cache。一个问题如果和历史问题语义近似直接返回历史答案不再走模型。我们用向量相似度做判断阈值设 0.9 以上直接命中能省 20%-30% 的 token 开销延迟也压到 50ms 内。第二是 Prompt 压缩。系统提示词和工具描述会反复跟随每次调用发送我们每月做一次压缩审计去掉那些加进去之后从来没有启用过的冗余描述。第三是流式输出。把首字延迟从 2 秒压到 0.3 秒用户体感提升非常明显这属于“花钱买体验”的正确姿势。护栏设计上我们做了两个强制性模块输入侧 PII 检测用户问题里如果带身份证号、手机号先打码再进模型防止敏感信息被记录进外部日志。输出侧合规校验模型生成结果里如果意外带出“内部员工工资”“未公开财报”等关键词直接拦截并返回安全模板。4. 踩坑实录与排查技巧最后这部分是这次 from-scratch 项目的最大资产我把真实排查过的高频问题整理成一张速查表然后挑几个详细拆解希望你能少走几个月的弯路。4.1 高频问题速查表现象根因定位方法解决方案回答内容与知识库事实不符检索片段不相关上下文被无关信息污染回放检索链路检查 top5 片段相关性优化 Embedding 模型引入 Rerank同一问题前后回答不一致模型抽样式输出温度参数过高查看同一 prompt 多次输出的差异把 temperature 降到 0.1-0.3回答前先让模型“草稿思考”Agent 陷入死循环工具返回信息不足以让模型做出下一步决策打印每轮工具返回的消息长度限制最大迭代次数工具返回里加“当前步骤摘要”检索永远召回不到关键片段分块把关键句子拦腰截断了检查 chunk 内容找断裂点改造分块策略按段落边界切分token 消耗暴涨上下文组装没有截断长文档片段全部塞入查看每次请求的实际 token 明细按相关性裁剪片段限制上下文上限模型输出违反格式要求Prompt 里 JSON 格式要求与系统消息冲突查看完整 prompt 各 role 的内容统一格式要求放在 user 消息末尾测试不同 prompt 位置的效果权限过滤形同虚设过滤操作放在生成之后而不是检索之前查看日志确认片段来源把 ACL 过滤下沉到数据查询层4.2 几个值得一提的教训第一个教训发生在 Embedding 模型切换那天。我们团队看到新模型跑分更高果断切换结果当天用户反馈检索质量骤降。排查了两小时才找到原因我们存储在向量库里的 embeddings 是用旧模型生成的你不能把新模型生成的向量和旧向量混在一个库里检索——空间不一致相似度没有任何意义。这件事的直接代价是所有文档重新切片、重新向量化、重新入库。所以后来我们养成一个习惯任何向量化代码升级第一步永远是全量重建向量索引而不是局部增量。第二个教训和 Prompt 的“位置敏感度”有关。我们的系统消息里写了一大段 JSON 输出格式说明同时工具定义也要求 JSON 格式模型有时候就“精神分裂”了一会儿输出工具调用一会儿直接输出 JSON 文本格式校验直接挂掉。后来我把输出格式要求从系统消息挪到最后一轮 user 消息里并用明确的“请只输出如下 JSON”句式稳定性立刻好很多。为了让模型默认输出 JSON我还在调用参数里加了response_format{type: json_object}但要注意某些模型不支持这个参数需要做兼容。第三个教训跟成本有关。我们上线初期的用户场景是“长文档分析”一个 100 页 PDF 全量塞进模型分析一次分析要烧掉几美元的 token。一开始没有在意等月末账单出来才知道痛。后来我们把长文档统一转换为“结构化摘录 分段分析 汇总综合”三步流水线先让模型分章做摘要再让模型基于摘要做综合成本直接降了一个数量级。这里有一个关键点长文档的场景不要指望一次 prompt 解决拆分粒度本身就是 Ai 工程能力的体现。5. 后续扩展方向与个人体会如果这个项目继续往下走我目前看好的三个方向分别是多智能体协作把文档问答、数据分析、报告生成拆成不同角色专职单干、评估自动化用 LLM-as-a-judge 的方式给每次回答自动打分把人工回归从每周半天压到十分钟、以及更细粒度的在线学习不是微调模型而是基于用户主动反馈动态调整检索权重。最后说一句这段话最核心的经验。做完 ai-engineering-from-scratch 之后我最大的体会是AI 工程里面 70% 的问题不是模型不够聪明而是系统设计不够稳。你可以把大模型想象成一个才华横溢但不太靠谱的新员工你要做的不是给他一本《百科全书》而是搭好一套工作流——告诉他知识库在哪、工具怎么用、什么情况必须停下来问人、什么情况可以自己拿主意。这套工作流的主体就是我们前面写的检索链路、上下文工程、Agent 循环和护栏。只要你把这几层控制好模型本身的短板大部分都可以被工程手段对冲掉。做这个项目之前我总想着把模型换成更强大的做完之后我更愿意花时间把数据、检索和评估做到位。希望这篇记录对你有用也欢迎你把实操中遇到的坑扔过来聊聊。