说实话我一开始看到“ai-engineering-from-scratch”这个项目名时脑子里浮现的是那种一堆人写过的“从零开始学AI”的入门教程又是环境配置又是跑通MNIST那种。但真正上手之后才发现这个“from scratch”的含义远比想象中锋利它不是说“我装个Python、调个API”而是指把一套完整的AI工程体系在没有现成平台支撑的前提下从裸环境开始搭建出来。那段时间我的目标非常具体不依赖任何开源成品方案也不直接用拖拽式AI平台就在一台普通服务器上从目录结构开始自己构筑一套私有知识库问答系统包括数据接入、索引构建、检索增强生成、Agent调用、评估与部署这一整条链路。这个过程让我真正体会到ai-engineering不只是一个时髦的热词它背后是一套非常扎实的工程方法论涉及模型选型、数据管道、检索策略、上下文管理、成本控制、稳定性设计这些实打实的决策。这篇文章就把我整个踩坑过程、技术选型的思考逻辑、关键模块的落地细节以及最终怎么让它稳定跑起来全部拆开讲清楚。无论你是刚准备进入AI应用开发的新手还是正在纠结要不要自建AI技术栈的团队负责人这份复盘应该都能给你一些可落地的参考。1. 项目从零开始的真实动机为什么非要从头造轮子很多人问我明明有那么多成熟的AI平台和框架为什么要自己从零搭一套这个问题的答案恰恰是理解这个项目所有后续决策的关键。我当时面对的真实场景是企业内部有大量非结构化的文档资料需要做一个内部智能问答助手但这些数据有很强的私密性不能直接交给外部SaaS平台处理而且交互模式也不是简单的“问一句答一句”而是需要在多个业务系统之间来回查询、汇总、对比甚至要触发一些后续动作。这就意味着我必须要有一支“完全可控”的技术栈能够精确到每一步的输入输出、每一个token的流向。1.1 需求盘点我要解决的问题到底是什么先把需求拆得很细这比直接写代码重要得多。我最终要交付的能力可以拆成五个层次第一数据层能接进来PDF、Word、Markdown、网页抓取等不同来源的资料清洗后统一入库第二知识表示层也就是把文档切分成合适的片段用向量模型转成可检索的表示第三检索层用户提问后能从知识库里召回最相关的片段第四生成层把召回的片段交给大模型组织成自然语言回答并且能标注引用来源第五行动层某些问题需要调用外部工具比如查数据库、发邮件这需要Agent能力。这五层任何一层所使用的现成平台都存在同样的天花板你在别人平台上积累的数据管道、检索策略、prompt调优经验换个场景就归零。而从零搭一套虽然前两周进度很慢但从第三周开始每一行代码都变成自己的资产。这个取舍非常像自己装修和请装修队的区别前者操作累很多但你对每一根电线的走向都心里有数。1.2 from-scratch的真正优势与隐藏成本这段经历里我印象最深的一点是自建方案的核心优势不在“省钱”而在“可控”和“可诊断”。用第三方AI平台出故障时你能做的只有提工单但自建系统出故障时你可以从模型响应、检索结果、向量距离、提示词上下文四个维度逐层排查。文档回答不准你能立刻判断是切分粒度问题、召回策略问题还是模型理解能力问题。但代价也很真实。最大的隐藏成本是时间尤其是前期的沉没成本。我从规划目录结构到第一条完整链路跑通花了将近三周如果算上反复调整的时间实际接近一个月。其次是运维成本模型服务、向量库、缓存、日志监控、API网关每一块都需要自己维护。所以做这个决策前一定要想清楚你是真的需要系统级自控还是只是想要一个能快速演示的Demo如果是后者用现成方案效率高得多没必要自讨苦吃。这个判断比技术选型本身更重要。2. 技术选型背后的一轮轮取舍技术选型是整个项目中最容易陷入“选择困难症”的环节。我给自己定了一个原则不追最热的新框架只选三条标准同时满足的方案——社区活跃且文档完善、自己团队能维护得住、能跟现有系统顺畅集成。围绕这三点我在每个关键决策点上都做了对比和取舍。2.1 语言与框架选Python但不盲从框架动手写第一个Python脚本时我几乎没有任何犹豫就锁定了Python作为主力语言。这倒不是说Python性能多好而是AI工程这个领域的整个生态都长在Python上不管是模型推理库、数据处理库还是向量计算库Python的调用成本最低。但接下来在框架层面我做了个反直觉的选择核心链路没有直接用那些重型的编排框架而是自己写了一套轻量级的流水线调度逻辑。原因很简单——当时我需要处理的知识库文档类型非常杂切分规则、清洗规则、入库逻辑各自都有特殊要求通用框架在这类场景下反而会变成约束。我实际最终用的是Pydantic做数据校验FastAPI做服务封装LangChain只在个别封装好的工具调用上做了集成没有让它主导整个链路。这种“取其长、避其短”的方式让我把更多精力花在业务逻辑上而不是去适配框架的抽象概念。对于团队没有做过深度AI项目的同学我建议初期至少把框架抽象层看一遍知道它是怎么工作的但真正写业务时按自己的数据结构来控制。2.2 模型接入策略大模型API与开源模型的组合拳模型选择上我没有走“一家独大”的路线而是做了一套双轨策略对话生成模块同时支持接入商用大模型API和本地部署的开源模型通过一个统一的模型网关来路由。商用模型适合对回答质量要求高、对成本不敏感的内部演示场景开源模型则用于大批量离线处理比如文档向量化、批量摘要、实体抽取这类不需要复杂推理但量很大的任务。向量化模型这块我最终用了中文效果比较稳定的bge-m3系列它支持8192的上下文长度对长文档切片的语义表示能力明显优于一些早期的embedding模型。这块我踩过一个很深的坑最初图省事直接用了一款通用英文向量模型处理中文文档结果检索召回率惨不忍睹很多同义词和专有名词完全匹配不上。后来换成中英双语向量模型召回率直接提升了一个档次。所以如果你的知识库以中文为主一定不要跳过用中英双语模型做召回对比这一步。2.3 向量库与存储选型向量存储经历了两个阶段。第一版为了快速验证直接用了一个轻量级的向量索引库优点是不用额外搭服务所有数据就是一个本地文件对初期的几十万条文本向量完全够用。但当数据量超过百万级之后它的查询性能明显下降而且没有原生的过滤能力我需要按文档来源筛选时就只能先把全量向量扫一遍再过滤效率很低。第二阶段迁移到了专门为向量检索设计的数据库支持集合分片、标量过滤和混合检索查询模式丰富很多。这里我总结出一个经验如果你的业务有“按部门、按文档类型、按时间范围过滤之后再做召回”这类需求向量库一定要选支持标量过滤的否则那个过滤操作会让你头大无比。从运维角度看选型的标准还包括别忘了检查备份与恢复的能力向量数据不像关系型数据库那么直观一旦损坏重建向量索引的成本是非常高的。3. 从零构建AI工程的五个核心模块前面几轮选型定下来之后项目终于进入了真正的工程实现阶段。这一部分我按数据接入、索引构建、检索生成、Agent编排、评估体系五个模块拆开来讲每个模块都包含我当时的设计思路和关键代码逻辑。3.1 数据接入与清洗管道第一个要解决的事情是让知识库“吃”进不同格式的内容。我用一套统一的DataLoader接口把所有文档来源抽象成同一类对象PDF走文本抽取Word走文档解析HTML走抓取清洗每类文档有自己的解析器但出口都是一组结构化的Document对象。这个设计的好处是后续所有的处理逻辑只要面向Document来实现完全不用关心原始文件是什么类型。清洗阶段要处理的问题很多比如PDF解析经常会带出页码页眉HTML会夹杂脚本和样式这些都需要通过正则或者解析树过滤掉。另外一个非常容易被忽略的点是编码问题很多中文文档是GBK编码如果不做检测和转换到了向量化阶段会出现一堆乱码向量整个索引就废了。我会在文本进清洗管道时统一做编码检测转成UTF-8再输出一份清洗日志方便后续追溯每个文档到底被改了什么。清洗完成之后我还会做一条重复检测逻辑用simhash算法计算文档指纹把内容相似度极高的重复文档剔除掉。这块是很多人会忽视的但真实企业文档库里同一个文件换个文件名存三份的情况太常见了不去重的话检索阶段同样的内容会被召回多次既浪费向量库空间又干扰答案质量。3.2 索引构建切分、嵌入与存储这是整个项目里技术含量最高的一环。文档切分的粒度直接决定问答质量我实验过按固定字符数切、按段落切、按语义切、按标题结构切四种方式最终的体会是没有任何一种切分方式能通吃所有文档类型必须要走混合策略。对于结构清晰的文档比如技术手册、规章制度我会先用标题层级做结构感知切分优先保证一个切块内部是同一个章节的内容对于小说、散文这类没有明确章节边界的文本再退回到固定窗口加重叠的方式避免把完整语义拦腰切断同时让相邻片段有部分重叠防止检索边界处的信息被漏掉。经过多轮问答结果对比我最终把默认切块大小定在450个字符左右重叠80个字符。这个参数不是拍脑袋定的而是因为我在生成环节的上下文窗口有限切块太大单块内容放不进prompt切块太小又会让语义碎片化。向量化环节我用了中英双语模型将每块文本转成1024维的向量。这里有个工程细节要特别注意每批向量化时要注意batch size和GPU显存的对应关系不然很容易OOM。我初期图快一次性把几千条文本丢进去生成结果进程直接崩溃。后来改成每批128条并加上了失败重试和日志记录才稳定下来。3.3 检索增强生成RAG查询链路查询链路我采用了“先召回、后重排、再生成”的三段式设计。用户提问进来后第一轮先用混合检索把候选文档找出来混合检索的含义是同时走向量相似度和关键词匹配两者结果做加权合并。这一步非常关键因为某些专业术语比如设备型号、合同编号向量检索可能匹配不到但关键词检索能精确命中反过来一些语义相关的近义词表达关键词匹配又搞不定所以两种方法必须互补。第二轮重排我用了一个专门做语义排序的精排模型把第一轮的候选按相关性重新打分。这一步带来的提升非常大在同样的测试集上经过精排的答案可接受度至少提升了15%到20%。最后才把精排前三的文本块拼装进prompt交给大模型生成。拼装时我会在每段文本前面标注来源文档和章节信息强制模型在生成时引用上下文范围内的事实这样回答的可信度和可追溯性都更好。3.4 Agent任务编排与工具调用知识库问答只是这个AI工程的一半另一半是Agent能力。有些问题光靠检索文档回答不了比如“帮我查一下上个月某个项目的上线进度”这需要去调用项目管理系统的接口。为了支持这类场景我给系统加上了一个简单的ReAct式工具调用机制模型在推理时先判断是否需要使用工具如果需要就输出一个结构化的工具调用请求系统执行工具并把结果反馈给模型模型再基于反馈生成最终回答。工具注册这一块我设计了规范化的接口每个工具需要声明名称、参数结构和功能描述。这里有个经验值得强调工具描述必须写清楚什么条件下该用这个工具、传入参数代表什么含义因为大模型是靠描述来理解工具的描述越模糊工具被误调用的概率就越高。我第一版工具描述写得太简单模型经常在应该检索文档的时候去调用了一个查询数据库的工具导致答非所问。后来我把每个工具的触发条件和禁用条件都写进描述里误调用率大幅下降。3.5 评估体系没有度量就没有优化很多自建AI项目最后烂尾根源就是没有评估体系。你改了提示词、调了切分参数到底变好了还是变差了如果没有一套统一的评估方法所有优化都是玄学。我花了不少时间搭建了一套离线评估管道准备了一组覆盖日常高频问题的测试集每条测试数据包含问题、标准答案、相关文档ID列表然后设定三个评估维度答案忠实度、答案完整性、引用正确率。忠实度的判断我会用一个更强大的模型自动打分再抽检一部分进行人工复核。为什么不用小模型来自动打分因为评估模型本身的理解能力如果不够打分结果比人工还不稳定根本没办法作为优化的依据。这套评估体系陪我走过了后面几乎所有的调参环节每次改动都要先跑一遍评估用数字说话而不是凭感觉说“好像变好了”。4. 实操过程复盘从能跑到跑稳的三个阶段从零搭建AI工程的整个过程可以很清晰地分成三个阶段。第一阶段的目标是让整条链路能跑通第二阶段是让系统在各种边界条件下不崩第三阶段才是性能、成本和可观测性的精细打磨。每个阶段的侧重点和踩坑方式完全不同。4.1 第一阶段先让Demo跑起来这个阶段不要追求完美所有东西能work就行。我用了两天时间先搭了一个最简版本读入几篇测试文档切分、向量化、存入本地向量索引然后写了个极简的问答接口。当时连缓存都没有每问一个问题都要实时调用模型速度很慢回答质量也一般但这个Demo最大的价值是让整条链路的每一个环节都有了真实的输入输出后面任何一次优化都能在这个基础上看到改动前后的对比。我强烈建议所有做AI工程的人千万不要在第一个版本就引入太复杂的架构。什么微服务、消息队列、分布式向量库统统先放一边。第一版的所有逻辑尽量写在一个进程里出问题好排查。这个阶段最核心的验收标准只有一条输入有一个明确的问题输出能有一个看起来靠谱的、有引用来源的回答。只要做到了你就已经超过了大多数停留在想法层面的人。4.2 第二阶段把边界条件和异常处理好Demo跑通之后接下来的工作重点是让系统具备生产可用性。这一阶段我处理最多的是两类问题一类是输入侧的边界问题比如用户提问太长怎么办提问内容侮辱性或者太短怎么办文档解析失败怎么办另一类问题是链路中的容错比如模型API超时了需要重试向量库查询异常需要有降级方案上下文超过模型窗口限制时需要做截断策略。这里分享一个踩过的很实在的坑最初我没限制单次召回文本的总长度当用户问一个需要引用多个知识块的问题时拼接出来的prompt很容易超过模型的上下文窗口导致请求直接失败。后来我加了一套上下文压缩机制先把所有候选文本加起来算token数超出阈值就按分数从低到高裁剪直到总长度满足窗口限制。这个机制上线之后服务再也没出现过上下文超限导致的报错。4.3 第三阶段性能、成本、可观测性优化链路稳定后我开始考虑效率和成本。性能优化的痛点是响应速度早期一次完整问答需要8到10秒用户体感很差。我做了三个优化效果立竿见影第一引入语义缓存相同或近似的问题直接命中缓存返回大量重复咨询场景下缓存命中率能做到将近一半第二把向量化模型常驻在显存里省掉了每次调用的加载时间第三对精排阶段做截断只对第一轮召回的前20个结果做精排而不是对全部候选评分减少无效计算。成本优化的核心在于正确把握“每一层该花多少钱”。我梳理了整条链路的成本结构发现大头在模型API调用上于是做了一个策略调整对于简单的、可以被规则明确回答的问题比如查询固定指标、获取文档列表就不经过大模型直接用检索结果加模板拼装答案只有真正需要推理和生成的复杂问题才走全链路。这个方案直接让日均API成本下降了将近40%而且回答质量没有下降。可观测性这块我用结构化日志记录了每个请求在数据接入、检索、精排、生成各环节的耗时和结果配合一个简单的看板展示日均调用量、平均响应时间、缓存命中率、检索召回率这些指标。有了这些数据之后每次优化都变成了有方向的事情。这一点对AI工程来说尤其重要因为你面对的模型行为不是100%确定的必须用数据来验证假设。5. 踩坑记录与问题排查速查表这部分专门写给会遇到问题的人。AI工程链路长任何一个环节出错都会导致最终回答出问题而且表面现象经常和真正的根因隔得很远。我把项目期间遇到的高频问题、排查思路和解决方案整理成速查表这比任何长篇原理说明都有用。现象可能根因排查手段解决方案回答内容明显错误或答非所问召回的相关文本不准确或补全后放错位置打开检索日志检查前几名召回片段的分数与内容调整切分参数、混合检索权重或重排阈值回答内容正确但缺乏引用来源生成prompt未附上文本来源信息检查prompt拼接逻辑中的来源字段在每段文本前显式标注文件名与章节号部分问题直接请求失败单次prompt tokens超出上下文窗口查看报错日志中的token数统计启用上下文压缩裁剪机制检索召回率很低专有名词查不到向量模型对领域术语不敏感用几个典型术语测试关键词与向量召回差异引入关键词检索与向量分数按权重合并语义缓存的相近问题没命中缓存key基于字符串hash而非语义向量观察缓存命中日志用问题向量相似度匹配缓存相似度超过阈值直接返回Agent工具被误调用工具描述不够清晰触发了错误行为查看Agent的推理链日志重写工具说明补充触发条件和禁用条件文档导入后部分内容检索不到清洗阶段把有意义内容误过滤了对比清洗前后文本日志调整清洗规则保留标题、列表等结构信息向量化过程中进程崩溃批次过大导致显存溢出查看运行日志中的OOM记录减小batch size增加异常重试重复内容在答案里反复出现知识库中重复文档未去重手动检索同一关键词看召回结果入库前用simhash指纹做去重处理5.1 高频问题现象与根因上面表格里最典型的一个坑是“答案看着流畅但其实是错的”。这种场景大多不是模型能力问题而是检索阶段把不相关内容推到了最前面。有一次我测试“如何申请办公设备”系统回答了一大段关于保修的流程仔细看日志才发现切分时把一个混合章节的文本块拆错了导致保修段落里的关键词匹配分数虚高。解决这个问题不是优化模型提示词而是回去修正切分规则和索引逻辑。这个案例特别典型它说明了一个原则在AI工程里凡是回答内容与预期不符第一件事永远是查检索链路而不是调生成侧因为生成侧只是把你给它的内容重新组织了一遍而已。另一个高频坑跟上下文有关。曾经有个用户问了一个非常复杂的问题系统需要引用六个知识块才能回答完整但在当时的窗口限制下只能放进去三个于是答案变得支离破碎。后来我用分层摘要的方式把多个知识块先做一个局部摘要压缩再拼接问题才得以解决。这类场景让我意识到上下文管理不只是“放得下”的问题更是“放得恰当”的问题。5.2 排查思路与通用检查清单总结下来我自己排查AI工程问题的顺序已经固化成一条路径先看输入数据有没有问题再看检索结果对不对再看拼接进prompt的上下文是否合理最后才看模型生成。任何一步出问题后面的结果都必然走样。为了不遗漏我给自己列了一个检查清单数据层文档是否成功解析清洗后内容是否保留完整语义编码是否正确有没有重复内容检索层候选文本的召回分数是否合理关键词与向量各自贡献了多少精排后的前三名是否真正相关上下文层拼接后的总token数是否在窗口内文本顺序是否按相关性排序来源标注是否完整生成层提示词是否明确了回答边界是否要求引用上下文模型温度参数是否合适这套清单用了很久每次问题定位基本五分钟内能锁定环节。维护这样一个排查体系对我来说比写功能代码的单次收益更高因为它让整个系统的运转状态随时处于可被检查的状态而不是每次都要从第一行代码开始回头找问题。我个人在项目接近尾声时的体会是从零搭建AI工程这件事困难的地方根本不是写代码而是每一个决策都要基于你自己的数据和场景来做验证不能照搬别人的参数。我会在每次调整切分大小、重排阈值或者提示词写法之后都重新跑一遍评估集看看数值变化而不是凭感觉判断效果。最后再分享一个实用习惯所有索引、配置、日志都要有清晰的版本标记AI工程的调试很多时候是在比较两个版本之间的差异有版本追溯能力的项目排查问题的效率会高出数倍。这套从零搭起来的东西也许在某些环节不如商业平台的界面那么精致但当你能精确控制它每一个token的去向时那种踏实感是任何黑盒方案都给不了的。