“AI工程从零开始”这句话喊的人多落地的人少。我见过太多项目卡在同一个地方模型刚写了几行代码跑通就急着接业务结果prompt一换场景就崩Agent跑着跑着自己就失控了更别说评测和迭代。这篇文章我想用一个完整案例把从零搭建一个AI应用我习惯叫它AI工程的核心环节拆开来讲包括提示词设计、Agent编排、工程化落地和评测复盘。如果你是刚接触AI工程、或者已经做了几个demo但总觉得离“能上生产”差口气的人这篇文章应该能帮你少走很多我踩过的弯路。这里说的“AI工程”不是让你从权重开始训练大模型那条路的成本和门槛完全不同而是指在现有语言模型基础上把提示词、工具调用、流程控制、结果校验这些环节系统性地组织起来形成一个稳定可控的应用系统。我见过的许多团队本质上是把AI工程做成了“prompt拼接”没有把它当成真正的软件工程来对待。这篇博文就是想把后者这件事讲透。1. 从零开始先想清楚一件事你到底在造什么1.1 别急着写代码先定义你要解决的问题边界很多刚接触AI工程的人一上来就问“我要用哪个框架”“我要调哪个模型”这是典型的工具先行误区。我做过的几个失败项目复盘时发现根因都不是模型不够强而是“我们根本没想清楚系统要做什么、做到什么程度算成功”。动手前请先回答四个问题输入是什么是用户自由输入的文本还是带结构化字段的表单输出是什么需要精确的JSON还是允许自然语言返回边界在哪里系统允许调用哪些外部工具不允许做哪些事失败的代价是什么如果回答错了用户会发现并投诉还是只是降低一点体验这四个问题的答案直接决定你后续的提示词设计、工具配置、评测方案甚至模型选型。举个例子如果输出是结构化JSON那你必须启用模型的JSON模式并在代码里做schema校验如果输出会被直接展示给用户那你可以更侧重于流式输出和表述自然度而不是强约束格式。我习惯把这些边界写进一个简短的“系统用例文档”一页纸就够。这个文档是给团队看的也是给模型看的——系统提示词里大部分内容就来自这个文档。1.2 “从零”其实有两种起点决定你的技术路线“from scratch”这个词很容易让人误解。如果是想从头训练一个类似LLaMA的大模型那你需要的是几万张显卡、海量数据和很长时间这不在普通人“工程实践”的范围内。但如果你是像我一样的产品技术负责人想在现有模型能力之上构建自己的AI应用“从零”的真正含义是不依赖别人的模板、不抄现成框架的示例自己设计一套适配业务场景的提示词、工具编排和评测机制。这两种起点的技术路线完全不同。前者是模型层的“预训练-微调-对齐-部署”后者是应用层的“提示词-工具-编排-评测-迭代”。这篇文章聚焦后者因为对绝大多数团队来说后者才是投入产出比最高的选择。但完全不理解前者也不行至少要知道模型是概率系统它输出的不是确定结果这就决定了你所有工程手段的核心目的只有一个把不确定性尽可能关在笼子里。2. 把“AI工程”拆成四个核心模块2.1 提示词工程不是写文案是定义输入输出契约很多人把提示词工程理解成“把话说清楚让模型听懂”这个理解太浅了。跟模型打交道的次数多了你会发现提示词其实是“程序接口的注释增强版”它定义了输入输出的契约。一个健壮的提示词应该包含五个部分系统角色定义模型应该以什么身份、什么专业背景来回答。任务范围约束什么话题该回答什么话题必须拒绝什么情况下该转人工。输入格式说明告诉模型用户可能输入哪些类型的内容如何解析。输出格式规范给出JSON模板或markdown结构要求严格遵守。例外处理规则当信息不足、检测到恶意输入、遇到模糊请求时怎么办。举个例子我做一个“资料检索助手”时系统提示词的开头不是“你是一个助手”而是你是企业的资料检索助手。你的任务是根据用户问题调用搜索工具阅读搜索结果原文提炼答案。 规则1必须基于工具返回的内容回答禁止编造信息来源。 规则2当搜索结果与问题无关时回复“未找到相关信息”不要强行作答。 规则3输出必须使用如下JSON格式{answer: ..., sources: [...], confidence: 0.0-1.0}为什么要写这么细致因为语言模型对模糊指令的“发散”能力远超你的想象。你只说“找资料”它会自由发挥你给出明确规则和格式它才知道边界在哪。关键心得提示词一定要做版本管理。我见过太多团队直接在生产环境里手改提示词改完没记录效果回归了都不知道是哪个版本导致。建议把每个提示词模板存成独立文件用Git管理修改必提交线上版本和提交记录一一对应。2.2 Agent 不是魔法是“能力编排”的设计Agent是现在最热的概念之一但真正理解它的人不多。从工程角度看Agent就是一个“能自主决定工具调用顺序的循环系统”它接收任务决定是否需要调用工具调用后获得结果再决定下一步动作直到满足结束条件。如果你看过一些所谓“harness engineering”的资料会发现这个词本质上讲的就是怎么为Agent设计一个“安全带/控制框架”。控制框架至少包含三个要素工具注册表明确告诉模型有哪些工具可用、每个工具的参数schema描述是什么。决策循环模型输出工具调用请求代码执行请求把结果反馈给模型再让模型决定下一步。终止与回退设定最大循环步数和退避规则避免模型陷入死循环或错误路径。很多人会问为什么需要Agent直接用一个大调用完成“用户问题 - 答案”不行吗确实很多简单场景一次调用就够但一旦涉及“获取最新数据、查数据库、操作现有系统”这类需要动态信息的场景单次调用就不够了。模型不知道数据库里有什么你需要它自己去查询。Agent循环就是解决“动态决策”问题的。别急着引入LangChain这类重量级框架。我的建议是第一版Agent用原生SDK手写循环尽量把控制流掌握在自己手里。框架能帮你省事但也会掩盖细节当你连“什么时候该重试、什么时候该结束”都没想明白时框架的默认策略只会让你更加困惑。2.3 流程编排从单次调用到多角色协作真正的AI工程很少只有一个Agent单打独斗。更常见的情况是多个Agent各司其职或一个Agent拆分成多个阶段。比如资料检索助手可以拆成“意图识别Agent”“检索Agent”“生成Agent”三个角色每个Agent拥有不同的提示词和工具集。为什么这么拆因为每个子任务的最优提示词不同。意图识别关注的是分类准确性不需要引用文献生成Agent关注的是表达自然和信息忠实需要引用来源。如果能将它们拆分每个阶段的提示词都能做到精简专业整体效果远好于一个万能Agent加上一堆复杂指令。流程编排要注意三个问题状态传递上游Agent的输出通常含有中间结果如何安全地传给下游Agent。建议用统一的JSON结构在节点间传递而不是直接拼字符串。错误分支如果意图识别失败后面的流程不要继续跑直接返回兜底文案。人工介入点在设计流程时提前标好“哪里需要人工审核”。比如涉及对外发送邮件之前必须有人确认。2.4 评测与观测没有度量就没有工程不做评测的AI工程等于在黑暗里开车。模型每次输出的分布都可能有差异你今天好用的prompt明天模型一更新可能效果大跌。所以从第一天开始就要建立评测集和观测机制。评测集不需要很大但要有代表性。我会在项目启动时花两个小时从真实使用记录里挑出30到50条典型输入标注好“标准答案”和“可接受答案”。每次修改提示词或调整工具配置就全量跑一遍评测集记录评分。评分方式可以用客观指标如JSON schema通过率、字段缺失率也可以用“模型评模型”做LLM-as-judge让一个强模型按固定标准打分。观测方面至少要有日志记录以下几点每次请求的prompt版本号模型返回的完整原始输出Agent每一步动作调用了什么工具参数是什么耗时、token消耗、费用失败类型超时、解析失败、校验失败、安全拒绝带着这些数据去迭代你才能说“这个改动提升了3%”而不是“感觉好像变好了一点”。3. 实操从零搭建一个最小可用的AI Agent3.1 场景设定与功能拆解为了把上面的原理讲清楚我带你搭一个最小但完整的AI Agent功能是“技术问题研究助手”它能根据用户提出的问题调用一个内部知识库接口检索相关文档片段再生成带引用来源的回答。这个场景的典型输入是“帮我查一下系统里关于权限配置的文档并告诉我管理员如何修改角色权限。”我把它拆成两个阶段检索阶段调用知识库API传入用户问题作为关键词获取Top3文档片段。生成阶段把检索结果和用户问题一起放进提示词让模型生成回答并标注引用。注意这里我先不做多轮对话和复杂工具链因为最小可用的意义在于先把闭环跑通后续可以在此基础上扩展。3.2 环境准备与依赖选择环境只需Python 3.10加上openai官方SDK你需要一个兼容OpenAI API的模型服务或云服务不需要额外的Agent框架。为什么不用LangChain不是为了“炫技”而是当项目规模还没大到需要抽象层时手写循环反而更可控。你可以清晰看到每次请求的输入输出方便排查和调优。等真正复杂到需要并发管理、记忆持久化、工具生态接入时再引入框架也不迟。依赖安装就一行pip install openai再加一个用于校验JSON的库pip install jsonschema3.3 核心代码实现首先定义一个工具注册表用一个字典维护所有可调用工具的描述和执行函数def search_knowledge_base(query: str, top_k: int 3) - list[dict]: 模拟检索知识库文档片段的函数实际项目中换成向量库或搜索服务 # 这里省略真实实现返回两个模拟片段 return [ {id: doc-001, text: 角色权限在管理员后台的“角色管理”页面配置修改后即时生效。}, {id: doc-002, text: 管理员可以使用admin账号进入系统设置选择需要修改的角色并调整权限范围。}, ] TOOLS { search_knowledge_base: { description: 搜索内部知识库返回相关文档片段。参数query(str), top_k(int), function: search_knowledge_base, } }然后写一个引用工具的提示词模板SYSTEM_PROMPT 你是一个企业知识库助手。 请根据用户问题调用search_knowledge_base工具获取资料然后基于资料回答。 规则 1. 输出必须是可以被json.loads解析的JSON格式为{answers: [{content: 回答内容, source_id: 文档ID}]} 2. 只引用工具返回内容里包含的信息禁止编造。 3. 如果工具没有返回有用信息output字段为未找到相关信息source_id为null。 USER_PROMPT_TEMPLATE 用户问题{question} 请开始回答。接着是Agent的主循环。逻辑很简单把系统和用户消息发送给模型如果模型返回内容可被解析为工具调用则执行工具并把结果作为后续消息之一继续对话直到模型输出最终答案或达到最大轮数。为了控制篇幅我这里先给出一个简化版假设模型直接返回最终答案不先走工具调用逻辑先调用工具然后把结果拼接到消息中再让模型生成答案。import json import openai client openai.Client() # 配置好base_url和api_key def run_agent(question: str, max_rounds: int 2) - dict: # 1. 先调用检索工具获取文档上下文 docs TOOLS[search_knowledge_base][function](question, top_k3) context \n\n.join(f[{d[id]}] {d[text]} for d in docs) # 2. 构造消息 messages [ {role: system, content: SYSTEM_PROMPT}, {role: user, content: USER_PROMPT_TEMPLATE.format(questionquestion)}, {role: assistant, content: f我查一下知识库返回结果如下\n{context}}, ] # 3. 调用模型生成最终答案 resp client.chat.completions.create( modelMODEL_NAME, messagesmessages, temperature0.2, response_format{type: json_object}, ) content resp.choices[0].message.content return json.loads(content) result run_agent(管理员如何修改角色权限) print(result)这个代码虽然简单但已经包含了“检索-生成”的基本闭环。实际项目中你还需要把工具调用放在循环里因为可能一次检索不够需要再追问或者生成的中文路径需要二次确认。但第一版能把闭环跑通最重要。3.4 运行调试与输出微调我运行上面的代码三次结果并不完全一致其中一次还把answer写成了“根据文档管理员修改角色权限需要在后台进行”虽然意思对但格式里缺少source_id。这是因为JSON模式只保证是json对象不保证字段完整。此时需要用jsonschema校验并用重试机制补一次from jsonschema import validate schema { type: object, properties: { answer: {type: string}, source_id: {type: [string, null]}, }, required: [answer, source_id], } validate(instanceresult, schemaschema)如果校验不过就把报错消息和新一轮提示发给模型让它重新输出。这种“校验-重试”机制是保证生产可用性的关键细节。小技巧在调试阶段每次请求都打印日志包含prompt、raw output、校验是否通过、消耗token数。你会发现模型行为模式越来越清晰。4. 常见问题与排查技巧实录4.1 大模型输出不稳定怎么解析和兜底这是AI工程里遇到最多的问题。同一个prompt模型今天返回标准JSON明天可能多了一句“好的这是你要的答案”。我的标准做法是三重兜底第一重设置response_format为json_object尽量约束输出结构。第二重用schema校验不通过就自动重试重试次数一般设1到2次。第三重重试仍然失败时降级到“文本后处理”用正则提取JSON片段的尝试保留如果还不行就返回“服务暂时不可用”的提示文案。不要指望模型永远守规矩。设计时就要假设它可能犯错并让防线在每一层都拦住问题。4.2 Agent跑飞了怎么限制行为边界Agent最常见的失控方式是反复调用同一个工具或者在没有结果的情况下继续“编造步骤”。我出过几次事故之后总结出三条硬规则最大步数限制设定循环上限如4步超过就强制终止并返回当前已有结果。工具白名单Agent只能调用注册表里明确告知的工具不能让它即兴发挥任何未注册动作。预算拦截每次工具调用前检查总token预估接近预估值就停止禁止“超支续跑”。如果模型是调用外部API或操作数据库这些限制尤其重要。我遇到过一次生产事故Agent在循环里重复调用了10次搜索API账单涨了上百倍幸好步数上限及时拦截。从那以后工具调用前我都会加一个“确认”中间层。4.3 评测集过拟合或偏差怎么设计很多团队的评测集要么是开发工程师自己随手写的测试用例跟真实用户需求脱节要么只有十几个case模型一改就跑不准。我建议从三个维度扩充分布常见问法覆盖高频、标准表达。边缘问法问题里包含错别字、含糊表述、超长上下文、口语化表达。拒答样本明明不该回答的内容你要看模型是否真的拒绝。评测集建议每两周更新一次。真实用户日志里挑出最近新增的、有价值的问题补充进集合。如果某次改动导致旧case效果变好但新case变差就要考虑是不是过拟合了旧模式需要重新平衡。4.4 成本与性能怎么平衡模型越强效果越好但成本也可能翻十几倍。我的常见组合招数缓存高频查询对相同或相似问题复用结果使用语义向量计算相似度相似度超过阈值就返回缓存。模型分级简单问题走轻量模型复杂问题走旗舰模型。可以通过一个分类器先判断难度再路由到不同模型。压缩上下文只传入最近几轮对话和有效检索片段不要一股脑塞进整段知识库。并发上优先做异步和批量但也要为每个用户设置速率限制。AI工程的运维更像是一个“限流系统”不是给你算力就完事得考虑每次调用的波动性。4.5 一个容易忽视的细节提示词版本与线上线下一致性我在多个项目里遇到过“线上模型效果突然变差”的假象排查半天才发现是有人改了线上系统的prompt文件但版本没提交。后来我严格要求prompt模板以代码形式提交线上部署使用与代码绑定的同一份模板文件任何人要修改都必须走代码评审和发版流程。这样做还能让“效果回滚”变成一条git revert操作。最后再分享一个小技巧无论你用什么框架从零开始做AI工程时永远把“如何验证效果”当成和“如何实现功能”同等重要的事。我吃过最大的亏就是在上线第一个Agent时只关注了它能回答什么却没提前定义它“哪些不该做”结果用户在无关问题上得到了错误答案一下击穿了信任度。所以建一个几十条的冒烟评测集从第一行代码起跑着它你的AI工程才算真正入了门。