1. 先认清定位AI工程不是调API也不是背概念1.1 为什么这个仓库值得从零开始说实话我最初看到ai-engineering-from-scratch这个项目名时第一反应是又一个学习清单仓库。这类仓库在GitHub上太多了基本都是把论文、教程、工具链接一股脑扔进去标个上千星然后大家收藏完就再也不看。但仔细翻了翻这个项目的内容组织方式我发现它跟那些收藏夹型仓库有本质区别——它把从零开始当作一条真正的学习主线而不是资料聚合。我见过太多人学AI工程的方式先买一堆课程把Transformer、注意力机制、反向传播背得滚瓜烂熟然后打开IDE发现自己连一个完整项目都搭不起来。反过来也见过另一批人一上来就死磕LangChain源码结果连提示词的基础规则都没搞明白做出来的Agent一跑就崩。这两种极端我都有过切身体会。早两年我做传统后端开发自认为工程化能力还行结果第一次碰大模型应用时写的代码跟玩具一样——没有版本管理、没有测试、没有评估模型换一个版本整个输出就全变了。那时候我才意识到AI工程不是会用大模型API而是把模型、数据、评估、部署、监控当成一个系统工程来设计。这个仓库的定位正好打中这个痛点它不教你数学推导也不教你背诵概念它教你如何用工程手段把AI能力稳定地落地。1.2 AI工程师和算法工程师的边界在哪里很多新手分不清AI工程师、算法工程师、数据工程师这三个角色的区别这个认知偏差会直接影响你学习路径的设计。算法工程师的核心是发明或改进模型——搞新的网络结构、调新的训练策略、刷新的指标他们围绕模型本身工作。而AI工程师更准确地说是AI应用工程师核心是把现有的大模型能力封装成稳定的产品功能工作重心在提示词编排、Agent逻辑、上下文管理、评估迭代、部署监控这些环节上。举个简单例子算法工程师会研究如何让模型在数学推理上表现更好可能涉及微调或蒸馏AI工程师则是在模型已经具备数学推理能力的前提下设计一套提示词框架和工具调用链让模型能够稳定地完成一道多步应用题并在出错时能自我纠错或转人工。所以你在学ai-engineering-from-scratch这类项目时要带着产品思维去学而不是研究思维。你的目标不是发明新模型而是把现有模型用到极致。这并不意味着算法知识不重要——恰恰相反理解模型的能力边界、上下文窗口机制、温度参数对输出分布的影响能帮你大幅减少调试时间。但学习的优先级必须是先会工程再补理论而不是反过来。从实战角度讲我推荐的认知模型是这样的把大模型当作一个能力不确定的实习生把AI工程当作一套管理这个实习生的制度体系。提示词是你给他的任务说明书Agent框架是你在旁边配的监工RAG是你给他的资料库评估用例是你的验收标准日志和监控是你看他每天工作表现的考勤表。这套制度设计得好实习生就能稳定产出设计得不好他今天超常发挥明天直接摆烂。2. 知识版图Prompt、Agent、RAG与模型部署四条主线2.1 Prompt Engineering最基础也最容易被低估很多人觉得Prompt Engineering只是写指令这大概是AI工程领域最大的误解。真正在生产环境里跑过的人都知道提示词是系统设计的一部分它跟代码一样需要版本管理、需要测试、需要遵循设计模式。我举个例子你就明白了。早期我做客服问答机器人最初的提示词写的是请回答用户的问题后来发现模型经常答非所问而且有时候会编造一些不存在的售后政策。后来我把提示词拆成了四个部分系统角色设定、背景知识库引用、回答规则约束、输出格式要求并且建立了十几个典型的边界场景测试用例每次改动提示词都要跑一遍这些用例。这时候提示词就不是一段话了而是一份像代码一样可维护、可回滚、可评审的工程资产。具体到实践层面我总结了几个关键点。第一外部知识必须先于问题注入也就是说提示词里要先放检索到的文档再放用户问题不然模型会优先响应后文中的指令第二负面约束要具体化不要只写不要胡说八道而要说当检索到的资料不包含相关信息时必须回答当前没有查到该问题的资料第三要求模型先推理再回答通过Lets think step by step这类引导词虽然老套但在复杂推理任务中确实能降低错误率代价是Token消耗增加需要评估收益是否能覆盖成本。还需要注意的一点是Prompt本身存在脆弱性问题。你可能用几分钟写的一个不错的提示词在模型换版本之后突然失效。GPT-4时代好用的提示词模式可能在新的模型上表现反而变差。所以Prompt必须要做版本管理并且每次模型供应商更新版本之后都要拿同样的测试集跑一遍回归测试——这不是可选操作是必须的操作。2.2 Agent与Harness Engineering从单次调用到自主工作流Agent是这两年AI工程最热的方向但也是概念最混乱的方向。从我实际做项目的经验来看Agent的本质就是给模型加上了工具调用能力然后在一定约束下让模型自主决策下一步动作。听起来很酷但工程上的复杂度会指数级上升。先说Harness Engineering这个概念最近圈子里提得很多。它指的是为Agent设计一套约束和支撑系统的工程实践——包括限定工具集、定义决策边界、设计回退机制。说白了就是给那个能力不确定的实习生配工作流程和权限边界。我做过一个自动化数据分析Agent最初设计让它自主选择分析路径结果它经常跑偏浪费大量Token和时间。后来我改成阶段式编排先让Agent做数据质量检查做完了必须停下来让我确认再进入下一阶段。这就是一种Harness的设计思路。在Agent实践中最关键的工程决策不是用什么框架而是怎么设计状态流转和错误恢复。框架只是工具核心逻辑永远是Agent干了一步结果是什么如果是成功下一步做什么如果是失败是重试、换方案还是标记人工介入这些如果不在代码层面明确定义Agent就会变成一只无头苍蝇。我建议从零开始学Agent的人先不要碰任何现成的Agent框架直接用模型API手动实现一个一次仅执行一步的循环记录每一步的输入输出观察模型是怎么决策的。当你手动实现过一遍理解了工具调用、结果回填、循环终止这三个关键环节之后再去用LangGraph或者开源的多Agent框架你会知道自己在干什么。直接上手框架的人往往只是学会了框架的API核心的编排思想完全没建立起来。2.3 RAG和数据管线让模型拥有外脑RAG检索增强生成是我个人认为AI工程里性价比最高的技术方向没有之一。因为大多数场景下你不能随便拿用户数据去微调模型而且微调一个模型动辄几千上万块钱效果还不一定可控。RAG的思维很简单模型不知道的知识我们检索出来拼进提示词里让它参考回答。但RAG的工程实现远不止向量数据库加召回这么简单。我把一个RAG系统拆开给你看你就知道水有多深了文档解析阶段你要处理PDF、Word、网页、表格等多种格式PDF里可能还有扫描图片需要OCR。段落切分阶段你不能简单按字符数切那样会切断语义。我试过用标题层级段落长度上限的混合切分策略效果比纯长度切分好很多。向量化阶段Embedding模型的选择直接决定召回质量通用Embedding在处理专业词汇时经常拉胯。存储阶段除了向量索引还要保留原始文本块、元数据、来源链接。召回阶段单纯向量检索不够要配合关键词检索做混合召回还要做重排序Rerank。生成阶段你需要设计引用来源的机制避免模型把多个文档的信息缝合成错误答案还无法溯源。这一套全链路做下来你会发现真正难的其实不是模型而是工程精度。每个环节都只有80分的水平叠在一起就是灾难。我当时在做企业知识库的时候最大的坑出现在切分策略上公司合同文档里大量条款互相引用简单按段落切分后模型经常只看到3.2条款的数字看不到对应的具体内容回答完全错误。后来我加了实体-条款关联检索才算基本解决。2.4 模型部署与评估工程化的最后一公里说实话很多从零学AI工程的人会忽略部署和评估满脑子想着做Agent、做RAG觉得部署是运维的事。但如果你做的是一个真正的产品部署环节的坑会把你所有的设计都击穿。我举个实际例子。有一个项目最初直接调用云端大模型API联调阶段一切正常但客户要求数据必须私有化部署于是我们必须在企业内部机房部署开源模型。这时候才发现需要考虑的东西完全不一样了选什么尺寸的模型能跟现有GPU资源匹配量化到多少位精度损失可接受推理框架用vLLM还是TGI并发请求怎么排队显存不足时怎么降级这些问题每一个都要踩一遍坑才能形成直觉。评估也一样是被低估的环节。很多团队上线AI功能完全靠人工看几条例子觉得还行这在To B场景绝对不够。我建议从项目第一天就开始积累评估用例集而且用例要持续补充把每次线上用户的bad case都沉淀进来。评估维度至少包括准确率信息是否正确、完整性有没有漏掉关键点、格式合规性、拒绝率不该答的是不是没答、Token消耗成本。把这些做成自动化的回归测试每次改提示词、换模型、调参数先跑一遍再决定是否上线。没有这套机制你根本不敢对线上系统做任何改动因为改了之后你不知道是变好了还是变坏了。3. 从零落地一个最小可行AI项目的完整搭建过程3.1 第一步选好技术栈和项目结构理论说多了容易飘我现在带你从零走一遍一个最小可行AI项目的搭建。选这个项目作为例子是文档问答机器人因为它覆盖了Prompt、RAG、Agent、评估、部署五个环节规模又适合做学习练习。技术栈方面我推荐走模块自研路线而不是全栈框架路线。什么意思用Python加FastAPI搭服务用OpenAI或DeepSeek的SDK调模型用chromadb或qdrant存向量自己写RAG流程和Agent循环而不是一上来就用LangChain全家桶。全栈框架的好处是省事坏处是你不知道每一步发生了什么出了问题无从排查。自研模块你会多写不少代码但这些代码本身就是最好的学习材料。项目结构我会这么组织doc-chatbot/ ├── app/ │ ├── main.py # FastAPI 入口 │ ├── config.py # 配置管理 │ ├── rag/ │ │ ├── ingest.py # 文档解析与写入 │ │ ├── retrieve.py # 检索模块 │ │ └── prompt.py # 提示词模板 │ ├── agent/ │ │ └── loop.py # Agent 简单循环 │ └── eval/ │ ├── cases.json # 评估用例 │ └── runner.py # 评估脚本 ├── data/ # 原始文档与向量库 └── tests/ # 单元测试这个结构看起来很简单但它强制你区分了检索和生成两个逻辑层这在你后续优化时非常关键。不要把RAG流程和提示词逻辑写在一起否则你很难定位到底是检索出了问题还是生成出了问题。3.2 第二步把大模型调用封装成可测试的模块很多新手写代码直接在业务逻辑里调用模型APISpread到处都是。这在AI工程里是大忌因为模型调用环节太容易变了——模型版本会变、参数要调、返回格式要解析。我建议所有模型调用都统一封装在一个模块里对外只暴露业务方法。封装的核心是两件事一是统一的返回结构把token消耗、延迟、返回内容一起打包返回方便记账和排查二是统一的错误处理模型API的限流错误、超时错误、内容审核错误都要有自己的异常类型这样业务层可以按需处理。参考一个简单的Python调用封装from dataclasses import dataclass from typing import Optional dataclass class ModelResponse: content: str prompt_tokens: int completion_tokens: int latency_ms: Optional[float] None class ModelClient: def complete( self, messages: list[dict], temperature: float 0.3, max_tokens: int 2048, ) - ModelResponse: # TODO: 在此处调用模型 SDK解析返回结果 # 统一记录日志、耗时、Token 消耗 pass # 进一步封装业务方法 def ask_document(self, query: str, context_docs: list[str]) - ModelResponse: # TODO: 组合提示词并调用 self.complete() # 这里放提示词模板逻辑 pass封装之后你的业务代码里就不会出现模型API的类型、超时重试逻辑这些细节。以后要换模型供应商只改这个模块业务层完全不受影响。这个习惯越早养成越好。3.3 第三步用评估用例驱动迭代这是我认为整个项目里最重要的一步但也是最容易被初学者跳过的一步。一个没有评估集的AI项目就是一个没法迭代的项目。你会陷入改了好像好一点又好像变差了的泥潭里。第一次写评估集不需要多复杂二十个用例就够了。覆盖下面这些类型有标准答案的事实型问题文档里确切存在的内容模型必须回答准确。需要跨段落整合的综合型问题需要模型把多处信息拼起来看是否逻辑一致。陷阱型问题文档里没有的内容模型应该拒绝回答不能编造。边界型问题关键词模糊但有一定指向性的问题考察模型的判断力。每个用例写上预期行为和关键词。评估脚本跑完之后生成一个表格展示每个案例的通过情况、Token消耗、延迟这样你每次改动之后可以对比。提示词每改一次、模型每换一版、RAG参数每调一次第一件事就是跑一遍评估集。我自己的经验是这个动作能把迭代效率提升至少三倍因为你不再靠感觉做判断了。3.4 第四步接入持续集成和监控小型项目也有必要做持续集成吗我的答案是有必要重点是轻量。不需要部署一套完整的CI系统重点做两件事一是评估集的自动化运行二是线上日志和Token消耗的监控。评估集自动化我用最朴素的方式实现本地一个脚本每次修改代码之后手动跑一遍如果你有GitHub仓库用GitHub Actions在每次push时自动跑。跑完输出一个JSON结果文件对比基线任何指标下降超过5%就不允许合并代码。监控方面重点跟踪三类指标请求成功率、平均延迟、Token消耗趋势。日志里要给每次请求记录一个request_id存下完整请求和响应快照这样线上出问题时你才能回溯到底是模型抽风还是提示词逻辑有漏洞。有一个真实案例让我印象很深线上机器人偶尔会回答一些莫名其妙的内容看表面完全感觉不到规律后来查日志发现是某个特定格式的用户输入触发了提示词注入通过完整快照才定位到问题。4. 最容易翻车的四个环节与排查思路4.1 上下文爆炸你以为在省Token其实在堆垃圾RAG项目最常见的性能杀手就是上下文越长、回答越差。很多新手以为把越多资料塞进提示词模型回答就越准确实际上恰恰相反。我先讲一个我在真实项目里的惨痛经历。当时做合同审查辅助工具为了追求全面每个问题都检索15段相关条文然后全放进提示词。结果模型经常把不同条款的条件混在一起输出的结论完全错误。后来我做了个实验把同样的问题只用4段高相关条文重新回答准确率反而提升了。这个现象背后的原因其实不复杂大模型在处理超长上下文时对中间部分的内容关注度会下降而且多个相似片段会互相干扰。工程上的解法就是先精后多。检索阶段可以多召回一些候选但进入提示词之前必须经过重排序只保留最相关的几个片段。同时要给上下文加结构标记让模型知道哪段是当前问题的直接依据、哪段是背景补充。4.2 幻觉和数据污染评估集的质量决定模型的天花板幻觉问题在RAG场景里几乎不可避免但有些幻觉是模型造成的有些不完全是。我遇到过很多次模型回答得很流畅、引用格式也很规范但内容跟检索到的资料完全对不上——这不是模型幻觉而是提示词设计缺陷模型根本没有强制要求它严格依据给定资料回答。我在提示词里固定加了一句话所有回答必须严格依据文档内容当文档中不存在所需信息时必须明确说明未找到相关内容。效果立竿见影。但要注意这不能根治幻觉只能把幻觉率降到一个可控范围。剩下来的幻觉要靠评估集持续跟踪特别是针对文档里没有的信息这一类用例要保证足够的覆盖量。另外一个容易忽略的问题是数据污染。如果你直接生产环境积累用户问题当作测试集测试集里可能包含标注人员的错误标注或者过时文档对应的答案。被污染的测试集会让你的评估指标变成数字游戏。我那段时间就被坑过明明线上bad case越来越多评估集的通过率却一直升后来发现是测试集里积累了太多跟当前文档版本不匹配的旧答案。定期清理和更新测试集是评估系统的日常工作之一。4.3 并发与限流本地能跑线上就挂很多人第一次部署AI应用时都经历过本地跑得好好的一上线就疯掉的情况。这里面除了GPU资源的问题最大的坑是上游API限流。如果你用的是云服务提供商的模型API它一定有限流策略而且限流不只是每秒钟多少请求还要看每分钟Token数。你的应用可能在低并发下完全正常但一旦超过某个阈值API开始给你报429错误如果你没有写重试和退避机制用户体验会断崖式下降。我的解法是做一层代理缓冲层。所有上游模型请求走统一的网关模块做一个简单的令牌桶限流器本地限制最大请求速率超过了就排队而不是直接打到上游。这样既有削峰效果又不会触发上游的限流惩罚。对响应时间要求高的场景还可以把常见问题的答案缓存起来做一个两级缓存策略——向量检索结果缓存、最终生成结果缓存能省下不少成本。4.4 版本管理Prompt、模型、数据三者谁能对齐AI工程里最隐蔽的坑之一就是线上运行的Prompt、模型版本、数据集三者不在同一个版本上。传统软件开发里代码有版本、数据库有迁移脚本依赖关系相对清晰。但AI应用多了一个动态资产维度——你的Prompt是存在代码里的还是存在数据库里的模型是固定版本还是跟随供应商更新数据文件更新后旧的索引有没有被清理我见过一个故障案例开发者更新了数据文件但忘了重新生成向量索引结果线上用户检索到的全是旧文档内容另一个案例是Prompt存在远程配置中心某个同事改了一个字的角色设定影响面是全部线上流量但完全没有走代码评审。我的经验是Prompt必须跟代码一起走版本控制放在仓库里有评审、有记录数据文件和向量索引每次更新都要打版本标记在系统里记录对应关系模型版本要显式配置禁止使用latest这种自动指向最新版本的配置方式。模型升级这件事必须走完整的测试流程先在评估集上跑一遍再灰度发布到线上。5. 学习路线与工具箱我实测有效的路径5.1 三阶段学习路线基础、实战、扩展如果你现在还是一个AI工程的初学者并且想沿着ai-engineering-from-scratch这条路系统地往下走我给你一个实践过的三阶段路线参考。第一阶段是把API用利索。花一到两周时间用原生SDK对接一个模型实现聊天、结构化输出、多轮对话、Function Call这几件事。每一件事都写一个小的Demo不需要复杂框架。目标是理解模型的基本能力边界和调用方式。第二阶段是做透一个RAG。选一个你熟悉的领域知识集自己搭一套RAG流程——从文档解析到向量化到检索到提示词组织再到评估集和指标统计。这一轮走完你已经跨过了大部分初学者过不去的门槛因为你亲手踩过检索不准、切分不当、幻觉控制这些具体的坑。第三阶段是探索Agent与多系统集成。当你具备了RAG和Prompt的系统能力之后再碰Agent就会从容很多。尝试给系统接工具调用、设计多步骤任务流程最后把应用部署上线加上监控和日志体系。至此你已经完成了从零到一再往后就是针对特定场景的深挖了。5.2 值得长期关注的方向走完基础路线之后有几个方向值得持续投入。第一个是评估体系现在大多数团队在评估上做的还很粗糙把模型输出的自动评估做扎实本身就是高价值的工程方向。第二个是多Agent协作模式多个角色Agent之间如何分工、如何共享信息、如何避免重复劳动这里面有大量工程问题没有被解决。第三个是成本优化同样的任务怎么通过模型选型、缓存策略、上下文压缩来把Token成本降一半这在大规模应用语境下是个极其实际的课题。还有一个心态上的建议AI工程这个领域变化很快几乎每个月都有新东西冒出来你不可能什么都学。真正重要的是抓住那些变换速度慢的知识——上下文管理机制、评估方法论、系统设计原则、数据结构思维这些才是地基。新框架、新工具只是在地基上换家具位置变了但地基不会塌。我在实际做项目的过程中最大的体会是AI工程的能力不是学出来的是拿真实项目喂出来的。你接的第一个单子哪怕很小只要你完整地走完了需求分析、方案设计、开发、上线、复盘这五个环节你学到的东西会比看十个小时教程多得多。从第一个丑陋的项目开始然后在下一次迭代里让它变得不那么丑这就是工程能力成长的本来路径。
AI工程从零到一：Prompt、RAG、Agent与部署评估实战
1. 先认清定位AI工程不是调API也不是背概念1.1 为什么这个仓库值得从零开始说实话我最初看到ai-engineering-from-scratch这个项目名时第一反应是又一个学习清单仓库。这类仓库在GitHub上太多了基本都是把论文、教程、工具链接一股脑扔进去标个上千星然后大家收藏完就再也不看。但仔细翻了翻这个项目的内容组织方式我发现它跟那些收藏夹型仓库有本质区别——它把从零开始当作一条真正的学习主线而不是资料聚合。我见过太多人学AI工程的方式先买一堆课程把Transformer、注意力机制、反向传播背得滚瓜烂熟然后打开IDE发现自己连一个完整项目都搭不起来。反过来也见过另一批人一上来就死磕LangChain源码结果连提示词的基础规则都没搞明白做出来的Agent一跑就崩。这两种极端我都有过切身体会。早两年我做传统后端开发自认为工程化能力还行结果第一次碰大模型应用时写的代码跟玩具一样——没有版本管理、没有测试、没有评估模型换一个版本整个输出就全变了。那时候我才意识到AI工程不是会用大模型API而是把模型、数据、评估、部署、监控当成一个系统工程来设计。这个仓库的定位正好打中这个痛点它不教你数学推导也不教你背诵概念它教你如何用工程手段把AI能力稳定地落地。1.2 AI工程师和算法工程师的边界在哪里很多新手分不清AI工程师、算法工程师、数据工程师这三个角色的区别这个认知偏差会直接影响你学习路径的设计。算法工程师的核心是发明或改进模型——搞新的网络结构、调新的训练策略、刷新的指标他们围绕模型本身工作。而AI工程师更准确地说是AI应用工程师核心是把现有的大模型能力封装成稳定的产品功能工作重心在提示词编排、Agent逻辑、上下文管理、评估迭代、部署监控这些环节上。举个简单例子算法工程师会研究如何让模型在数学推理上表现更好可能涉及微调或蒸馏AI工程师则是在模型已经具备数学推理能力的前提下设计一套提示词框架和工具调用链让模型能够稳定地完成一道多步应用题并在出错时能自我纠错或转人工。所以你在学ai-engineering-from-scratch这类项目时要带着产品思维去学而不是研究思维。你的目标不是发明新模型而是把现有模型用到极致。这并不意味着算法知识不重要——恰恰相反理解模型的能力边界、上下文窗口机制、温度参数对输出分布的影响能帮你大幅减少调试时间。但学习的优先级必须是先会工程再补理论而不是反过来。从实战角度讲我推荐的认知模型是这样的把大模型当作一个能力不确定的实习生把AI工程当作一套管理这个实习生的制度体系。提示词是你给他的任务说明书Agent框架是你在旁边配的监工RAG是你给他的资料库评估用例是你的验收标准日志和监控是你看他每天工作表现的考勤表。这套制度设计得好实习生就能稳定产出设计得不好他今天超常发挥明天直接摆烂。2. 知识版图Prompt、Agent、RAG与模型部署四条主线2.1 Prompt Engineering最基础也最容易被低估很多人觉得Prompt Engineering只是写指令这大概是AI工程领域最大的误解。真正在生产环境里跑过的人都知道提示词是系统设计的一部分它跟代码一样需要版本管理、需要测试、需要遵循设计模式。我举个例子你就明白了。早期我做客服问答机器人最初的提示词写的是请回答用户的问题后来发现模型经常答非所问而且有时候会编造一些不存在的售后政策。后来我把提示词拆成了四个部分系统角色设定、背景知识库引用、回答规则约束、输出格式要求并且建立了十几个典型的边界场景测试用例每次改动提示词都要跑一遍这些用例。这时候提示词就不是一段话了而是一份像代码一样可维护、可回滚、可评审的工程资产。具体到实践层面我总结了几个关键点。第一外部知识必须先于问题注入也就是说提示词里要先放检索到的文档再放用户问题不然模型会优先响应后文中的指令第二负面约束要具体化不要只写不要胡说八道而要说当检索到的资料不包含相关信息时必须回答当前没有查到该问题的资料第三要求模型先推理再回答通过Lets think step by step这类引导词虽然老套但在复杂推理任务中确实能降低错误率代价是Token消耗增加需要评估收益是否能覆盖成本。还需要注意的一点是Prompt本身存在脆弱性问题。你可能用几分钟写的一个不错的提示词在模型换版本之后突然失效。GPT-4时代好用的提示词模式可能在新的模型上表现反而变差。所以Prompt必须要做版本管理并且每次模型供应商更新版本之后都要拿同样的测试集跑一遍回归测试——这不是可选操作是必须的操作。2.2 Agent与Harness Engineering从单次调用到自主工作流Agent是这两年AI工程最热的方向但也是概念最混乱的方向。从我实际做项目的经验来看Agent的本质就是给模型加上了工具调用能力然后在一定约束下让模型自主决策下一步动作。听起来很酷但工程上的复杂度会指数级上升。先说Harness Engineering这个概念最近圈子里提得很多。它指的是为Agent设计一套约束和支撑系统的工程实践——包括限定工具集、定义决策边界、设计回退机制。说白了就是给那个能力不确定的实习生配工作流程和权限边界。我做过一个自动化数据分析Agent最初设计让它自主选择分析路径结果它经常跑偏浪费大量Token和时间。后来我改成阶段式编排先让Agent做数据质量检查做完了必须停下来让我确认再进入下一阶段。这就是一种Harness的设计思路。在Agent实践中最关键的工程决策不是用什么框架而是怎么设计状态流转和错误恢复。框架只是工具核心逻辑永远是Agent干了一步结果是什么如果是成功下一步做什么如果是失败是重试、换方案还是标记人工介入这些如果不在代码层面明确定义Agent就会变成一只无头苍蝇。我建议从零开始学Agent的人先不要碰任何现成的Agent框架直接用模型API手动实现一个一次仅执行一步的循环记录每一步的输入输出观察模型是怎么决策的。当你手动实现过一遍理解了工具调用、结果回填、循环终止这三个关键环节之后再去用LangGraph或者开源的多Agent框架你会知道自己在干什么。直接上手框架的人往往只是学会了框架的API核心的编排思想完全没建立起来。2.3 RAG和数据管线让模型拥有外脑RAG检索增强生成是我个人认为AI工程里性价比最高的技术方向没有之一。因为大多数场景下你不能随便拿用户数据去微调模型而且微调一个模型动辄几千上万块钱效果还不一定可控。RAG的思维很简单模型不知道的知识我们检索出来拼进提示词里让它参考回答。但RAG的工程实现远不止向量数据库加召回这么简单。我把一个RAG系统拆开给你看你就知道水有多深了文档解析阶段你要处理PDF、Word、网页、表格等多种格式PDF里可能还有扫描图片需要OCR。段落切分阶段你不能简单按字符数切那样会切断语义。我试过用标题层级段落长度上限的混合切分策略效果比纯长度切分好很多。向量化阶段Embedding模型的选择直接决定召回质量通用Embedding在处理专业词汇时经常拉胯。存储阶段除了向量索引还要保留原始文本块、元数据、来源链接。召回阶段单纯向量检索不够要配合关键词检索做混合召回还要做重排序Rerank。生成阶段你需要设计引用来源的机制避免模型把多个文档的信息缝合成错误答案还无法溯源。这一套全链路做下来你会发现真正难的其实不是模型而是工程精度。每个环节都只有80分的水平叠在一起就是灾难。我当时在做企业知识库的时候最大的坑出现在切分策略上公司合同文档里大量条款互相引用简单按段落切分后模型经常只看到3.2条款的数字看不到对应的具体内容回答完全错误。后来我加了实体-条款关联检索才算基本解决。2.4 模型部署与评估工程化的最后一公里说实话很多从零学AI工程的人会忽略部署和评估满脑子想着做Agent、做RAG觉得部署是运维的事。但如果你做的是一个真正的产品部署环节的坑会把你所有的设计都击穿。我举个实际例子。有一个项目最初直接调用云端大模型API联调阶段一切正常但客户要求数据必须私有化部署于是我们必须在企业内部机房部署开源模型。这时候才发现需要考虑的东西完全不一样了选什么尺寸的模型能跟现有GPU资源匹配量化到多少位精度损失可接受推理框架用vLLM还是TGI并发请求怎么排队显存不足时怎么降级这些问题每一个都要踩一遍坑才能形成直觉。评估也一样是被低估的环节。很多团队上线AI功能完全靠人工看几条例子觉得还行这在To B场景绝对不够。我建议从项目第一天就开始积累评估用例集而且用例要持续补充把每次线上用户的bad case都沉淀进来。评估维度至少包括准确率信息是否正确、完整性有没有漏掉关键点、格式合规性、拒绝率不该答的是不是没答、Token消耗成本。把这些做成自动化的回归测试每次改提示词、换模型、调参数先跑一遍再决定是否上线。没有这套机制你根本不敢对线上系统做任何改动因为改了之后你不知道是变好了还是变坏了。3. 从零落地一个最小可行AI项目的完整搭建过程3.1 第一步选好技术栈和项目结构理论说多了容易飘我现在带你从零走一遍一个最小可行AI项目的搭建。选这个项目作为例子是文档问答机器人因为它覆盖了Prompt、RAG、Agent、评估、部署五个环节规模又适合做学习练习。技术栈方面我推荐走模块自研路线而不是全栈框架路线。什么意思用Python加FastAPI搭服务用OpenAI或DeepSeek的SDK调模型用chromadb或qdrant存向量自己写RAG流程和Agent循环而不是一上来就用LangChain全家桶。全栈框架的好处是省事坏处是你不知道每一步发生了什么出了问题无从排查。自研模块你会多写不少代码但这些代码本身就是最好的学习材料。项目结构我会这么组织doc-chatbot/ ├── app/ │ ├── main.py # FastAPI 入口 │ ├── config.py # 配置管理 │ ├── rag/ │ │ ├── ingest.py # 文档解析与写入 │ │ ├── retrieve.py # 检索模块 │ │ └── prompt.py # 提示词模板 │ ├── agent/ │ │ └── loop.py # Agent 简单循环 │ └── eval/ │ ├── cases.json # 评估用例 │ └── runner.py # 评估脚本 ├── data/ # 原始文档与向量库 └── tests/ # 单元测试这个结构看起来很简单但它强制你区分了检索和生成两个逻辑层这在你后续优化时非常关键。不要把RAG流程和提示词逻辑写在一起否则你很难定位到底是检索出了问题还是生成出了问题。3.2 第二步把大模型调用封装成可测试的模块很多新手写代码直接在业务逻辑里调用模型APISpread到处都是。这在AI工程里是大忌因为模型调用环节太容易变了——模型版本会变、参数要调、返回格式要解析。我建议所有模型调用都统一封装在一个模块里对外只暴露业务方法。封装的核心是两件事一是统一的返回结构把token消耗、延迟、返回内容一起打包返回方便记账和排查二是统一的错误处理模型API的限流错误、超时错误、内容审核错误都要有自己的异常类型这样业务层可以按需处理。参考一个简单的Python调用封装from dataclasses import dataclass from typing import Optional dataclass class ModelResponse: content: str prompt_tokens: int completion_tokens: int latency_ms: Optional[float] None class ModelClient: def complete( self, messages: list[dict], temperature: float 0.3, max_tokens: int 2048, ) - ModelResponse: # TODO: 在此处调用模型 SDK解析返回结果 # 统一记录日志、耗时、Token 消耗 pass # 进一步封装业务方法 def ask_document(self, query: str, context_docs: list[str]) - ModelResponse: # TODO: 组合提示词并调用 self.complete() # 这里放提示词模板逻辑 pass封装之后你的业务代码里就不会出现模型API的类型、超时重试逻辑这些细节。以后要换模型供应商只改这个模块业务层完全不受影响。这个习惯越早养成越好。3.3 第三步用评估用例驱动迭代这是我认为整个项目里最重要的一步但也是最容易被初学者跳过的一步。一个没有评估集的AI项目就是一个没法迭代的项目。你会陷入改了好像好一点又好像变差了的泥潭里。第一次写评估集不需要多复杂二十个用例就够了。覆盖下面这些类型有标准答案的事实型问题文档里确切存在的内容模型必须回答准确。需要跨段落整合的综合型问题需要模型把多处信息拼起来看是否逻辑一致。陷阱型问题文档里没有的内容模型应该拒绝回答不能编造。边界型问题关键词模糊但有一定指向性的问题考察模型的判断力。每个用例写上预期行为和关键词。评估脚本跑完之后生成一个表格展示每个案例的通过情况、Token消耗、延迟这样你每次改动之后可以对比。提示词每改一次、模型每换一版、RAG参数每调一次第一件事就是跑一遍评估集。我自己的经验是这个动作能把迭代效率提升至少三倍因为你不再靠感觉做判断了。3.4 第四步接入持续集成和监控小型项目也有必要做持续集成吗我的答案是有必要重点是轻量。不需要部署一套完整的CI系统重点做两件事一是评估集的自动化运行二是线上日志和Token消耗的监控。评估集自动化我用最朴素的方式实现本地一个脚本每次修改代码之后手动跑一遍如果你有GitHub仓库用GitHub Actions在每次push时自动跑。跑完输出一个JSON结果文件对比基线任何指标下降超过5%就不允许合并代码。监控方面重点跟踪三类指标请求成功率、平均延迟、Token消耗趋势。日志里要给每次请求记录一个request_id存下完整请求和响应快照这样线上出问题时你才能回溯到底是模型抽风还是提示词逻辑有漏洞。有一个真实案例让我印象很深线上机器人偶尔会回答一些莫名其妙的内容看表面完全感觉不到规律后来查日志发现是某个特定格式的用户输入触发了提示词注入通过完整快照才定位到问题。4. 最容易翻车的四个环节与排查思路4.1 上下文爆炸你以为在省Token其实在堆垃圾RAG项目最常见的性能杀手就是上下文越长、回答越差。很多新手以为把越多资料塞进提示词模型回答就越准确实际上恰恰相反。我先讲一个我在真实项目里的惨痛经历。当时做合同审查辅助工具为了追求全面每个问题都检索15段相关条文然后全放进提示词。结果模型经常把不同条款的条件混在一起输出的结论完全错误。后来我做了个实验把同样的问题只用4段高相关条文重新回答准确率反而提升了。这个现象背后的原因其实不复杂大模型在处理超长上下文时对中间部分的内容关注度会下降而且多个相似片段会互相干扰。工程上的解法就是先精后多。检索阶段可以多召回一些候选但进入提示词之前必须经过重排序只保留最相关的几个片段。同时要给上下文加结构标记让模型知道哪段是当前问题的直接依据、哪段是背景补充。4.2 幻觉和数据污染评估集的质量决定模型的天花板幻觉问题在RAG场景里几乎不可避免但有些幻觉是模型造成的有些不完全是。我遇到过很多次模型回答得很流畅、引用格式也很规范但内容跟检索到的资料完全对不上——这不是模型幻觉而是提示词设计缺陷模型根本没有强制要求它严格依据给定资料回答。我在提示词里固定加了一句话所有回答必须严格依据文档内容当文档中不存在所需信息时必须明确说明未找到相关内容。效果立竿见影。但要注意这不能根治幻觉只能把幻觉率降到一个可控范围。剩下来的幻觉要靠评估集持续跟踪特别是针对文档里没有的信息这一类用例要保证足够的覆盖量。另外一个容易忽略的问题是数据污染。如果你直接生产环境积累用户问题当作测试集测试集里可能包含标注人员的错误标注或者过时文档对应的答案。被污染的测试集会让你的评估指标变成数字游戏。我那段时间就被坑过明明线上bad case越来越多评估集的通过率却一直升后来发现是测试集里积累了太多跟当前文档版本不匹配的旧答案。定期清理和更新测试集是评估系统的日常工作之一。4.3 并发与限流本地能跑线上就挂很多人第一次部署AI应用时都经历过本地跑得好好的一上线就疯掉的情况。这里面除了GPU资源的问题最大的坑是上游API限流。如果你用的是云服务提供商的模型API它一定有限流策略而且限流不只是每秒钟多少请求还要看每分钟Token数。你的应用可能在低并发下完全正常但一旦超过某个阈值API开始给你报429错误如果你没有写重试和退避机制用户体验会断崖式下降。我的解法是做一层代理缓冲层。所有上游模型请求走统一的网关模块做一个简单的令牌桶限流器本地限制最大请求速率超过了就排队而不是直接打到上游。这样既有削峰效果又不会触发上游的限流惩罚。对响应时间要求高的场景还可以把常见问题的答案缓存起来做一个两级缓存策略——向量检索结果缓存、最终生成结果缓存能省下不少成本。4.4 版本管理Prompt、模型、数据三者谁能对齐AI工程里最隐蔽的坑之一就是线上运行的Prompt、模型版本、数据集三者不在同一个版本上。传统软件开发里代码有版本、数据库有迁移脚本依赖关系相对清晰。但AI应用多了一个动态资产维度——你的Prompt是存在代码里的还是存在数据库里的模型是固定版本还是跟随供应商更新数据文件更新后旧的索引有没有被清理我见过一个故障案例开发者更新了数据文件但忘了重新生成向量索引结果线上用户检索到的全是旧文档内容另一个案例是Prompt存在远程配置中心某个同事改了一个字的角色设定影响面是全部线上流量但完全没有走代码评审。我的经验是Prompt必须跟代码一起走版本控制放在仓库里有评审、有记录数据文件和向量索引每次更新都要打版本标记在系统里记录对应关系模型版本要显式配置禁止使用latest这种自动指向最新版本的配置方式。模型升级这件事必须走完整的测试流程先在评估集上跑一遍再灰度发布到线上。5. 学习路线与工具箱我实测有效的路径5.1 三阶段学习路线基础、实战、扩展如果你现在还是一个AI工程的初学者并且想沿着ai-engineering-from-scratch这条路系统地往下走我给你一个实践过的三阶段路线参考。第一阶段是把API用利索。花一到两周时间用原生SDK对接一个模型实现聊天、结构化输出、多轮对话、Function Call这几件事。每一件事都写一个小的Demo不需要复杂框架。目标是理解模型的基本能力边界和调用方式。第二阶段是做透一个RAG。选一个你熟悉的领域知识集自己搭一套RAG流程——从文档解析到向量化到检索到提示词组织再到评估集和指标统计。这一轮走完你已经跨过了大部分初学者过不去的门槛因为你亲手踩过检索不准、切分不当、幻觉控制这些具体的坑。第三阶段是探索Agent与多系统集成。当你具备了RAG和Prompt的系统能力之后再碰Agent就会从容很多。尝试给系统接工具调用、设计多步骤任务流程最后把应用部署上线加上监控和日志体系。至此你已经完成了从零到一再往后就是针对特定场景的深挖了。5.2 值得长期关注的方向走完基础路线之后有几个方向值得持续投入。第一个是评估体系现在大多数团队在评估上做的还很粗糙把模型输出的自动评估做扎实本身就是高价值的工程方向。第二个是多Agent协作模式多个角色Agent之间如何分工、如何共享信息、如何避免重复劳动这里面有大量工程问题没有被解决。第三个是成本优化同样的任务怎么通过模型选型、缓存策略、上下文压缩来把Token成本降一半这在大规模应用语境下是个极其实际的课题。还有一个心态上的建议AI工程这个领域变化很快几乎每个月都有新东西冒出来你不可能什么都学。真正重要的是抓住那些变换速度慢的知识——上下文管理机制、评估方法论、系统设计原则、数据结构思维这些才是地基。新框架、新工具只是在地基上换家具位置变了但地基不会塌。我在实际做项目的过程中最大的体会是AI工程的能力不是学出来的是拿真实项目喂出来的。你接的第一个单子哪怕很小只要你完整地走完了需求分析、方案设计、开发、上线、复盘这五个环节你学到的东西会比看十个小时教程多得多。从第一个丑陋的项目开始然后在下一次迭代里让它变得不那么丑这就是工程能力成长的本来路径。
