AI工程落地实践笔记：从零搭建智能系统全指南

今年是我做AI工程落地的第四个年头从最早拿着模型接口拼出能跑的Demo到后来在公司里搭完整的知识库问答系统、多Agent协作框架最大的感受是AI工程的难点从来不在模型本身而在模型之外那套工程体系。如果你正打算从零开始AI工程或者想把团队从传统软件开发转向AI原生研发这篇文章就是我实际折腾下来的完整笔记把思路、技术选型、实操步骤和踩过的坑都拆开讲一遍。内容会覆盖整体设计思路、工程化基建、Prompt Engineering的实战方法、Agent的搭建路径以及端到端项目的评估与排查适合刚入门的学习者也适合正在做技术方案的人参考。1. 从零开始AI工程先想清楚这几件事1.1 一个AI工程项目的真实解剖经常有人问我从零开始AI工程到底该先学什么。我的回答通常是先别急着看模型先做一个真实项目的解剖。一个完整的AI工程项目拆开来看无非是几层数据层负责把原始资料变成模型能理解和检索的高质量语料模型层负责处理你定义的任务比如文本生成、分类、抽取、代码补全应用层负责把模型能力封装成稳定的接口承接业务流程最后是评估与运维层负责回答模型答得好不好系统崩了怎么恢复这些现实问题。这四个层次里最容易被新手忽略的是数据层和评估层。很多人拿到一个开源模型就急着调Prompt结果发现效果不稳定回头才发现是输入数据本身有问题或者压根没有一套评估标准来衡量改动好坏。AI工程和传统软件工程最大的差异就在这里传统开发的核心是确定性逻辑AI工程的核心是管理不确定性。你没法像测试一个纯函数一样测试一个对话系统所有质量保障都依赖数据和评估策略。从零开始的意思就是把这四层一层一层搭起来而不是跳过地基直接盖屋顶。我在第一年踩过最深的坑就是把90%的时间花在模型选型和Prompt微调上结果上层应用一接入真实业务数据格式对不上、上下文长度爆掉、接口响应超时全暴露了。后来我把精力重新分配到数据清洗、评估集建设和调用链路的稳定性上项目才真正跑起来。1.2 技术栈选型别被热门技术绑架技术选型是从零开始AI工程里决策成本最高的一环。我先说结论初期阶段能用成熟API解决的不要自己部署模型能用标准框架解决的不要重复造轮子。我自己早期的技术栈是OpenAI风格的大模型API加上开源的向量数据库后来逐步演进到支持国内多个模型厂商的调用层、更灵活的Agent调度框架。做选型时我建议大家把三个维度拉出来对表成本、可控性和团队能力。成本不只是API价格还包括开发调试的时间成本可控性指的是数据隐私、模型升级影响、厂商依赖风险团队能力则是你现有团队能不能驾驭这套系统。如果你是一个三人小团队做内部工具直接调模型API大概率是最优解如果做B端产品对数据隔离有硬要求可能就得考虑私有化部署或使用可私有化部署的开源模型。还要想清楚的是框架选型。现在AI工程的框架已经非常丰富有做Agent编排的有做RAG管线的有做评估的。我建议起步时别一次引入太多抽象层先从最简单的直接调用开始把业务流程跑通再逐步换成框架来治理复杂度。我自己见过太多团队引入了一大堆框架结果连简单的消息传递都折腾不明白。工程化的本质是让事情可控不是为了工具而堆工具。2. 工程化基建把地基打扎实2.1 环境与项目结构从零开始的第一步AI工程的第一步不是写模型调用的代码而是搭一个可复现的开发环境。这里的核心诉求就一个换一台电脑、换一个同事代码还能一键跑起来。我建议用虚拟环境管理依赖把模型相关的依赖、数据处理相关的依赖分离开同时把配置文件独立出来密钥、模型名称、温度参数这些全部走环境变量不要硬编码在代码里。我习惯的项目结构大致是这样的project/ ├── configs/ # 配置项模型、参数、路径 ├── data/ │ ├── raw/ # 原始数据 │ ├── processed/ # 清洗后的数据 │ └── eval/ # 评估集 ├── src/ │ ├── data_pipeline/ # 数据清洗与转换 │ ├── model/ # 模型调用与推理逻辑 │ ├── agent/ # Agent 编排逻辑 │ ├── evaluation/ # 评估脚本与指标 │ └── api/ # 对外服务接口 ├── tests/ └── requirements.txt这个结构的重点是边界清晰数据处理、模型调用、Agent逻辑、评估脚本互不渗透。我做过的几个项目里凡是代码开始乱成一锅粥的几乎都是因为有人把业务逻辑直接写在了模型调用文件里。保持分区的好处是后续替换模型、调整检索策略、升级Agent框架时你只需要动其中一块其他模块完全不受影响。还有一点容易被忽视就是依赖锁定。AI生态的依赖更新极快今天能用的一套版本组合过两周可能就冲突了。用锁定文件把依赖版本固定下来再配合CI做自动化测试能省下大量复现问题的时间。这套习惯我从传统开发带过来在AI项目里收益极明显。2.2 数据准备AI工程真正的分水岭很多人把数据准备理解成把文件读进来喂给模型这是大错特错。数据层决定AI系统的上限模型只是把这个上限兑现出来。我在几个知识库项目中反复验证过这个结论同样一个模型喂给脏乱差的数据回答效果可以用灾难来形容喂给结构清晰、经过标注的数据效果直接提升一档。从零开始处理数据我会按这几步来先做格式统一把PDF、Word、网页、数据库导出的各种格式全部转成统一的纯文本或Markdown格式然后做内容清洗去掉无用的页眉页脚、水印、导航链接处理乱码和特殊字符接着做数据分割按语义完整性和长度限制切成合适的文本块同时保留段落结构最后做向量化索引把文本块转成向量存入向量数据库并建立元数据映射。数据分割这件事值得单独说说。文本块的粒度直接影响检索效果切得太粗检索出来的片段包含大量无关内容还容易超过模型的上下文限制切得太细又会导致语义不完整检索结果支离破碎。我常用的策略是先按标题和段落结构做规则切分再对超过长度上限的块做二次切割块与块之间保留少量重叠避免语义断在边界上。还有一个常被忽略的关键动作为每条数据打上元数据标签比如来源、时间、章节路径、权限级别。元数据在后续做权限过滤、时间排序、引用溯源时特别有用。等系统上线后你会发现之前花在元数据上的时间全都值回来了。3. Prompt Engineering实战和模型有效对话3.1 从“热情提问”到“结构化对话”Prompt Engineering作为AI工程的核心技能之一本质是把人类的模糊意图转译成模型能精确执行的指令。我在带新人时观察到最常见的误区是把模型当搜索引擎想什么就说什么结果输出天马行空。真正的工程化Prompt讲究的是结构化表达。比如你问模型帮我写个方案不如给它这样一个结构化指令你是一名资深的解决方案架构师。 任务为[某场景]设计一份技术方案。 要求 1. 方案包含背景、架构设计、实施步骤、风险评估四个部分 2. 架构设计需要画出模块间的关系并用文字详细描述 3. 实施步骤按阶段划分每个阶段给出可交付物 4. 风险部分需要说明可能遇到的问题和应对预案。 约束 - 篇幅控制在800字以内 - 使用简体中文 - 技术方案需具体避免空洞描述。对比一下你就会发现结构化Prompt的输出质量稳定得多。我的经验是一个合格的工程化Prompt至少包含四个要素角色定义、任务描述、输出约束、补充示例。角色定义让模型切换到一个特定的语境任务描述要具体可执行输出约束要明确格式、长度、语言补充示例则是用few-shot的方式给模型打样这对格式类任务尤其有效。3.2 让模型稳定输出的三个技巧Prompt调优是一个迭代过程不能指望一次写好。我总结了三个对稳定性帮助最大的技巧第一个技巧是要求结构化输出。现在主流大模型基本都支持JSON模式或函数调用你可以明确要求模型只输出JSON不要输出任何其他内容然后在项目代码里用解析器把返回结果转成对象。这个习惯能让下游处理变得极其可靠也便于自动化评估。如果你还在靠正则解析自由文本赶紧改成结构化输出性价比极高。第二个技巧是善用上下文里的示例。在Prompt里塞两三个配对示例模型输出几乎不会跑偏。比如要模型做意图分类就给它几个输入-输出的黄金样例。这比你在提示词里反复强调你要准确有用得多。示例本质上就是在给模型划定答案分布。第三个技巧是合理设置生成参数。温度参数控制随机性需要发散创意的任务温度调高一些需要精确执行的任务温度调低甚至接近0。最大生成长度也要主动控制不然遇到长文本任务模型会在结尾开始重复废话。这些参数应该写进配置文件而不是每次调用时临时传值方便统一调整和对比实验。3.3 从Prompt到Prompt管理当项目里的Prompt越来越多就会遇到新的工程问题提示词该存在哪里怎么版本管理怎么灰度上线。我给自己的项目设计了一套简单的Prompt管理方案所有Prompt都作为独立的模板文件存下来模板内部定义变量占位符运行时动态填充变更时走代码仓库的评审和记录流程。Prompt管理做到一定阶段你会发现它和代码管理越来越像。模板文件要写注释说明用途变更要记录原因和影响范围要有版本号。这个过程中积累的Prompt测试集作用相当于传统开发的单元测试每次改Prompt就跑一遍回归。我在团队里推行这个习惯之后Prompt改动导致的效果回退明显少了很多。4. 从Prompt到Agent让AI真正自己干活4.1 Agent的基本架构工具、规划与循环如果说Prompt Engineering解决的是单次问答的准确度那么Agent解决的就是多步骤任务的自动化完成能力。Agent的本质是让模型在循环里工作模型不再只回答一个问题而是不断分析当前状态、决定下一步动作、调用外部工具、再根据结果继续推进直到任务完成。我理解的Agent核心架构有三个部分工具集、规划器、状态管理。工具集是Agent可以调用的外部能力比如搜索、计算器、数据库查询、API请求规划器是模型本身负责决定下一步该执行哪个工具状态管理则记录整个任务执行过程中上下文和中间结果。很多入门者一上来就搭多Agent协同系统这是典型的步子迈太大。我建议从最简单的单Agent加工具调用开始给模型定义若干个工具函数让它学会在对话过程中通过函数调用接口来触达外部系统。跑通这个闭环之后再去想如何拆分多个Agent角色、如何协调它们之间的通信。4.2 Harness Engineering与Loop Engineering的现实意义在Agent工程化实践里有两个概念逐渐成为主流一个是Harness Engineering指搭建Agent运行时的整体框架包括工具注册、权限管控、调用链追踪、失败重试另一个是Loop Engineering指构建Agent的核心决策循环让模型在观察-思考-行动-再观察的闭环中稳定运转。你把这两个方向做扎实Agent项目就成功了一大半。我在真实项目里遇到过的最经典的问题是Agent在循环里卡死反复调用同一个工具拿不到进展或者跑出几十轮不必要的调用钱和时间都烧掉了。解决办法是给循环加上各种护栏比如最大迭代次数、单次工具调用的超时时间、对重复操作的自动终止逻辑。这些护栏工程细节才是Agent真正落地的关键。从工程管理的视角来看Agent运行时的可观测性极其重要。我在搭建Agent项目的时侯会为每轮决策和工具调用加上日志埋点包括模型的思考内容、调用参数、返回结果、耗时和成本。没有这套观测体系Agent出问题时你只能干瞪眼完全不知道是模型决策错了还是工具返回出错了。4.3 多Agent协作的现实场景多Agent协作是我目前最看好的一个方向但也是最容易失控的领域。我的实践经验是只有当任务天然具有多人协作特征时才值得拆成多Agent。比如一份技术方案文档可以安排一个分析Agent负责调研背景一个架构Agent负责设计技术方案一个评审Agent负责找出方案漏洞这种分工切合实际工作流。但多Agent之间的通信协议、上下文传递、任务分配机制都比单Agent复杂得多。我踩过的坑包括Agent之间传递上下文时信息丢了一部分造成理解偏差多个Agent同时修改同一份数据而产生冲突Agent之间互相踢皮球把任务推来推去就是不结束。这些问题没有万能药只能靠设计清晰的协作协议和严格的终止条件。一个务实的建议是先让单Agent处理80%的简单任务只把那些确实需要多视角的任务交给多Agent协同。这是我的核心原则——复杂度要配得上任务的收益而不是为了炫技而引入复杂度。5. 端到端项目实操从零搭建一个RAG问答系统5.1 场景定义与方案设计理论知识说多了还是得上手实操。我以一个最常见的场景为例搭建一个基于私有文档的问答系统帮你把大量PDF和网页内容变成可以对话的知识库。这个项目的初心是解决资料太多找不到答案的问题这也是RAG架构最典型的应用场景。方案设计遵循了前面说的分层原则数据层做文档解析和切块向量化存入向量数据库检索层负责把用户问题转成向量在库里做相似度检索取回相关文本块生成层把用户问题和检索结果拼装成Prompt调大模型生成答案。我选型时用了一个开源向量数据库存储向量配合一个开源嵌入模型做文本转向量生成模型则选择通用的大模型API。在动手写代码之前我还做了个额外动作整理了一份预期问答清单把真实业务里最常问到的问题列出来。这份清单后来变成了评估集的基础是我整个项目里投入产出比最高的一个决定。没有评估目标的时候你做任何优化都像在摸黑走路。5.2 核心代码实现与分析先来看数据管道的代码这是一个最简化的数据切块和向量化流程只保留了核心逻辑方便理解from langchain.text_splitter import RecursiveCharacterTextSplitter # 按标题层级切分再对长块做二次切割 text_splitter RecursiveCharacterTextSplitter( chunk_size600, chunk_overlap100, separators[\n\n, \n, 。, , ], ) chunks text_splitter.split_text(cleaned_text) print(f切分后共 {len(chunks)} 个文本块)递归字符切分器是我在实际项目里用得最多的方式它会优先在段落边界切段落太长就继续往里找更小的分隔符。重叠区域设为100个字符左右能保证跨块语义不丢。切分完成后每个文本块交给嵌入模型转成向量存入向量数据库同时记录文本块对应的来源文档和章节信息。这一步看似平淡无奇实际操作中值得反复调整的是切块大小。太大检索不精准太小语义不连贯必须根据你的文档类型实测调参。检索部分的核心逻辑是向量相似度检索def search_documents(query: str, top_k: int 5): query_embedding embedding_model.embed_query(query) results vector_store.search( embeddingquery_embedding, top_ktop_k, score_threshold0.75, # 过滤低相关结果 ) return results这里的score_threshold参数很关键它决定了检索结果相关性的底线。阈值设低了返回一堆不相关内容影响生成质量设高了就召回不足答案缺失。我在实践中会先用一个开发集测试不同阈值下的召回率和准确率挑一个平衡点。我个人倾向于在0.7到0.8之间试探不同嵌入模型差异很大没有通用值。生成层的Prompt设计直接决定了最终回答质量。把检索到的文本块按格式拼装进Prompt注明来源并约束模型的回答行为prompt f请基于以下参考片段回答用户问题。 要求只引用片段中的信息不要编造如果片段信息不足明确回答“根据现有资料无法回答”。 参考片段 {context} 用户问题{question} 这里的不要编造不是心理安慰而是在给模型划定行为的边界。RAG系统最怕生成层自由发挥把检索到的正确信息淹没在自己脑补出来的细节里。加上这段约束之后幻觉问题会大幅减少。5.3 调试过程与工程细节代码写完只是开始调试和联调才是大头。我在联调时刻意观察了几个核心指标检索Hit率用户的问题是否真的能在库里找到对应内容、回答引用准确率答案里的每一句话能否追溯到参考片段、端到端时延用户从提问到得到回答需要几秒。我实际联调时发现的最大问题是用户提问方式稍微变化检索效果就剧烈波动。比如问产品的质保政策是什么和问这个东西坏了能不能修表述完全不同语义上却高度相关。单纯靠向量检索很难把这些说法关联起来。后来我加了一个查询改写模块用模型把用户问题改写成更适合检索的形式检索命中率明显上升。这个技巧在RAG项目里非常实用强烈推荐尝试。同时需要注意上下文的长度和成本控制。检索回来的结果越多Prompt越长模型处理时间越长费用也越高。我设置了检索条数上限只保留最相关的Top5左右。如果业务场景确实需要更多上下文就考虑分步补充检索而不是一次性把库都塞进Prompt。6. 评估、优化与常见问题排查6.1 构建你自己的评估体系AI工程项目的质量评估没法完全自动化但也不能完全靠肉眼。我的做法是三层评估体系第一层是自动化指标用于回归测试比如检索准确率、回答与参考片段的一致性第二层是半自动评估用大模型当裁判来给回答打分关注相关性和忠实度第三层是人工评测拿真实业务问题跑一轮人工看结果并标记案例。对于个人项目我建议先从人工评测开始把每个失败案例记录下来分析失败原因归类是检索不到正确内容、检索到了但Prompt组织不好、还是模型输出和检索内容脱节。分类之后你会发现真正的问题集中在那几个类型针对性优化就有的放矢了。人工评估的节奏也要控制好。我每周做一次集中评测每次用同一批问题跑系统对比本周和上周的结果。长期积累下来这套评估集就是你项目的守护神任何模型或配置的变更都在它面前过一遍。6.2 常见问题排查速查表根据我多年实操经验把AI工程项目里最常遇到的问题和排查思路整理成了下面这张表遇到问题时可以直接对照排查症状可能原因排查步骤解决方案回答与资料不符检索召回相关性差打印检索到的文本块检查调低相似度阈值、换嵌入模型、优化切块粒度回答过于简短或空洞Prompt约束过强或上下文不足检查Prompt指令和检索长度增加参考内容、放宽回答长度约束、增加提示词自由度接口时延过高模型调用耗时过长或Prompt过大观察模型输入Token数和请求耗时精简Prompt、换更低时延模型、加缓存层模型输出格式解析失败模型未按JSON格式输出查看原始输出日志开启JSON模式、增加格式示例、加解析重试逻辑Agent重复调用工具规划循环缺少终止条件查看工具调用日志增加最大迭代次数、检测重复调用并终止上下文超限输入内容太长检查输入大小是否超出模型窗口做截断、摘要、分段处理这张表里的每一项我都踩过。最让我印象深刻的是一次生产事故用户反馈系统突然大面积报错查了半天发现是上游嵌入模型的版本被静默升级了向量空间整体变了旧索引全部失效。从此我的变更流程里多了一条铁律任何模型或嵌入版本的升级必须先重建索引并跑回归评估禁止直接切换。6.3 性能与成本优化的经验AI工程项目的运行成本是团队最敏感的话题。我常用的优化手段包括结果缓存、模型分层、批量处理。对于重复出现的相似问题缓存处理能省下大量重复的模型调用费用对于简单任务用轻量模型、复杂任务才用大规模模型我这里指的是类似从站内快捷模型到通用大模型的分层思路在非实时场景里则用批量处理把多个请求拼到一起跑进一步降低单次开销。另外一个非常实用但容易被低估的手段是自建评估流水线把回归测试接入CI流程。每次改动代码之后自动跑一遍评估集输出分数变化和典型案例。这套机制的好处是团队里任何人在model调用或者Prompt变更时都能立刻看到影响而不是上线后才发现效果变差了。7. 从零开始AI工程的路线图我的一些体会项目做多了之后我越来越认同一个说法AI工程能力不是靠看教程学出来的是靠一个个真实项目喂出来的。从零开始AI工程重要的不是掌握了多少模型细节而是能不能在不确定性中找到一套可控的方法论。我这里的方法论归纳起来是明确的分层架构、强化的数据治理、结构化的Prompt管理、严格的评估闭环。如果你现在正处在从零开始的阶段我还想给三个具体建议。第一从一个小而完整的场景做起千万别一开始就铺开做平台能解决一个具体问题的系统比一个哪里都能用但哪里都不精的平台有价值得多。第二把评估集当作项目的一等公民开工第一天就建立而不是最后补交作业这是整个项目中回报率最高的一笔投入。第三尽量去追踪每一行代码背后的成本和效果AI工程项目的资源消耗远比传统项目大没有数据支撑的优化就是在赌博。最后分享一个我个人的习惯每次项目结束我会把这个项目的决策记录写下来包括当时为什么选这个模型、数据方案怎么定的、踩过哪些坑、最后怎么解决的。过几个月再回头看这些记录比自己记得的结论要丰富得多因为里面藏着大量当时的假设和判断。这些积累下来的判断才是AI工程能力真正的核心资产。