1. 项目概述：一个仓库背后的AI工程路线图
1.1 为什么会有 ai-engineering-from-scratch 这个项目
我接触 AI Engineering 已经三年多了。回想刚入门那会儿，最痛苦的其实不是模型不会调参，而是信息太碎。今天看到一段 Prompt 技巧，明天刷到一篇 RAG 优化文章，后天又被 Agent 概念刷屏，好像什么都会一点，真要动手搭一个能跑的应用时，大脑一片空白。这个项目的初衷就是把自己踩过的坑、走过的弯路、验证过可行的方案，整理成一条从零开始的路径，存进一个叫ai-engineering-from-scratch的仓库里。
这个仓库不是教科书，更像一份“工程逃生手册”。里面记录的是从明确业务需求开始，到选择模型、设计 Prompt、搭建检索链路、处理上下文、评估效果这一整套流程。核心思路很简单：AI Engineering 不是算法岗，不是你必须手写 Transformer、推导注意力公式才有资格入场。真正的工作重心是组合、编排、评估和调优。把大模型当作一个能力很强的实习生，你负责给它明确任务、提供靠谱资料、检查交付质量。
谁适合参考这份路线图？如果你是后端开发者想给现有系统加 AI 能力，或者是测试、运维、产品经理想搞清楚 AI 应用到底怎么落地，再或者你已经调过几个 API 但总觉得项目停留在 demo 阶段，那这份从实战中沉淀的思路会非常对路。它不要求你有深厚的机器学习背景，但要求你愿意动手、愿意反复调试。
1.2 AI Engineering 到底在做什么
这几年“AI 工程师”和“算法工程师”的边界越来越清晰。算法工程师的重点是训练模型，AI 工程师的重点是使用模型。用大白话讲，算法岗解决“有没有模型能用”的问题，AI 工程岗解决“模型怎么用出价值”的问题。同样是调大模型，AI 工程师关心的是：怎么让输出格式稳定、怎么控制成本、怎么把私有知识灌进去、怎么在用户访问量上来之后还能撑得住。
从核心内容看，AI Engineering 至少包含五大块：
- Prompt 工程：设计提示词，让模型的输出在格式、内容、风格上可控。
- RAG 检索增强：把外部知识库接入模型，解决“模型不知道、容易编造”的问题。
- Agent 与工具调用：让模型具备调用外部工具、拆解任务、多步执行的能力。
- 应用工程化：涉及流式输出、并发控制、缓存、可观测性、安全过滤。
- 评估与调优：建立评测集，用数据判断每一次改动是变好还是变坏。
现在回到ai-engineering-from-scratch项目本身。它的价值在于用一条主线把这些零散知识点串起来了。每个章节都对应一个真实会遇到的工程问题，而不是孤立的教程。下面我就按这个项目的进阶逻辑，逐层拆解每个阶段的要点和实操细节。
2. 从零搭建AI工程技能树：知识体系拆解
2.1 第一层：大模型基础与API调用习惯
很多新手上来就纠结“该学 LangChain 还是 LlamaIndex”，我个人建议先把裸调用 API 练熟。裸调用的意思是不用任何框架，直接通过 HTTP 或 SDK 请求模型接口。为什么这一步如此重要？因为框架每天都在变，API 返回的原始结构、Token 计费规则、超时重试机制这些是不变的底座。你只有亲手处理过返回的 JSON、处理过截断的流式响应，才可能在后面用框架时真正理解它的封装在做什么。
一个最基础的调用包含三个要素：模型名、消息列表、参数配置。很多初学者只关注前两个，忽略了参数。以常见的 Chat 接口为例，temperature控制随机性，max_tokens限制生成长度，top_p影响采样范围。不同场景对参数的要求完全不同：做分类抽取任务时希望温度接近 0，保证输出稳定；做创意文案时希望温度调高，让输出更发散。起步阶段建议把参数变化对输出的影响亲自测一遍，记录几个典型值，这是形成工程直觉的第一步。
另一个需要养成的习惯是让模型输出结构化内容。早期我总让模型直接回答一段话，结果下游系统根本没法解析。后来习惯在 Prompt 里强约束“只输出 JSON 格式，字段固定为 xxx、yyy”，再配合 API 的响应格式参数，把模型的输出从“语文题”变成“填空题”。这个习惯越早养越好，后面无论是接业务系统还是做评估，结构化的输出都省大量麻烦。
2.2 第二层：Prompt 工程与上下文窗口管理
Prompt 工程是 AI 工程里看起来门槛最低、天花板却很高的一块。说它门槛低，是因为任何人都能写几句指令；说它天花板高，是因为同样一个模型，高手写出的 Prompt 和新人写出的效果可能相差十倍。我的经验是，一个稳定的 Prompt 至少要包含四个部分：角色定义、任务描述、输入数据、输出要求。
拿“从客服对话中提取客户诉求”这个场景举例。差的 Prompt 可能就一句“请提取客户诉求”，模型输出五花八门。好的 Prompt 会这么写：
你是一名客户服务质检分析助手。下面是一段客服与客户的对话记录。 请从中提取客户的最终诉求，以 JSON 格式输出字段： reason：客户遇到的问题类型，用简短短语概括。 emotion：客户情绪，只能填写 平静、不满、愤怒、焦虑 之一。 demand：客户希望得到的具体解决方案，不超过50字。 对话内容： ...角色定义让模型调用正确的知识面，任务描述明确目标，输入数据划定处理范围，输出要求强制格式。四者缺一不可。
上下文窗口管理是这一层另一个绕不开的话题。现在主流模型动辄支持几十万 Token 的上下文，但从工程视角看，应该持保留态度。上下文越长，推理成本越高，首字返回时间越长，关键信息被稀释的风险也越大。更合理的做法是“够用就好”：把必要的背景压缩成几百字的提示词，把动态内容按相关性过滤后塞入，而不是一股脑把整份文档丢进去。
我自己的一个习惯是给 Prompt 里的历史消息设置滑动窗口。比如只保留最近 6 轮对话和数据库里提取出的用户画像摘要，更早的内容就丢弃掉。这种做法既控制了成本，又减少了模型被无关信息干扰的可能。
2.3 第三层：RAG 与向量检索的落地细节
RAG 是绝大多数 AI 应用绕不开的一环。大模型的知识截止时间是固定的，企业内部文档、最新的产品资料、个人笔记这些信息模型一概不知道。RAG 的核心思路是“先查后答”：用户提问后，先从知识库里找出最相关的片段，拼进 Prompt，再让模型结合上下文作答。这套机制有点像开卷考试，允许模型翻书，但翻书动作要在回答前完成。
在ai-engineering-from-scratch的实践记录里，我把 RAG 链路拆成了五个环节：文档解析、切片、向量化、检索、重排。其中最容易翻车的是文档解析。很多 PDF 里其实是扫描图片，直接切出来全是乱码，必须先用 OCR 转成文本。表格信息在转为纯文本时会丢失结构，遇到这种情况要把表格转为 Markdown 格式保留关系。这一步做不好，后面检索质量再高也是空中楼阁。
切片策略也是经验密集区。有人喜欢把文档固定切成 512 字的小块，觉得这样精准。但切片过小会破坏语义完整性，一个完整段落被切成两半，检索时很可能只取到一半。我的验证结果是用“标题层级 + 段落语义”切分更可靠：先按文档结构分块，如果块太大再继续往下切，同时给每块附带它所属的上层标题作为上下文前缀。这样既保持了语义完整，又让向量能捕捉到段落主题。
切片之后是向量化和检索。向量化是把文本映射成高维向量，语义相近的内容在向量空间里距离更近。这里有个细节：不是所有模型都擅长向量化，也不是向量化之后就不能用关键词检索了。实践中，把“向量检索的语义泛化能力”和“BM25 关键词检索的精确匹配能力”结合起来，做混合检索，通常能比单一检索高出十个点的召回率。检索出的 Top-K 片段不要直接丢给模型，接一个轻量级的 rerank 模型，把相关度重新排一遍，效果提升非常明显。
2.4 第四层：Agent 与工作流编排
Agent 是 AI 工程里最迷人的一部分，也是翻车率最高的地方。模型本身并不“会”做事，它只会生成文本。所谓的 Agent，本质上是写了一段循环：模型推理下一步该做什么 → 生成一个结构化的工具调用指令 → 代码执行工具并把结果返回给模型 → 模型基于新信息继续推理。这套机制看起来聪明，实际上如果没有边界，很容易陷入死循环。
我在项目里总结的控制原则是“凡事有据可查”。第一步是给 Agent 定义严格的能力清单：它能调哪些工具、每个工具的入参是什么、返回结果长什么样。第二步是限制迭代次数，一般 5 到 10 步之内必须给出最终答复，防止模型无限循环下去。第三步是要求每一步的关键决策都记录到日志里，方便问题复盘。
给 Agent 接入工具时有个细节值得单独说：工具的入参描述一定要写清楚。模型不知道你的系统里有多少张表、每个字段什么含义，它在决策时完全依赖你对工具的描述。描述越模糊，它就越可能填错参数。比如一个“查询订单状态”的工具，参数描述写成“订单号，字符串”就远不如“从用户消息中提取的订单号，通常是 10 位纯数字”效果好。这个现象业内叫“工具描述就像是给模型写说明书”，说明书的质量直接影响协作质量。
3. 实操过程：从0到1搭建一个AI问答系统
3.1 环境准备与依赖安装
讲完理论，进入实操环节。这里我以ai-engineering-from-scratch仓库里的一个入门案例为例：搭建一个基于本地文档知识库的问答系统。这个案例篇幅适中，既能覆盖 RAG 全链路，又不会上来就挑战 Agent 的高复杂度。开始前需要准备以下环境：
- Python 3.10 以上版本，建议用虚拟环境隔离依赖。
- 一个可调用的模型 API，并准备好密钥。
- 一个向量数据库实例，本地项目优先选择轻量级的 Chroma 或 SQLite 支持的向量库，避免一上来就部署集群。
- 一份测试文档，随便找几篇 Markdown 或 PDF 格式的说明书即可。
依赖安装只需要少数几个库：调用模型用的 SDK、文本切片用的langchain-text-splitters、向量计算用的框架、向量库客户端。我的建议是中途不要贪多装一堆框架，先把链路上的每个环节用最薄的封装跑通，再考虑上框架。
在requirements.txt里，核心依赖看起来像这样：
openai>=1.0.0 chromadb>=0.4.0 langchain-text-splitters>=0.2.0 pypdf>=3.17.0安装完成后，先做一个最小连通性测试：写一个几行的脚本，调用模型 API 让它输出“hello”，确认密钥有效、网络通畅、计费正常。这一步虽然简单，却能把后面排错的变量隔离掉一大半。我见过太多同学在集成框架时报错，最后发现是密钥填错了，白白浪费一晚上。
3.2 完整链路实现：解析、切片、检索与应答
搭建 RAG 系统的代码链路适合一步一步来。先实现文档加载：
from pypdf import PdfReader def load_pdf(path): reader = PdfReader(path) return "\n".join(page.extract_text() for page in reader.pages)看到extract_text()这里要警觉，扫描版 PDF 提取出来大概率是空字符串。如果是这种情况，需要先接入 OCR 服务，不能直接往后走。文本加载完后，进入切片环节。我用的是 MarkdownHeaderTextSplitter，它会按标题层级切分，并把标题信息保留为上下文：
from langchain_text_splitters import MarkdownHeaderTextSplitter splitter = MarkdownHeaderTextSplitter( headers_to_split_on=[("#", "chapter"), ("##", "section")] ) chunks = splitter.split_text(document_text)每个切出来的 chunk 都带了chapter和section的元数据。向量化时把这两项也一起编码，检索效果比纯正文好不少。切片做完之后，写入向量库：
import chromadb client = chromadb.PersistentClient(path="./kb_store") collection = client.get_or_create_collection( name="notes", metadata={"hnsw:space": "cosine"} ) collection.add( ids=[str(i) for i in range(len(chunks))], documents=[c.page_content for c in chunks], metadatas=[c.metadata for c in chunks] )写入向量库之后，检索逻辑就简单了。调用collection.query时把用户问题转成向量，按相似度返回 Top-K 结果。这里有一个经验：Top-K 不要硬编码成一个值，而要根据切片大小灵活调整。切片短、信息密度低时，取 6 到 8 个片段比取 3 个可靠得多；切片长、信息密度高时，取 3 到 4 个就够用。把 Top-K 设计成可通过环境变量调整的参数，方便后面做对比实验。
检索完成之后，把片段按相关度从高到低拼接到系统提示词里。注意控制总长度，一个通用模板是“你的任务基于以下参考资料回答问题，参考资料用 [1]、[2] 标注，回答中须引用对应编号”。这样模型在给出答案时能返回出处，下游用户可以回溯原文。最后把用户问题作为用户消息发送，整个链路就闭环了。
3.3 小型评估集：如何快速判断系统好坏
不少人在系统跑通之后就停下来了，这恰恰是错的。能回答问题不代表回答得好。严格来说，RAG 应用上线前至少要做一轮评估。评估不一定要高大上，我建议先准备 30 到 50 条测试问题，覆盖三种类型：显式查询、推理查询、反向查询。
显式查询指的是知识库里有现成答案的问题，主要检验检索召回能力。推理查询需要模型综合多个片段得出结论，主要检验指令遵循能力。反向查询是故意问知识库里没有的内容，检查模型会不会老老实实说不知道，而不是强行编造。三种类型比例可按 4:4:2 配比。
评估指标上，工程团队最容易上手的两个指标是“答案相关度”和“引用正确率”。相关度可以用另一个强模型来打分，也可以人工看。引用正确率更好统计：检查模型给出的答案里，引用编号对应的片段是否真的支撑了结论。如果引用正确率低于六成，说明切片或检索环节存在系统性问题，光调 Prompt 治标不治本。
我通常会把评估做成一个独立脚本，输入测试集、调用问答接口、记录输出结果、生成评估报告。每次改动，无论是更新 Prompt 还是调整切片策略，都跑一遍同样的测试集，用数据对比再决定是否上线。这个习惯帮我避开过很多“感觉变好了、实际变差了”的坑。
4. 常见问题与排查技巧实录
4.1 向量召回质量差，怎么办
我在项目运行中遇到过最频繁的问题就是召回质量差。典型表现是模型答非所问，或者明明库里有答案，模型却答不出来。排查这类问题，第一步要区分是“没查出来”还是“查出来没用上”。方法很简单：在日志里打印检索结果，人工看一眼 Top-K 片段。
如果检索结果本身就不相关，往下看三个环节。第一检查文档解析质量，文本是否乱码、表格是否丢失结构。第二检查切片粒度，是不是切得太碎或切错了语义边界。第三检查向量化模型与检索需求是否匹配。很多中文场景使用通用向量模型效果不理想，换成针对中文语料优化的向量模型就能显著改善。
如果检索结果相关但模型没有利用好，问题多半出在 Prompt 编排上。我踩过的一个典型坑是：多个片段拼接时没有区分优先级，模型被排在后面的低相关片段带偏了。解决办法是在模板中明确“优先依据编号靠前的内容作答”，或者在检索结果拼接时把高置信片段固定放在最前面。
4.2 Token 成本暴涨，如何控制
AI 应用的成本大头是 Token，尤其是 RAG 和 Agent 场景。一次请求把几十个片段全塞进去，单轮成本看起来不贵，并发一上去账单就难看了。控制成本的手段有两个层面：一是减少输入，二是建缓存。
减少输入方面，除了前面说的滑动窗口压缩历史消息，还要学会“摘要换全文”。对较长的历史会话，定期让模型生成一个几百字的摘要，后续请求只携带摘要，而不是完整对话。对检索片段，可以按相关度只保留 Top-K 中的前几段，低分片段宁可不给也不要滥竽充数。
缓存层面，最简单的方案是“完全相同的问题直接命中缓存”。稍微复杂一点的是“语义缓存”：把新问题向量化，如果在过去几小时内已有相似问题出现过，直接把当时的回答返回。这种方案对高频重复提问的场景能省下 80% 的调用量。不过缓存层要注意设置合理的过期时间，因为知识库内容更新后，旧缓存可能已经错了。
还有一个省钱技巧容易被忽略：为不同任务选择不同规格的模型。对简单分类任务用便宜的小模型，对复杂推理任务才用旗舰模型。做好这个分级策略之后，综合成本下降明显，而用户体验几乎无感。
4.3 上下文截断与输出异常
长对话场景经常遇到上下文超限的问题。模型输入长度有上限，一旦消息总长度超过限制就会报错。为了应对这个问题，我养成了给 Prompt 做“预算”的习惯：把模型输入上限想象成一块固定大小的硬盘，系统提示词、历史消息、检索片段、用户问题这几部分各占多少配额，心里有数。
实际操作中，我给系统提示词预留 20%，检索片段预留 30%，历史消息预留 30%，其余 20% 留给用户问题和模型输出空间。一旦某一部分超预算，优先压缩历史消息，其次裁剪低相关检索片段。这种配额式的管理方式在任何模型升级时都能快速适配。
输出异常主要指模型返回格式不合法，比如要求 JSON 却返回了多余解释、输出在中间截断、生成了非预期的空字符串。这类问题排查时先看原始响应日志，确认是模型行为问题还是客户端解析问题。如果是模型行为，一般在 Prompt 里加强输出格式描述，并开启“强制 JSON 输出”模式就能解决。如果是客户端解析问题，要给 JSON 解析做好容错，能处理模型中偶尔补全的尾逗号和非标准引号。项目里我用了一个容错逻辑：解析失败时先尝试修复常见 JSON 语法错误，再尝试用模型二次修复，最后才报错给用户。这几层退路下来，线上出错的概率大幅下降。
5. AI工程的工具链选型：我的最终取舍
5.1 框架选择：LangChain、LlamaIndex 还是原生代码
ai-engineering-from-scratch的仓库里有一章专门记录工具选型的思考过程。很多人问到底是选 LangChain 还是 LlamaIndex，我的答案是分阶段看。纯学习和低复杂度原型阶段，建议直接写原生代码，不引入框架。原生代码的好处是每个环节都是透明的，出了问题一眼就能看到。随着项目复杂度上升，比如要做多数据源的插件机制、需要丰富的文档加载器支持，再引入框架会明显提速。
框架能让你 10 分钟搭出一个 demo，但也能让你在一个小版本升级后焦头烂额。LangChain 这类框架的抽象层次高，API 变动频繁，社区里戏称“跟着文档更新就已经耗尽精力”。如果你已经有了一段原生代码跑通的基线，引入框架时就可以按需引入：只用来处理文档加载和解析，链路核心部分继续用原生代码控制。这样兼顾了开发效率和可控性。
LlamaIndex 在数据索引和检索方面底子更扎实，尤其适合以知识库为核心的 RAG 项目。租用工具越多越要理解每个组件的独立性。我最后的取舍是，工程化程度高的业务系统里，通信层和编排层自己写，检索和解析部分适度引入成熟库，避免被单一框架绑架。
5.2 模型选择：API 还是本地部署
模型的选型决定应用效果的下限。很多团队困惑于“到底用闭源 API 还是本地部署开源模型”，我的经验是看三个要素：数据敏感性、成本结构、效果要求。
数据敏感的场景没得选，必须本地部署。虽然部署开源模型需要 GPU 资源，团队初期可能在基建上投入较大，但数据不出域的合规压力会小很多。效果敏感而数据不敏感的场景，闭源大模型 API 是更省力的选择。它的综合能力通常优于同参数量的开源模型，配套的工具链也更成熟，接入成本低。
成本结构上要注意别只盯着单价。本地部署看似单次调用便宜，但 GPU 硬件折旧、运维人力、机房电费都是隐形成本。当并发量稳定且较高时，本地部署才有规模优势；当并发波动大或业务早期验证时，按量计费的 API 更划算。我建议做一次成本模型测算，把硬件、人力、调用量预估放进去，用数据说话。
另外还有一个折中方案值得考虑：把两者结合。企业内部的敏感核心知识用本地模型处理，非敏感的大规模开放域对话走云端 API，甚至可以按请求路由，实现“敏感数据隔离 + 顶级模型兜底”。这种混合架构在实践中越来越常见。
5.3 向量数据库：从原型到上线的选型建议
向量数据库的选型也是个热点。个人项目或原型验证阶段，直接用轻量级嵌入式向量库即可，比如 Chroma 或 LanceDB。它们随应用一起启动，不需要额外运维服务，几十万条向量规模内表现良好。我很多实验性项目都跑在嵌入式向量库上，省去了连接管理和部署的麻烦。
到了百亿级向量规模或多实例并发访问阶段，才需要考虑独立的向量数据库服务。目前主流的方案有三类：专用向量库、自带向量检索的全文数据库、以及云厂商托管服务。专用向量库单查性能强，但在复杂查询和多字段过滤上不如全文数据库灵活。在实际业务里，仅仅按向量相似度检索往往不够，还需要对文档来源、更新时间、用户权限做过滤，这时全文数据库的 SQL 能力就显得很重要。
所以在选型上我给出的建议是：别迷信“向量”两个字，先列出应用的过滤条件、数据量级、写入频率、延迟要求，再倒推选型。原型阶段用嵌入式方案，线上根据过滤复杂度选择。换库成本比想象中高，先把需求定义清楚能省很多迁移的眼泪。
6. 项目复盘与持续迭代思路
6.1 仓库内容如何持续更新
ai-engineering-from-scratch不是一份写完就固定的文档。AI Engineering 这个领域变化太快，模型产品几乎每个月都在出新能力，新框架也在不断洗牌。把项目当作“活文档”的关键在于，每次实践都要留一手记录。我在处理新需求时，会把“踩坑背景、实验参数、线上表现”三件事记录下来。这些记录比任何转载的技术文章都更有参考价值，因为它们建立在真实业务数据上。
具体操作上，我给仓库每个关键模块都配了一个 README，里面包含典型的失败案例和对应的决策过程。比如某个切片策略为什么被放弃、某次模型升级后哪些 Prompt 需要重写。这些“做决策时的上下文”是文档里最值钱的部分，也是from scratch这条学习路径的灵魂：你看到的不是结论，而是结论是怎么来的。
另外还要留意能力边界的迁移。以前觉得做不了的方案，比如用大模型做结构化数据抽取、做 OCR 纠错、做代码评审，会因为模型能力升级而变得可行。保持定期刷新的习惯，用最小 demo 验证新能力，把验证结果更新进文档，这个项目才能真正陪伴你从入门到熟练。
6.2 从问答系统走向复杂应用
项目做到一定阶段，单纯做问答已经不够了。后续迭代可以考虑三个方向：第一个方向是把单个问答节点嵌入到业务流程里，比如从“回答人力政策问题”升级为“根据问题自动提交工单并跟踪处理进展”。第二个方向是给问答系统加上多轮自主规划能力，让它根据用户目标拆解任务、调用多个工具、逐步完成。第三个方向是建立反馈闭环，收集用户对回答的点赞点踩，定期微调 Prompt 和检索策略，让系统越用越顺手。
这三个方向越往后越考验工程能力，尤其是可观测性和回滚机制。我不推荐一上来就把系统设计成纯 Agent 形态，那容易陷入不可控局面。稳妥的思路是保持“一个主流程 + 多个确定性子流程”，让 AI 只在需要判断和归纳的地方介入，其余环节继续用传统代码控制。这个思路在稳定性和灵活性之间能取得很好的平衡。
根据个人经验的体会，从零开始做 AI Engineering 最忌讳的就是“感觉懂了就停手”。你花一天跑通的 demo 只证明模型能工作，不证明方案能落地。真正拉开差距的地方在于：你有没有想过回答质量怎么度量、成本失控怎么办、失败的时候能不能快速定位。把这些问题在每个项目里都主动过一遍，你的工程判断力自然会成形。希望这份从 scratch 整理出的路径能让你少走一些我走过的弯路。
