说实话，我一开始看到“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工程链路长，任何一个环节出错都会导致最终回答出问题，而且表面现象经常和真正的根因隔得很远。我把项目期间遇到的高频问题、排查思路和解决方案整理成速查表，这比任何长篇原理说明都有用。

5.1 高频问题现象与根因

上面表格里最典型的一个坑，是“答案看着流畅但其实是错的”。这种场景大多不是模型能力问题，而是检索阶段把不相关内容推到了最前面。有一次我测试“如何申请办公设备”，系统回答了一大段关于保修的流程，仔细看日志才发现切分时把一个混合章节的文本块拆错了，导致保修段落里的关键词匹配分数虚高。解决这个问题，不是优化模型提示词，而是回去修正切分规则和索引逻辑。这个案例特别典型，它说明了一个原则：在AI工程里，凡是回答内容与预期不符，第一件事永远是查检索链路，而不是调生成侧，因为生成侧只是把你给它的内容重新组织了一遍而已。

另一个高频坑跟上下文有关。曾经有个用户问了一个非常复杂的问题，系统需要引用六个知识块才能回答完整，但在当时的窗口限制下只能放进去三个，于是答案变得支离破碎。后来我用分层摘要的方式，把多个知识块先做一个局部摘要压缩再拼接，问题才得以解决。这类场景让我意识到，上下文管理不只是“放得下”的问题，更是“放得恰当”的问题。

5.2 排查思路与通用检查清单

总结下来，我自己排查AI工程问题的顺序已经固化成一条路径：先看输入数据有没有问题，再看检索结果对不对，再看拼接进prompt的上下文是否合理，最后才看模型生成。任何一步出问题，后面的结果都必然走样。为了不遗漏，我给自己列了一个检查清单：

• 数据层：文档是否成功解析？清洗后内容是否保留完整语义？编码是否正确？有没有重复内容？
• 检索层：候选文本的召回分数是否合理？关键词与向量各自贡献了多少？精排后的前三名是否真正相关？
• 上下文层：拼接后的总token数是否在窗口内？文本顺序是否按相关性排序？来源标注是否完整？
• 生成层：提示词是否明确了回答边界？是否要求引用上下文？模型温度参数是否合适？

这套清单用了很久，每次问题定位基本五分钟内能锁定环节。维护这样一个排查体系，对我来说比写功能代码的单次收益更高，因为它让整个系统的运转状态随时处于可被检查的状态，而不是每次都要从第一行代码开始回头找问题。

我个人在项目接近尾声时的体会是，从零搭建AI工程这件事，困难的地方根本不是写代码，而是每一个决策都要基于你自己的数据和场景来做验证，不能照搬别人的参数。我会在每次调整切分大小、重排阈值或者提示词写法之后，都重新跑一遍评估集，看看数值变化，而不是凭感觉判断效果。最后再分享一个实用习惯：所有索引、配置、日志，都要有清晰的版本标记，AI工程的调试很多时候是在比较两个版本之间的差异，有版本追溯能力的项目，排查问题的效率会高出数倍。这套从零搭起来的东西，也许在某些环节不如商业平台的界面那么精致，但当你能精确控制它每一个token的去向时，那种踏实感，是任何黑盒方案都给不了的。