1. 为什么我决定从零搭建AI工程，而不是直接套编排框架

大概半年前，我手头堆了一堆 AI 相关的工具和框架：LangChain、AutoGPT、各种 Agent 平台，还有前段时间社区里反复讨论的 harness engineering 思路。工具的清单越来越长，但真正落到业务上的时候，我发现自己陷入了一个很尴尬的处境——单个模型调用的效果已经不错，可一旦组合成"工程"，就到处漏水。

你可能会问：市面上现成的编排框架那么多，为什么要从零开始？我当时的判断很简单：现成的框架解决的是"通用连接"问题，而我遇到的是"特定场景下的可靠性"问题，这两件事根本不在一层。框架帮你把 A 模型的输出接到 B 模型的输入，但如果你连"A 模型的输出到什么程度算合格"都没办法定义，接得再顺也是把垃圾从一个管道倒进另一个管道。

另外还有一个很现实的因素——黑盒叠加黑盒，出了问题根本没法排查。大模型本身的输出就有随机性，这是第一层不确定；框架在你不知道的地方做了 prompt 拼接、记忆压缩、工具调用重试，这是第二层不确定。当两层不确定性叠在一起，你拿到一个错误结果，完全不知道是模型的问题、提示词的问题、还是框架内部逻辑的问题。与其在一个失控的系统里猜，不如从最底层把每一个环节都变成自己看得懂的代码。

所以我把这个项目起名叫 "ai-engineering-from-scratch"。这里的"from scratch"不是说要从头训练一个大模型，而是说在应用层把 AI 能力当作一个被严谨对待的工程组件来搭建——自己设计提示词的信息结构，自己写 Agent 的循环，自己定义多 Agent 协作的协议，自己建立可观测性和质量评估。这篇文章就是我在这个过程中的完整复盘，包括设计思路、踩坑记录和可以直接拿走的代码骨架。

这个项目适合谁？我建议这几类人重点看：

• 已经用 API 调通了一些零散功能，但想让 AI 真正稳定地跑在业务链路里的开发者
• 被 LangChain 这类框架的"黑盒魔法"困扰过，想搞清楚底层机制的人
• 对 prompt engineering 有一定了解，但觉得"背模板"不够用、想理解第一性原理的人

下面的内容不会涉及任何需要付费的工具，核心思路也不绑定具体的模型厂商，你可以根据自己的实际情况套用。

2. 提示工程的第一性原理：从"背咒语"到设计信息结构

2.1 你给的上下文决定了模型的能力上限

很多人把 prompt engineering 理解成"给 AI 写一套神奇的咒语"——似乎只要把网上流传的某某大师提示词复制进去，模型就会开窍。我在项目初期也是这么干的，直到有一次对比实验让我彻底改变看法。同一个任务，我用网上流传的"资深专家"身份提示词跑出来的结果，和用我自己写的一份朴素但结构清晰的指令跑出来的结果，在准确率上几乎没有差别。差别出现在哪里呢？出现在模型的输出的稳定性上——结构清晰的指令，十次输出有九次能保持一致；花哨的提示词，十次输出有三次会跑偏。

后来我理解了背后的原因：大模型本质上是一个在巨大文本语料上训练出来的"下一个 token 预测器"。它不是真正"理解"了一段中文指令的深意，而是在你给出的上文约束下，计算最可能的续写路径。这就意味着，提示词里每一个字都在改变模型后续输出的概率分布。你给的信息结构越清晰，模型在续写时面对的"不确定性"就越小，输出自然更稳定。

我自己总结了一套比较实用的上下文设计公式，你可以直接抄作业：

2.2 结构化输出是工程化的第一步

如果说提示词设计第一个要解决的问题是"怎么让模型说人话"，那第二个问题就是"怎么让模型说结构化的人话"。工程化的本质是接口化，而大模型输出文本天然是弱类型的。我最初犯的错误是让模型直接输出自然语言，然后在代码里用正则去解析关键信息——这个方案在 demo 阶段看起来很顺利，一到真实流量下就崩了，因为模型的表达方式千奇百怪，今天说"价格为 100 元"，明天说"100 块钱"，后天说"总价是 100 元整"。

我后来的做法是让模型输出 JSON，并且在提示词里直接给出完整的 JSON Schema 示例。比如我在一个信息抽取任务中的提示词片段是这样的：

请从以下用户反馈中抽取结构化信息，严格按照示例格式输出 JSON，不要输出任何多余内容。 示例输出格式： {"sentiment": "negative", "issue_category": "shipping_delay", "confidence": 0.92, "key_phrases": ["还没收到", "快递太慢"]} 用户反馈：{{user_input}}

这段提示词的核心不是让模型"用 JSON 输出"，而是通过一个完整的示例把"JSON 长什么样"直接喂给模型，让它在这个结构里续写。实测下来，配合模型的 JSON mode（大多数主流 API 都支持），十次调用里九次以上能拿到一个可直接json.loads()的合法结果。

这也引出一个很重要的工程决策：不要把解析逻辑写在代码里，而是把解析约束写在提示词里。模型负责生成符合结构的内容，代码负责安全的解析——职责分离，出了问题也容易定位。

2.3 采样参数是提示词的"另一半"

我在项目早期几乎完全忽略了采样参数对工程稳定性的影响，直到有一次一个任务在测试环境跑得很好，上线后却开始频繁输出随机内容。排查了很久才发现，不是模型变了，是我忘了设置temperature——默认参数下模型选择可能性的倾向太强，导致同样的问题给出了多种多样的答案。

我的经验是，如果你用 AI 做的是确定性优先的任务（信息抽取、分类、意图识别、格式化转换），temperature可以直接压到 0 或者接近 0；如果你做的是创意生成类任务（文案撰写、头脑风暴），temperature可以放到 0.7 到 0.9。另外还有两个参数值得关注：

• top_p：控制模型从概率前多少的 token 里采样。和temperature有一定的重叠作用，我习惯固定一个不调，只调另一个，避免两个参数一起抖造成不可预期的结果。
• max_tokens：不设上限的后果是模型有时候会在输出完结构化内容后又来一段废话。我建议根据任务类型估算正常输出长度，然后给一个稍高的上限，既能防止失控也能控制成本。

这里有个容易被忽略的细节：temperature=0并不意味着输出一定完全确定。我在项目中遇到过几次在temperature=0下依然输出不一致的情况，原因是 GPU 计算的浮点不确定性或者并行采样引起的微小差异。所以永远不要在代码里假设"同样的输入一定得到同样的输出"，任何 AI 输出都必须走校验那一关。

3. 让 AI 从"回答工具"升级为"工作单元"：Agent 循环的拆解与实现

3.1 Agent 不是魔法，是一个显式化的循环

社区里对 AI Agent 的讨论很多，但你会发现很多人其实说不清楚 Agent 到底是什么。有人觉得能调用工具就是 Agent，有人觉得能自主规划就是 Agent。我的理解更朴素：Agent 是把"从目标到行动再到结果"这个过程显式化成一个循环，让模型在循环的每一步都有机会反思和修正。

传统的单次调用模式是这样的：你问一个问题，模型给你一个答案，任务结束。这种模式的瓶颈在于，模型在一个回合里既要理解问题，又要规划步骤，还要把步骤执行完——信息量太大，模型的长程规划能力又有限，稍复杂的任务就崩。

Agent 循环的核心思路是把这个过程拆开：模型先思考，在思考结果里声明"我下一步需要调用什么工具"，然后外部系统执行工具拿到结果，再把这个结果返回给模型，模型再继续思考下一步。用代码来表达是这样的：

def run_agent(task, max_steps=10, verbose=False): messages = [{"role": "system", "content": SYSTEM_PROMPT}] messages.append({"role": "user", "content": task}) for step in range(max_steps): # 模型产出思考结果，可能包含调用工具的意图 response = llm_call( messages=messages, tools=TOOL_SCHEMAS, # 工具的函数签名描述 tool_choice="auto", temperature=0.2 ) messages.append(response) # 如果没有工具调用意图，说明 Agent 认为任务完成了 tool_calls = response.get("tool_calls") if not tool_calls: return response["content"] # 外部系统真实执行工具，结果返回给模型继续循环 for tool_call in tool_calls: result = execute_tool(tool_call) messages.append({ "role": "tool", "tool_call_id": tool_call["id"], "content": result }) if verbose: print(f"[step {step+1}] called {tool_call['function']['name']}") return "MAX_STEPS_REACHED"

如果把代码拉平看，这个循环一点也不神奇——它就是模型在"思考"和"行动"之间来回切换的对话记录。但它解决了单次调用的最大问题：模型不再需要在一句话里完成从规划到执行的全过程，它可以在每步执行后看到真实世界的反馈，再决定下一步怎么走。

3.2 工具调用的边界条件：给模型配"知道自己的能力"的清单

Agent 循环能不能稳定工作，很大程度上取决于你给模型的工具清单设计得怎么样。我见过很多人直接把十几个函数一股脑丢进工具列表，结果模型经常选错工具或者在一个工具上绕圈。这里的原因也好理解——模型对每个工具都只有一个"名字和描述的文本"，它是在用文字理解工具的用途，而不是像人一样看过工具源码。

我的几个实操建议：

• 工具数量控制：一个 Agent 在一段循环里需要关注的工具建议不超过 5 个。工具太多，模型的选择空间太大，出错的概率指数上升。如果业务确实需要很多工具，拆成多个 Agent 各管一摊。
• 工具描述必须说明边界：不要只写"搜索函数"，要写"在内部知识库中搜索产品文档，仅支持精确匹配标题，输入参数为文档 ID 列表，返回值最多 5 条"。描述直接决定模型的调用准确度。
• 一个工具只做一件事：我最开始设计了一个"综合查询"工具，能查订单、查商品、查用户信息，当时觉得方便，结果模型经常搞不清楚该传什么参数。拆成三个独立工具后，准确率立刻就上去了。

工具调用的本质是把"模型的文本世界"和"真实系统的物理世界"之间的桥梁搭好，桥梁上的每一处指示牌（描述）越清晰，车（模型）就越不容易走错路。

3.3 思维链的价值与局限：什么时候该让它"先想再说"

现在很多开发者习惯在提示词里加一句"请一步步思考"，这就是思维链的通俗版。思维链确实能在不少任务上提升效果，但我在实际项目里发现它有两个容易忽略的副作用：

第一，思维链会显著增加输出 token 的数量，直接拉高成本。一次推理任务如果让模型把每一步想清楚的推导都写出来，输出长度可能增加 30%-50%，而且在长文本场景下还要预留足够的输出窗口，间接影响上下文容量。

第二，思维链暴露了模型的推理中间态。在某些需要严格保密策略判断的场景（比如信贷审批、风控决策），把推理过程明文输出是不可接受的。而且一旦推理中间态出现错误信息，在后续处理中反而会干扰最终决策。

我的取舍策略是：简单的分类、抽取任务不做思维链，直接强制输出结构化结果；复杂的多步推理任务（比如代码调试、数据分析）才让模型"先在内部推理，所有推理步骤都放在一个受控的字段里"。

具体做法是在输出格式里增加一个"hidden"字段：

{ "reasoning": "（内部推理过程，不直接对外展示）", "result": { "category": "bug_fix", "files_changed": ["server.py"], "suggestion": "在数据库连接池关闭后增加重试机制" } }

这样模型有了思考空间，同时最终输出依然是可控的结构化格式。你可以根据自己的需求决定是否输出reasoning字段——第一次跑通系统时建议完整输出，方便排查问题；稳定运行后再在接口层把它过滤掉。

4. 多 Agent 协作与工作流编排：我踩过的三个深坑

4.1 上下文污染：邻居的消息被塞进了我的窗口

项目进入多 Agent 阶段后，我遇到的第一个大坑是上下文污染。当时我让一个 Agent 负责收集材料，再把收集到的结果交给另一个 Agent 做总结输出。听着很合理对吧？但实际上，我把 Agent A 的完整对话历史，包括它的思考过程、中间试探、以及无关紧要的自我纠错，全部塞进了 Agent B 的上下文窗口。

结果 Agent B 开始"继承" Agent A 的思考习惯，甚至把 Agent A 中间的错误假设当成事实来使用。有一次我在日志里发现 Agent B 输出了一个 Agent A 在第三步生成的中间猜测值，而那个值后来已经被 Agent A 自己纠正过了——信息不是简单的拼接，而是上下文窗口内所有文本共同影响输出分布，被纠正过的错误信息依然在对话里，依然会影响模型。

这个坑的解法是：串行协作时只传递最终结果，不传递过程历史。Agent A 的执行过程是它的私有空间，Agent B 只需要知道"Agent A 得到了什么结论、置信度是多少、数据来源是什么"。如果你需要 Agent B 了解执行轨迹，交给日志系统，不要交给上下文窗口。

4.2 重复劳动：每个 Agent 都在做别人的事

第二个坑更有意思。我原本设计了一个"调度者-执行者-校验者"的三角色结构，想法很美，但在实际跑起来的时候，执行者经常自作聪明地做校验者的工作——它会在输出里附带一句"经检查，以上结果没有问题"。而校验者也不甘示弱，它开始重新执行一遍任务去验证结果，而不是基于执行者的产物做检查。

这听起来像是模型的"主动性强"，但放在工程里就是灾难。重复劳动不仅增加 token 成本和延迟，更关键的是模糊了责任边界——一旦最终结果出错，你根本不知道是哪一个环节出的问题。

解决办法是想清楚了角色的"信息差"。三个 Agent 看到的信息刻意做得不一样：

• 调度者：用户的目标 + 全局任务清单
• 执行者：被分配的子任务 + 明确的产出模板
• 校验者：执行者的产出 + 校验规则列表 + "只检查，不重做"的硬约束

提示词里我加了这样一句硬约束，实测效果明显："你不需要重新执行任何任务，你只负责根据校验规则对给定的产出进行检查，输出 PASS 或 FAIL 以及原因。任何超出校验规则的内容都不允许出现在你的回复中。"

一个角色只保留完成本职所需的最小信息量，这是多 Agent 协作里我学到最重要的一课。

4.3 校验缺失：没有检查环节，AI 就是批量生产幻觉的流水线

我在早期版本里其实没有设计独立的校验环节。当时的想法是：模型在循环过程中已经设置了反思机制，理论上会把错误的输出自己纠回来。但后来发现这种假设有个致命漏洞——模型在"反思"时和它"犯错"时是同一个脑子，反思很难跳出自己犯错的路径依赖。就像一个人写代码写了半天检查不出 bug，旁边人看一眼就发现了，因为你在自己习惯性的思维方式里看不到自己的盲区。

后来的架构里我加了一个独立校验器，它和任务执行器共享模型的调用方式，但提示词里不包含任何任务背景，只包含校验规则和输入产物。这个校验器有三大类检查项：

1. 结构检查：各项字段是否齐全、格式是否符合预期（JSON Schema）。
2. 事实一致性检查：输出中是否有与输入上下文明显矛盾的陈述，特别是数字、日期、引用。
3. 安全低位检查：是否包含明显超出任务边界的输出（比如询问用户隐私、尝试执行高危操作）。

如果校验器返回 FAIL，执行器会根据校验意见重新生成一次。这个"重新生成"的机制也很讲究——不是让执行器看一遍校验意见就重新跑，而是把校验意见作为明确的迭代指令，让它知道自己哪一步出了问题。

这个机制跑起来之后，我的项目的端到端成功率提高了大概两成。多花的那点 token 成本换来的是稳定性的指数级提升，这笔账非常划算。

5. 可观测性与质量评估：AI 工程能上生产的前提条件

5.1 每一轮 Agent 交互都要有"行车记录仪"

AI 工程和传统软件的运维有个明显的差异：传统软件的日志是"正常-异常"的二元状态记录，而 AI 工程的日志更像是一个深思的过程记录。我在项目一开始就觉得，如果不记录模型每一次的输入、输出、工具调用结果和校验结论，那整个系统就是一台没有行车记录仪的车——出了问题只能靠蒙。

我的线上日志格式是按"一次完整的 Agent 运行"为单位来组织的：

{ "run_id": "a3f9c1d2-7e4b-4f6a-9e2d-8b7c6a5d4e3f", "task_id": "order_inquiry_001", "agent_chain": ["dispatcher", "executor", "validator"], "steps": [ { "agent": "dispatcher", "input": "用户询问订单状态", "output": "分配订单查询任务给 executor", "tool_calls": [], "latency_ms": 523, "tokens_used": 218 }, { "agent": "executor", "input": "查询订单号 OD20240115", "output": "返回订单状态：已发货，物流单号 SF123456", "tool_calls": ["query_order"], "latency_ms": 812, "tokens_used": 305 } ], "final_output": "您的订单已于 1 月 20 日从仓库发出，物流单号 SF123456，预计 3 天内送达。", "validator_result": "PASS" }

这套日志格式里有三个我比较庆幸的设计。第一个是run_id：一次用户请求对应的完整链路可以全局追踪，试想一下如果多个 Agent 并发运行，没有这个关联键，日志根本没法串起来。第二个是 token 和使用成本的记录：AI 应用和传统应用不一样，每次交互都要花钱，没有成本意识很容易月底收到一张天价账单。第三个是validator_result：把校验结论存下来，方便做回归分析——你可以回溯那些"校验通过但用户仍然抱怨"的 case，进一步优化校验规则。

5.2 质量评估：没有度量就无法迭代

我见过不少 AI 项目的迭代方式是"感觉不行了，调一下提示词试试"，这种方式的效率太低了。要让 AI 工程持续改进，必须把质量的评估量化。但"量化"不是让你给每个输出打个主观分数，而是定义一套可重复、可归因的评估流程。

我给自己的项目设计了四个维度：

这四个维度在迭代中会互相牵制。比如把延迟优化上去，可能牺牲了事实准确率；把事实准确率拉上去，可能又拖慢了端到端成功率。所以我每周都会拉出这几个指标做一次对比，用数据决定下一轮优化方向，而不是拍脑袋。

5.3 评估集的构建：先把"标准答案"找出来

可能有人会问："输出质量好还是坏，标准答案从哪来？"确实，很多 AI 任务没有一个唯一正确的答案，但在一个具体的业务场景里，你是可以建立一个"参考标准"的。我在项目中做的是：从真实用户请求里抽样 100 条，自己人工写一份"这条请求最理想的处理结果应该是什么"，然后让 AI 去执行这 100 条测试用例，计算命中率。

这个方式的一个小技巧是：不要只看最终答案是否一致，还要看中间步骤是否合理。比如一条"比较两个方案优劣"的任务，如果模型连比较的维度和权重都没抓对，即使最终结论碰巧和标准答案一致，也不算好结果。把评估维度拆细一点，你才能知道该改哪里。

评估集还有一个迭代机制：每当线上出现一个"用户反馈不好但指标却通过"的案例，我就会把这条用例加进评估集，作为回归测试的一部分。这样评估集会越来越贴近真实业务需求，系统的质量也会跟着明显提升。

6. 工程化落地的最终拼图：轻量化、复用与成本控制

6.1 把 AI 能力封装成"功能开关"，而不是"定制脚本"

当初做 from scratch 的另一个动机，是希望自己搭的这套东西能像乐高积木一样复用，而不是为了一个任务临时写死一套流程。所以在项目后期，我把整个体系抽象成了三个可以独立替换的层级。

第一层是模型层：所有对话都走同一个封装好的LLMClient，换模型厂商时只需要改配置，完全不用动业务代码。第二层是能力层：每个 Agent 不再是"一个 Python 脚本"，而是"一个带输入输出协议、带质量自检逻辑的独立服务单元"，可以被不同的上游任务复用。第三层是流程层：Dispatcher 根据任务类型选择组合哪些 Agent，这个选择逻辑本身是一份可配置的 YAML 而不是硬编码的 if-else。

# workflow_config.yaml 示例 workflows: order_inquiry: description: "订单查询处理流程" stages: - agent: intent_classifier config: model: "gpt-4o-mini" temperature: 0 - agent: order_query_executor config: model: "gpt-4o-mini" temperature: 0 - agent: response_formatter config: model: "gpt-4o" temperature: 0.3 fallback: agent: human_handoff

为什么把流程做成配置而不是代码？因为在实际迭代中我发现，每次调整 Agent 组合方式都要重新部署代码，太蠢了。业务方说"我想让这个任务先经过一轮敏感信息过滤再进入分类器"，如果流程写死在代码里，一次简单的变更就要走整套发布流程；如果流程是配置，只需要改一行 YAML 即可。而且把"配置"和"代码"分开后，非技术同事也能在一定程度上参与流程调整。

6.2 模型选型：大模型干小活，小模型干杂活

成本控制是我在 from scratch 项目中最深刻地感受到"工程和 Demo 的区别"的地方。一个 Demo 级 AI 应用，你直接选能力最强的大模型就完事了，跑一次几毛钱也不心疼。但一旦进入生产环境，每天几千次调用，大模型和小模型的成本差距会呈几何级放大。

我的选型原则很简单：简单任务用便宜的小模型，复杂任务才让大模型上。一个订单分类和意图识别任务，用 mini 级别的模型完全够用；而复杂的 Agent 调度、策略判断，才需要旗舰模型出手。听起来很理所当然对吧？但很多项目在一开始就把所有任务都丢给同一个最强模型，等账单出来才知道肉痛。

还有一个没那么明显的好处：小模型在特定任务上的表现不一定比大模型差。这里有个经验规律是——任务越聚焦（边界清晰、输入输出格式固定），小模型通过良好 prompt 设计就越能接近大模型的效果；任务越开放（开放域对话、长程推理、创造力），大模型优势越明显。所以我会针对不同类型的任务分别测试几个候选模型的准确率和成本，用数据做选型决策。

6.3 一步步跑通的路径：我的最小可行闭环

很多读者可能会觉得上面讲得太多，自己想要一个可以直接照做的最小路径。这里我给一个从零开始快速验证 AI 工程闭环的五步方案：

1. 选一个高价值的单任务：比如"客服工单自动分类"，不要一上来就想着做全链路助理，单任务容易度量，也容易快速见效。
2. 手工构造 50-100 条测试集：包含典型场景和边界情况，标注好期望的输出结构。
3. 基于自身的需求设计提示词：应用我第二部分的信息结构公式，跑通最小调用，用测试集量一下准确率基线。
4. 接一个真实的工具调用：哪怕只是查询一个静态数据库，把 Agent 循环跑起来，验证"调用-入-入-出"的闭环。
5. 建立日志和评估机制：把每一步的输入输出记下来，定时跑一次测试集，看指标在提示词调整后的变化。

这个五步路径的精髓是"尽快让整个体系跑起来，然后让数据驱动你迭代"。我第一次跑通这个闭环花了大概两天，之后所有的改进都有数据支撑，效率比之前"凭感觉调提示词"高出一大截。

7. 最后说点自己的体会

如果让我给后来者一句最大的忠告，那就是：别把 AI 工程想得太玄，也别把现成框架想得太神。模型本身的能力已经被行业验证了，真正的差异化在于你怎么设计信息结构、怎么构建 Agent 循环、怎么建立反馈和评估机制。这些能力不依赖于某个特定工具，而来源于你对业务逻辑和模型特性的双重理解。

我踩过的最深的坑，是在项目一开始过度迷恋"用最前沿的框架 + 最多参数的工具"能一步到位。事实是，一个从零写出来、只有两三百行的 Agent 循环，加上精心设计的提示词和校验环节，稳定性和可维护性完胜那些叠了一堆抽象层的复杂系统。做 AI 工程的正确姿势，是先把最小核心跑通，然后让每一层都成为你能完全掌控的、透明的、可度量的存在。

这套思路的扩展空间也很大——我在最近的工作中已经尝试把多个工作流组合成一个更复杂的业务系统，底层的 Agent 单元全部复用之前搭好的那批。稳定的地基一旦打好，上面盖多少层楼都不慌。希望这篇记录能帮你少走我走过的那些弯路。