从零开始搞AI工程很多人第一反应是调一个API、套一个Prompt、跑通一个Demo就完事了。但我做了一段时间之后发现真正能落地的AI工程至少是Prompt、Agent、工作流、评测、监控一整条链路的组合。这个ai-engineering-from-scratch项目就是想把这条链路完整地走一遍不依赖别人的成品模板从需求定义到模型选型再到提示词设计、工具封装、效果评测最后把系统部署上去持续迭代。这篇文章就是我自己从零搭建AI工程体系的复盘适合那些已经会写Python、知道大模型基本概念但还不清楚怎么把一个AI想法真正做成可靠系统的人。1. 项目概述AI工程不是调接口是从零搭起的一套系统认知1.1 这个项目解决什么问题我见过太多AI项目死在Demo能跑上线就废这一步。原因不是模型不够强而是工程化意识缺失没有定义清楚输入输出的边界没有考虑异常分支没有评测标准也没有成本控制。这个项目想解决的恰恰是这些问题。它不是一个具体的产品更像是一条生产线。生产线上的每个环节我都要求自己从零搭一遍而不是直接复制某个教程里的现成代码。比如Prompt我不直接抄别人的万能模板而是先搞清楚我的任务到底需要模型扮演什么角色、输出什么结构、容忍什么错误比如Agent我不急着接一堆工具而是先想清楚工具调用的触发条件和错误恢复机制。1.2 从零开始到底是从哪个零这里要澄清一下。我说from scratch不是指从机器学习基础开始训练一个大模型那是不现实的。我指的零是指不依赖现成的AI应用脚手架不用别人封装好的一键生成智能体平台而是自己搭建整个应用层逻辑。具体来说我的起点是一个能用Python调大模型API的脚本一个能跑简单命令的命令行环境还有一个包含少量真实业务数据的测试集。在此基础上逐渐加入Prompt管理、工具调用、状态记忆、评测脚本、日志监控这些工程组件。每一步都亲手实现哪怕最后做出来没有商业产品的功能多但你会真正理解每个环节为什么会存在。1.3 适用人群与前置要求如果你属于下面这几类人这篇文章会比较适合你尝试过用大模型做小工具但效果不稳定想系统化解决熟悉Prompt Engineering但不知道Agent、Harness Engineering、工作流这些概念怎么落地团队里没有专门的AI工程师需要一个人从头搭起AI能力比如自动化客服、文档总结、代码辅助想转型AI应用开发但被各种名词绕晕需要一个主线清晰的练习清单。前置要求不高会写Python理解HTTP请求和JSON数据结构知道大模型API的输入一段文本、输出一段文本这个基本交互方式就够了。其他概念我会在过程中补。2. 核心拆解AI工程的四块地基2.1 Prompt Engineering一切交互的入口Prompt Engineering听起来像文科工作实际上是标准的工程活儿。它决定了系统输出质量的上限。我的经验是一份合格的Prompt至少要包含四层信息第一角色与目标。模型需要知道自己是什么人、在什么场景、干什么活。比如不只是说你是客服而是你是电商平台的售后客服在处理退货申请时需要先确认订单状态再给出可执行的退货步骤。第二输入与输出格式。用明确的标记或者JSON结构约束输出避免模型自由发挥。输出结构的稳定性是后续程序能自动化处理的关键。第三约束条件与边界。哪些情况不能回答、哪些内容必须拒绝、哪些字段缺失时要如何兜底。没有边界约束的AI一定会在真实场景里翻车。第四示例。少量、精准的示例比长篇大论的规则有效得多。示例最好是反例正例或者输入正确输出的配对让模型模仿而不是猜测。我在这个项目里专门建了一个Prompt版本管理目录每次修改都记录变更原因和评测结果。这非常重要。很多团队一条Prompt改到天荒地老最后不知道怎么回滚本质上是把Prompt当聊天记录而不是当代码管理。2.2 Agent与Harness Engineering把模型变成会办事的人Agent是当下最热的概念之一但我的理解比较朴素Agent就是模型工具循环控制的组合。模型负责理解任务、决定下一步做什么工具负责执行具体动作循环控制负责让这个过程不断推进直到完成任务。Harness Engineering这个词的重点在于马具——你给模型套上的约束框架。它解决Agent最容易出问题的三点模型不知道该调用哪个工具所以你需要在Harness里定义清晰的工具清单和选择规则模型调用工具出错了不会恢复所以你需要在Harness里设计错误反馈路径让模型能根据错误信息重新选择模型无限循环停不下来所以你需要在Harness里设置最大迭代次数和终止条件。Harness不是提示词工程换个名字它是Agent系统的骨架。没有Harness你得到一个偶尔聪明的随机数生成器有了Harness你才得到一个行为可控的AI员工。2.3 工作流与多工具协作不止是调模型现实业务很少是一个问题一个回答那么简单。更多时候是一连串任务接收用户输入→判断意图→查询数据库→生成草稿→人工确认→发送结果。这就是工作流。我在项目里把工作流拆成编排层和执行层。编排层用Python代码或配置文件定义步骤顺序和条件分支执行层是每个步骤的具体实现可以是大模型调用也可以是普通的字符串处理、API请求、数据库操作。如果不是需要实时交互、动态决策的复杂业务我建议先用这种确定的流程不要一上来就搞完全自由的Agent。原因很简单确定流程可测试、可回溯、成本可控。多AI协作也是一个重要思路。有些任务可以拆成规划AI和执行AI规划AI负责分析任务、拆解步骤执行AI负责具体生成或处理。二者通过结构化消息传递结果比一个大Prompt塞下所有任务更稳定也更方便分别调优。2.4 数据与评测被低估的工程环节项目做到后来我最大的体会是AI工程的瓶颈不是模型而是评测。没有评测你改Prompt全凭感觉上生产全靠信仰。我在项目里做了一个非常简单的评测方案准备30-100个真实输入样本覆盖典型场景、边界情况、难案例每个样本标注期望输出或者至少标注通过/失败的标准每次修改Prompt或Agent逻辑后跑一遍全套样本用脚本统计通过率、失败原因、平均耗时、Token消耗。这个方案不完美但足够让改动变得可比较。后来我把评测结果做成表格每次上线前都给团队看两份数据效果指标和成本指标。效果指标是准确率、完成率成本指标是Token消耗和延迟。没有这两份数据优化就是瞎撞。3. 实操过程跑通一个最小的AI工程闭环3.1 需求定义与场景收敛任何AI项目第一步都不是选模型而是把需求圈到足够小。给我的练习项目定的目标是做一个招聘JD分析助手输入一份岗位描述输出岗位的关键职责、硬性要求、软性要求、推荐搜索关键词。这个场景足够具体又包含文本理解和结构化输出非常适合练手。场景收敛的原则是越小越好越小越能测出真问题。如果你的需求描述里出现理解、洞察、智能这种词基本等于没定义。要做的是把智能翻译成可执行的动作提取什么字段、判断什么标准、输出什么格式。3.2 模型选型与成本测算选型阶段我列了一个对比表主要看四个维度效果、速度、价格、上下文长度。不同模型的英文写作、逻辑推理和中文理解能力差异明显面对JD分析这种中文任务我最终选择了在中文理解上表现稳定且支持结构化输出的一个中等规模模型。成本测算也不能省。我先拿30条样本跑了一遍算出平均每条的输入Token和输出Token推算出处理一万条JD大概要花多少钱。这一步很有用它会逼你去优化Prompt长度把不必要的背景说明删掉只留真正影响输出的内容。3.3 Prompt设计与迭代我写Prompt的方式是先写丑陋版把需求用大白话写在文本文档里不管格式目的是让信息完整。然后逐步结构化加入角色、规则、输出格式和示例。每次改动都记录版本号并在评测集上对比效果。迭代中最有价值的一次修改是给输出格式加了一个无法判断选项。原来模型会被迫编造信息增加了这个选项后模型在面对模糊描述时能诚实地标注无法判断系统的可信度一下提高了。这个细节说明Prompt设计不是让模型变得更聪明而是让它变得更诚实。3.4 搭一个简单的Harness输入→工具→输出最开始我的Agent只有一个功能读取文本。后来我加了两个工具一个用于查询内部职位库一个用于保存分析结果。Harness的逻辑是接收原始JD文本模型判断是否需要查询职位库如果需要就调用工具工具返回结果后模型把结果和原文结合生成最终分析输出到固定目录并记录日志。这个过程中我给每个工具写了一个返回状态机制正常返回数据异常则返回错误信息。Harness捕获错误信息后把错误作为新的上下文交给模型让它决定是重试还是放弃。这个设计看起来简单但它是Agent可靠性的基石。3.5 评测与回归评测脚本我写得非常简朴读入测试样本调用主流程把结果和预期对比最后输出一个通过率报告。报告里不仅包含正确率还包含每条样本的失败原因——是模型理解偏了还是工具调用错了还是输出格式不符合解析要求。第一次跑评测通过率只有六成大部分失败原因是输出格式不稳定。我修改了Prompt用了更严格的JSON schema描述和示例通过率升到八成。之后又补了几个边界样本比如空文本、极长文本、只有两行字的简版JD继续优化后稳定在九成左右。评测不是一次性的它是个持续过程每次改动都要跑一遍。3.6 上线与监控上线我用了最简单的方案一个定时任务每天批量处理新增的JD一个日志目录每次运行都记录输入、输出、耗时和Token数。日志是AI工程最容易被忽略的基础设施。没有日志线上出了问题你根本不知道是Prompt的问题还是工具的问题只能躺着猜。我还在日志里加了一个置信度字段。模型在输出结果时同时输出一个自我打分的置信度值。低于设定阈值的样本会被自动标记为待人工确认。这个机制不复杂但能把系统的风险控制在可接受范围内。4. 常见问题与排查技巧实录4.1 Prompt写了很多但仍然乱答如果你发现Prompt越来越长效果却越来越差多半是信息过载。模型不是人类不会自动分辨哪些指令更重要。我遇到过的情况是把角色描述、任务规则、历史背景、语气要求全堆在一起模型反而抓不住核心任务。解决办法是主次分离把最核心的指令放在最前面用简洁明确的动词句把次要的背景信息放在后面用较小的权重词引导比如以下内容仅供参考。另一个办法是删掉一半内容再测试如果效果没变差说明删掉的部分本来就是噪声。4.2 Agent陷入死循环或乱调用工具这是Harness设计不到位导致的。我在早期版本里没有设置最大迭代数结果模型在查询职位库→发现没有结果→再查询→再没有之间无限循环把我的API额度烧掉一大截。后来我做了三层限制最大迭代次数设为5次超过就停止并返回处理失败同一个工具连续调用超过2次就强制终止防止重复尝试每次工具返回结果都附上是否需要继续查询的建议字段由模型主动判断是否结束。这套机制上线后再没有出现过死循环。经验是永远不要信任模型的自控力用代码把边界焊死。4.3 上下文被撑爆长文本任务很容易把上下文窗口占满尤其当你做Agent时每轮工具调用结果都要塞进上下文。我的JD分析任务原本很短但后来加入职位库查询后工具返回了几百条职位记录模型直接被喂到接近上限速度变慢、输出质量下降、成本飙升。我在Harness里加了一个上下文压缩层工具返回的大量数据先经过一次摘要处理只保留与当前任务相关的字段摘要再传给模型。另外对于历史轮次的旧对话我会做截断或摘要而不是全部保留。这就像人的短期记忆一样只记住必要的那部分。4.4 效果时好时坏同一份输入模型有时候回答得好有时候回答得差这也是常见痛点。主要原因通常是模型采样温度设置过高或者Prompt存在模糊表达。温度建议在任务型场景设低一些比如0到0.3之间让输出更稳定。同时对输出要做后处理验证如果要求JSON格式就用代码解析并捕获解析异常解析失败就自动重试一次。重试时可以把失败原因回传给模型让它自我修正。这个失败重试错误反馈机制能把随机性带来的问题压到很低。4.5 成本失控AI项目的成本主要来自三块输入Token、输出Token和重试次数。我在日志里记录每个任务的Token消耗设置一个日消耗告警阈值。另外缓存命中率也很关键同一个JD如果前一天处理过第二天不应该再重新调用模型。我的做法是加了一个简单的结果缓存以输入文本的哈希值为键存储处理结果。如果命中缓存直接返回不调用模型。对于批量任务场景缓存能省下至少三四成的成本。5. 实战复盘CodeBuddy式Harness Engineering的一个完整案例5.1 场景让AI完成代码库分析除了JD分析我还在这个项目中跑了一个更复杂的场景让AI理解一个不熟悉的代码仓库完成功能模块梳理和接口清单提取。这个场景的目的是想验证Harness Engineering在准代码助手方向上的可行性对应现在热门的产品形态比如CodeBuddy这类编程助手。5.2 流程设计整个流程分成五个阶段代码库扫描用脚本列出所有源文件生成文件树模块定位模型根据文件树和文件名判断哪些文件属于核心模块逐文件分析每个文件单独送入模型提取函数签名、关键类和外部依赖汇总合并把逐文件结果汇总成模块级文档质量校验用脚本校验提取结果和实际代码是否一致比如函数名是否真实存在。5.3 关键设计点这个案例最有价值的地方是拆分。如果直接把整个代码库塞进一个Prompt结果一定是混乱的。拆成文件树→文件级分析→模块级回归每个环节的输入输出都很清晰任何一个环节出错了也容易定位。另外一个关键点是工具返回的是代码原文代码原文本身就是噪声很大的数据。我写了一个预处理器把注释、空行、文件头去掉只保留代码结构大大减少了Token消耗。这一步让我意识到Harness里面工具返回信息的预处理和Prompt设计同等重要。5.4 经验与教训第一次跑这个案例模型在模块定位环节把配置文件和业务代码混在一起导出的模块清单完全不可用。后来我在Prompt里加入了判断规则扩展名为配置类、测试类的文件不参与业务模块分析单独归类。这个规则看似简单但如果没有这个边界模型永远分不清。还有一个教训是不要在文件分析阶段让模型输出长篇解释。我一开始要求模型输出分析理由代码结果理由部分占了两百多Token对下游毫无作用。后来改成只输出结构化结果理由字段单独用一行简述成本低了一半准确率没有下降。做事少做多余的思考AI也一样。6. 从0到1的路线图与避坑清单6.1 按顺序学习不要直接追热点如果你想系统掌握AI工程我建议按这个顺序推进首先是基础模型API使用搞懂输入、输出、温度和Token然后是Prompt Engineering学会用角色、格式、示例、边界来控制输出接着是Agent基础理解工具调用和循环再往后是Harness Engineering学习设计约束、错误恢复和终止条件最后才是工作流、评测、监控和成本优化。不要一上来就研究多Agent协作也不要一上来就试图复刻一个商业产品。把最小的闭环跑通再逐步加复杂度这是最省时间的路线。6.2 避坑清单我整理了一份自己踩坑最多的清单你会发现大部分问题不来自模型来自工程习惯没有评测集你会陷入改了又好好了又改的无限循环没有版本管理Prompt改错后无法回滚只能靠记忆恢复没有日志线上出了问题完全黑盒排查靠猜没有成本记录等月底看到账单才意识到Token烧了多少钱没有异常处理工具回调失败时Agent直接崩掉而不是优雅降级输出格式不校验模型返回的JSON偶尔多一个逗号你的解析代码就直接报错一次塞太多任务想让一个Prompt做所有事结果哪件事都做不精。6.3 工具选型的经验参考工具这块我的原则是先用最普通的再换最趁手的。早期我用Python脚本和SQLite写日志用Markdown维护评测集用Git管理Prompt。这套组合没有任何花哨但足够验证思路。等流程稳定后再考虑引入更成熟的编排框架、向量数据库和可视化监控面板。选型不要追新。很多新框架每天都在发布但你的项目需要的是稳定、可控、文档全。我见过不少团队因为换框架花掉大量时间最后发现原本的核心问题并没有被解决。工具永远是为目标服务的而不是反过来。6.4 最后再分享一个小技巧这个技巧是当你调试Agent时把模型在想什么这个中间过程记录下来。我习惯让模型在每轮调用前输出当前状态下一步计划原因并把这些中间思考保存在日志里。这样一旦结果不对我能看到模型是在哪一步跑偏的。这个做法会让Token成本增加一点但对排查效率的提升是巨大的。做AI工程这么久我最深的体会是真正拉开差距的不是模型有多先进而是你对待工程细节有多认真。一个能稳定输出结构、能处理异常、能控制成本、能被日志追踪的AI系统比一个偶尔惊艳但随时翻车的Demo有价值得多。希望这份从零起步的复盘能帮你少走一些我走过的弯路。