1. 为什么我要从零搭一套资料汇编的 Agent 编排架构
做历史专题资料汇编这件事，听起来像是文科生的活儿，但真正干过一轮的人都知道，它本质上是一个信息工程问题。我前后接手过三个类似的项目，从地方史志的专题整理，到某个行业口述史的素材归集，再到一个跨机构档案的索引重建，每一次都踩在同一个坑里：资料散落在几十个来源里，格式五花八门，时间线互相打架，同一件事在不同材料里的表述能差出十万八千里。人工整理不是不行，但成本高得离谱，而且一旦资料量过千条，人的注意力就会断崖式下降，错漏率飙升。
所以这次我决定换个思路，不再把它当成一个"整理任务"，而是当成一个"编排问题"。核心想法很简单：把资料汇编拆成若干个可以独立执行、又能串起来的环节，每个环节交给一个专门的 AI Agent 去处理，中间用一套调度逻辑把它们串成流水线。这就是标题里说的"AI Agent 编排架构"。
需要先说明一点，我这里说的 Agent，不是那种科幻电影里全知全能的智能体，而是指"带明确职责边界、有固定输入输出格式、可以被反复调用"的处理单元。它可能是一个提示词模板，也可能是一段带工具调用的脚本，甚至可能只是一个规则引擎。关键不在于它多聪明，而在于它职责单一、结果可预期、失败可定位。
这套架构能解决什么问题？最直接的是三件事：第一，把重复性的清洗、分类、去重工作自动化，人只处理真正需要判断的部分；第二，让每一步的处理过程可追溯，出了问题能定位到具体环节；第三，让整个流程可以增量运行，新资料进来不用从头再来一遍。
适合谁来参考？如果你手头有几百到几万条不等的资料需要整理，不管是历史专题、行业调研、竞品分析还是文献综述，这套思路都能直接套用。不需要你是算法工程师，但需要你对整个资料的结构有基本判断，知道哪些环节可以交给机器，哪些必须人来把关。
我前后跑了六轮真实任务，每一轮都暴露了新问题，也逼着我改架构。下面就把这六轮里沉淀下来的东西，从设计思路到实操细节，完整拆一遍。
2. 整体架构设计与六轮迭代的取舍逻辑
2.1 为什么是"编排"而不是"一个大模型搞定"
最开始我也想过偷懒，直接把所有资料丢给一个大模型，让它一次性输出整理好的汇编。试了一轮就放弃了，原因有三个。
第一是上下文长度和成本。历史专题资料动辄几十万字，一次性塞进去，要么超限，要么成本高到不可接受，而且模型对长文本中段的注意力会明显衰减，越靠后的资料处理质量越差。
第二是错误不可定位。一次性输出意味着中间过程是个黑盒，如果最终结果里某条时间线错了，你根本不知道是原始资料的问题、清洗的问题，还是模型理解的问题。排查成本极高。
第三是无法增量。新资料进来，你得把整个流程重跑一遍，之前的人工校对成果全部作废。
所以"编排"的核心价值就出来了：把一个大问题拆成一串小问题，每个小问题单独可控、单独可测、单独可替换。这跟软件工程里拆微服务的逻辑是一样的，只不过这里的"服务"是 AI 处理单元。
2.2 六轮迭代的架构演进
我把六轮任务按时间顺序理了一下，每一轮解决的核心矛盾和遗留的问题都列在下面，这样你能看到架构是怎么一步步长出来的。
| 轮次 | 核心目标 | 架构形态 | 暴露的主要问题 |
|---|---|---|---|
| 第一轮 | 验证可行性 | 单 Agent 串行处理 | 错误不可定位，长文本质量衰减 |
| 第二轮 | 拆分环节 | 三 Agent 流水线 | 环节间格式不统一，衔接处丢信息 |
| 第三轮 | 统一数据契约 | 引入中间数据结构 | 契约设计过重，小任务跑不动 |
| 第四轮 | 增加校验层 | 处理+校验双轨 | 校验规则太死，误杀大量有效数据 |
| 第五轮 | 引入人工回环 | 人机协同节点 | 人工介入点太多，效率反而下降 |
| 第六轮 | 动态编排 | 按资料类型分流 | 调度逻辑复杂，维护成本上升 |
这张表看着简单，但每一行背后都是一次完整的重跑和复盘。我重点说几个关键转折。
第二轮引入流水线之后，最大的坑是环节之间的数据格式不统一。清洗 Agent 输出的是一种结构，分类 Agent 期望的是另一种结构，中间就得加一层转换，转换本身又可能出错。这个问题在第三轮通过"数据契约"解决了，也就是所有 Agent 的输入输出都遵循同一套字段定义。
但第三轮的契约设计又走过了头，字段定义得特别细，结果处理小批量资料时，光是构造和校验契约的开销就超过了处理本身。第四轮我做了精简，只保留最核心的字段，其余用可选字段承载。
第四轮的校验层是个双刃剑。加了校验之后，确实拦住了不少错误，但校验规则写得太死，把很多"表述不同但意思正确"的数据也判成了错误。后来我把校验从"硬规则"改成"打分+阈值"，低于阈值的才进人工队列，误杀率一下就降下来了。
第五轮的人工回环，一开始我设计了三个人工介入点，结果发现人工成了瓶颈。第六轮砍到只剩一个关键介入点，就是最终汇编前的语义一致性审核，其余全部自动化。
2.3 最终架构的分层
跑到第六轮，架构基本稳定成四层，我用文字描述一下这个分层，你可以对照自己的场景调整。
最底层是接入层，负责把各种来源、各种格式的原始资料统一读进来，转成纯文本加元数据的标准形态。这一层不涉及任何智能处理，纯粹是格式转换和编码统一。
往上是处理层，由若干个职责单一的 Agent 组成，包括清洗 Agent、切分 Agent、抽取 Agent、分类 Agent、去重 Agent。每个 Agent 只干一件事，输入输出都遵循数据契约。
再往上是校验层，对处理层的输出做质量打分，包括完整性校验、一致性校验、格式校验。打分低于阈值的进入待人工队列。
最上面是编排层，负责调度整个流程，决定哪些资料走哪条路径，处理失败怎么重试，人工队列怎么消费。
这个分层的好处是，每一层都可以单独替换。比如你觉得清洗 Agent 效果不好，换一个就行，不影响其他层。这也是我最终没有选择"一个大模型搞定"的根本原因。
3. 核心环节的细节拆解与实操要点
3.1 数据契约：整个架构的地基
数据契约这个词听着唬人，其实就是规定好每个环节之间传递的数据长什么样。我踩过的最大坑就是没早点定契约，导致前两轮的数据在环节之间来回转换，转一次丢一点信息。
我的契约核心字段就六个，其余都是可选的：
doc_id：资料唯一标识，用来源加序号的组合生成，保证全局唯一raw_text：原始文本，不做任何修改，保留最原始形态clean_text：清洗后的文本，去掉了页眉页脚、乱码、重复空行segments：切分后的段落列表，每个段落带位置索引entities：抽取出的实体，包括时间、人物、地点、事件meta：元数据，包括来源、采集时间、原始格式
这里有个关键决策：为什么保留 raw_text。因为清洗环节一定会引入误差，如果只保留清洗后的文本，一旦发现清洗把有用信息删了，就没法回溯。保留原始文本，等于给整个流程留了一条退路。这个字段占的存储空间不小，但绝对值。
提示：契约字段不要一次性设计太全。我第三轮就是吃了这个亏，字段多到二十几个，结果大部分环节根本用不上，反而增加了维护负担。先定核心字段，用起来之后再按需扩展。
3.2 清洗 Agent 的边界在哪里
清洗 Agent 最容易失控，因为它面对的是"脏数据"，而"脏"的定义很模糊。我第一版的清洗规则写了三十多条，结果把很多有价值的内容也清掉了。
后来我给自己定了一条铁律：清洗只做"确定性删除"，不做"判断性删除"。什么意思？页眉页脚、连续空行、明显的乱码字符、重复的标点，这些是确定性删除，删了不会错。但像"疑似无关段落""疑似重复内容"这种需要判断的，一律不删，交给后面的环节处理。
清洗 Agent 的实操流程我固定成四步：
- 编码统一，全部转成 UTF-8，处理掉 BOM 头
- 去除结构性噪声，包括页眉、页脚、页码、水印文字
- 规范化空白字符，连续空行压成一个，行首行尾空格去掉
- 标点规范化，全角半角统一，连续标点合并
每一步都记录处理日志，删了多少字符、删了什么类型，全部留痕。这样一旦发现清洗过度，能快速定位是哪一步的问题。
3.3 切分 Agent：颗粒度决定一切
切分这件事，颗粒度选错了，后面全白搭。切得太粗，一个段落里混了好几个主题，抽取和分类都会受影响；切得太细，语义被割裂，去重和一致性校验会误判。
我试过三种切分策略，最后定的是按语义边界切分，辅以长度约束。具体做法是，先按自然段切，然后对超过阈值的段落，用标点和连接词找次级边界再切。阈值我定的是 500 字，超过就考虑二次切分，但切分点必须落在句号、分号或者明显的转折词之后。
这里有个经验：历史类资料的时间线往往跨段落，如果切分点正好落在时间描述中间，会导致时间实体抽取失败。所以我在切分时会做一个检查，如果切分点前后 50 字内出现了年份、朝代、月份这类时间词，就往后延到下一个安全边界。
切分后的每个 segment 都带一个位置索引，格式是doc_id + 段落序号，这样后续任何环节出问题，都能定位到原文的具体位置。
3.4 抽取 Agent：实体识别的准确率怎么提
抽取 Agent 负责从文本里把时间、人物、地点、事件这些结构化信息捞出来。这是整个流程里对模型能力要求最高的环节，也是最容易出错的环节。
我的做法是分类型抽取，而不是一次性全抽。时间、人物、地点各用一个专门的提示词模板，事件抽取单独一套。为什么分开？因为不同类型的实体，识别逻辑差别很大。时间主要靠模式匹配加上下文判断，人物主要靠命名实体识别，事件则需要理解语义关系。混在一起抽，模型容易顾此失彼。
时间抽取是最麻烦的。历史资料里的时间表述极其不规范，有"光绪年间"这种朝代纪年，有"民国二十三年"这种纪年，还有"上世纪三十年代"这种模糊表述。我的处理方式是建一个映射表，把朝代纪年、干支纪年统一转成公历年份区间，模糊表述则保留原文并标注为"模糊时间"。
注意：抽取结果一定要保留原文片段和位置。我见过太多人只存抽取出的实体，不存出处，结果后面想核对都没法核对。每个实体都要带
source_span，记录它在原文里的起止位置。
3.5 去重 Agent：相似不等于重复
去重是资料汇编里最容易被低估的环节。历史资料里同一件事往往有多个版本，表述不同但说的是同一件事。如果简单按文本相似度去重，会把很多有价值的"异文"也删掉。
我的策略是分级去重。第一级是精确去重，文本完全一致的直接合并。第二级是近似去重，相似度超过 0.95 的合并，但保留所有版本作为"异文"。第三级是语义去重，相似度在 0.7 到 0.95 之间的，不自动合并，而是标记为"疑似重复"，进入人工队列。
相似度计算我用的是字符级和词级结合的方式，字符级用编辑距离，词级用分词后的 Jaccard 相似度，两个分数加权。权重我调了几次，最后定的是字符级 0.4、词级 0.6，因为历史资料的用词差异往往比字形差异更能说明问题。
3.6 分类 Agent：标签体系怎么定
分类 Agent 负责给每条资料打标签，方便后续按主题汇编。标签体系的设计直接决定了最终汇编的结构。
我的做法是先定一级标签，再让资料自己长出二级标签。一级标签是人工定的，比如"政治""经济""文化""军事""社会"这几大类，数量控制在十个以内。二级标签不预设，而是让分类 Agent 在处理过程中聚类生成，然后人工审核确认。
这样做的好处是，标签体系是"长"出来的，而不是"拍脑袋"定的，更贴合资料的实际分布。缺点是前期需要人工审核聚类结果，但相比预设一套可能根本不匹配的标签体系，这个成本是值得的。
分类 Agent 的输出除了标签，还要带一个置信度分数。置信度低于阈值的，进入人工队列。阈值我定的是 0.7，低于这个分数的分类结果，人工复核的收益大于成本。
4. 完整实操流程与关键环节实现
4.1 环境准备与依赖清单
这套架构对运行环境的要求不高，一台普通的开发机就能跑起来。我用的技术栈比较朴素，核心就是 Python 加几个常用库。
# 核心依赖 python >= 3.10 pandas # 数据处理 jieba # 中文分词 python-Levenshtein # 编辑距离计算 scikit-learn # 聚类和相似度 pyyaml # 配置文件解析模型调用部分，我用的是通用的文本处理接口，具体用哪家可以根据自己的情况选。关键是要支持批量调用和失败重试，因为资料量大，单条调用效率太低。
目录结构我固定成下面这样，每个环节的输入输出都放在对应目录，方便排查：
project/ data/ raw/ # 原始资料 cleaned/ # 清洗后 segmented/ # 切分后 extracted/ # 抽取后 classified/ # 分类后 final/ # 最终汇编 logs/ # 处理日志 config/ # 配置文件 agents/ # 各 Agent 实现 orchestrator/ # 编排逻辑4.2 编排层的调度逻辑
编排层是整个架构的大脑，它决定每条资料走哪条路径。我的调度逻辑是基于资料类型和状态的，不是简单的顺序执行。
每条资料进来，先判断类型。纯文本的直接进清洗，带表格的先做表格解析，带图片的先做 OCR。然后根据当前状态决定下一步。状态机大概是这样：
raw -> cleaned -> segmented -> extracted -> classified -> validated -> final | | | v v v 人工队列 人工队列 人工队列任何一步失败或者置信度低于阈值，就进人工队列，人工处理完再回到主流程。这个状态机我用一个简单的字典实现，每个状态对应一个处理函数，处理完更新状态。
重试逻辑也很关键。模型调用失败是常态，我的重试策略是指数退避，最多三次。第一次失败等 2 秒，第二次等 4 秒，第三次等 8 秒，三次都失败就标记为"待人工"，不再自动重试。
4.3 清洗环节的代码实现
清洗环节我写成了一个独立的函数，输入原始文本，输出清洗后文本和处理日志。
import re def clean_text(raw_text): log = {"removed_chars": 0, "steps": []} # 第一步：编码规范化 text = raw_text.encode('utf-8', errors='ignore').decode('utf-8') # 第二步：去除页眉页脚（基于常见模式） patterns = [ r'第\s*\d+\s*页', # 页码 r'共\s*\d+\s*页', # 总页数 r'^\s*-\s*\d+\s*-\s*$', # 页码变体 ] for p in patterns: text, n = re.subn(p, '', text, flags=re.MULTILINE) log["removed_chars"] += n # 第三步：空白规范化 text = re.sub(r'\n{3,}', '\n\n', text) text = re.sub(r'[ \t]+', ' ', text) # 第四步：标点规范化 text = text.replace('，', '，').replace('。', '。') text = re.sub(r'([。！？])\1+', r'\1', text) return text, log这段代码看着简单，但每一步都有讲究。比如编码规范化那一步，用errors='ignore'是为了处理掉无法解码的字符，而不是让整个流程崩掉。页眉页脚的去除用的是模式匹配，而不是固定字符串，因为不同来源的页码格式不一样。
实操心得：清洗日志一定要记。我一开始没记日志，后来发现某批资料清洗后少了一大段，根本不知道是哪一步删的。加上日志之后，同样的问题五分钟就定位了。
4.4 抽取环节的提示词设计
抽取环节的效果，八成取决于提示词。我试了很多版本，最后稳定下来的提示词结构是这样的：
你是一个历史资料信息抽取助手。请从下面的文本中抽取指定类型的信息。 抽取类型：{entity_type} 文本内容：{text} 要求： 1. 只抽取文本中明确出现的信息，不要推断 2. 每个抽取结果必须附带原文片段 3. 如果文本中没有该类型信息，返回空列表 4. 输出格式为 JSON，字段包括 value、source_span、confidence 输出示例： {"entities": [{"value": "光绪二十三年", "source_span": "光绪二十三年春", "confidence": 0.95}]}这个提示词的关键在于约束输出格式和要求附带原文。约束格式是为了后续环节好处理，要求附带原文是为了可追溯。confidence 字段是让模型自己评估把握程度，低于阈值的进人工。
实测下来，加了 source_span 要求之后，抽取的准确率有明显提升，因为模型在生成 source_span 的过程中，相当于做了一次自我校验。
4.5 校验层的打分机制
校验层不直接判断对错，而是打分。我设计了三个维度的分数：
- 完整性分：必填字段是否齐全，缺失扣分
- 一致性分：抽取的实体之间是否矛盾，比如时间线是否自洽
- 格式分：输出是否符合契约定义
三个分数加权得到总分，权重分别是 0.4、0.4、0.2。总分低于 0.6 的进人工队列，0.6 到 0.8 的标记为"待复核"，0.8 以上的直接通过。
一致性分的计算是最复杂的。我主要检查两类矛盾：时间矛盾和实体矛盾。时间矛盾是指同一事件在不同资料里的时间对不上，实体矛盾是指同一人物在不同资料里的身份描述冲突。这两类矛盾是历史资料里最常见的错误来源。
4.6 人工回环的设计
人工回环是整个流程里最需要克制的部分。我第五轮设计了三个人工介入点，结果人工成了瓶颈，整个流程的吞吐量被人工环节卡死。第六轮砍到只剩一个，就是最终汇编前的语义一致性审核。
这个审核点的工作内容是：检查自动汇编的结果里，有没有明显的逻辑矛盾、时间线断裂、主题归类错误。人工只需要看汇编的目录结构和关键节点，不需要逐条核对。这样人工的工作量从"处理所有异常"降到"审核最终结果"，效率提升非常明显。
人工审核的结果会反馈回系统，作为后续自动处理的参考。比如人工把某条资料从"经济"类改到了"社会"类，这个修改会被记录，下次遇到类似资料时，分类 Agent 会参考这个先例。
5. 六轮任务里踩过的坑与排查技巧
5.1 常见问题速查表
六轮跑下来，遇到的问题基本可以归成几类。我整理成表格，方便对照排查。
| 问题现象 | 可能原因 | 排查方向 | 解决方法 |
|---|---|---|---|
| 清洗后文本大量缺失 | 清洗规则过激 | 查看清洗日志 | 放宽规则，改为标记而非删除 |
| 切分后语义断裂 | 切分点落在语义中间 | 检查切分点上下文 | 增加时间词保护逻辑 |
| 抽取结果为空 | 提示词约束过严 | 检查提示词和输入 | 放宽约束，增加示例 |
| 去重误删有效资料 | 相似度阈值过低 | 检查相似度分布 | 提高阈值，增加人工确认 |
| 分类结果集中 | 标签体系不合理 | 查看标签分布 | 调整一级标签，重新聚类 |
| 流程卡住不动 | 某环节死循环 | 查看状态机日志 | 增加超时和重试上限 |
| 人工队列积压 | 阈值设置过严 | 统计各环节进人工比例 | 调整阈值，减少人工介入 |
5.2 三个最坑的问题复盘
第一个坑：清洗把时间信息删了。有一批资料的页眉里带了年份信息，我的清洗规则把页眉整个删掉，结果年份也没了。后来我改成，清洗前先做一次时间信息预抽取，把时间存下来，清洗后再合并回去。这个改动之后，时间信息的完整率从 70% 提到了 95%。
第二个坑：去重把异文删了。同一件事有两个版本，一个详细一个简略，相似度算下来 0.92，被自动合并了。但那个简略版本里有一个详细版本没有的细节。后来我把去重策略改成，相似度超过 0.95 才自动合并，0.85 到 0.95 之间的标记为"异文"保留，不合并。这样既去了重，又保住了异文。
第三个坑：分类标签越用越多。分类 Agent 跑了几轮之后，二级标签膨胀到两百多个，很多标签只对应一两条资料，完全失去了分类的意义。后来我加了一个标签合并环节，把出现次数少于三次的标签合并到上级标签，标签数量控制在五十个以内。
5.3 独家避坑技巧
跑完六轮，我总结了几个文档里不会写、但实际特别有用的技巧。
技巧一：先跑小样本，再跑全量。每轮任务我都先拿 50 条资料跑一遍完整流程，看看各环节的通过率和人工介入比例。如果小样本的人工介入比例超过 20%，说明阈值设置有问题，先调阈值再跑全量。这个习惯帮我省了大量时间。
技巧二：给每个环节设一个"熔断阈值"。如果某个环节的失败率超过 30%，自动暂停整个流程，而不是继续往下跑。因为上游环节失败率高，下游环节的结果基本没有参考价值，继续跑只是浪费资源。
技巧三：人工队列要按优先级排序。不是所有进人工队列的资料都一样重要。我按"影响范围"排序，影响最终汇编结构的排前面，只影响单条资料展示的排后面。这样人工时间花在刀刃上。
技巧四：保留每一轮的中间结果。我每一轮任务的每个环节输出都单独存一份，带时间戳。这样对比不同轮次的效果时，能直接看到改动带来的差异。这个习惯在调参的时候特别有用。
技巧五：模型调用要做缓存。同一段文本可能被多个环节调用，如果每次都重新调模型，成本会翻好几倍。我加了一层缓存，key 是文本的哈希值，value 是模型输出。缓存命中率大概在 40% 左右，成本直接降了一半。
6. 架构的可扩展性与后续演进方向
6.1 什么情况下该扩展，什么情况下该收手
这套架构跑通之后，很容易陷入"什么都想加"的陷阱。我给自己定了一条判断标准：只有当某个环节的人工介入比例持续超过 15%，才考虑为它单独增加自动化处理。低于这个比例，人工处理反而更划算。
比如我一度想给抽取环节加一个专门的"模糊时间解析"模块，但统计下来，模糊时间只占全部时间的 8%，人工处理完全扛得住，就没加。后来资料类型变了，模糊时间占比升到 20%，我才补上这个模块。
6.2 可以复用的部分
这套架构里，有几个部分是高度可复用的，换个领域基本不用改。
数据契约的设计思路可以直接搬，字段名改改就行。清洗 Agent 的四步流程是通用的，任何文本清洗都能用。校验层的打分机制也是通用的，改改权重和阈值就能适配新场景。编排层的状态机逻辑更是通用，只要环节定义清楚，状态机不用动。
需要改的主要是抽取和分类环节，因为这两个环节跟领域知识强相关。历史资料的实体类型和标签体系，跟其他领域完全不一样，这部分必须重新设计。
6.3 后续可以尝试的方向
如果这套架构要继续演进，我觉得有三个方向值得试。
第一个是引入主动学习。现在的人工审核结果只是被动记录，没有反馈到模型。如果能把人工修改的案例作为少样本示例，动态注入到提示词里，抽取和分类的准确率应该还能再提一截。
第二个是增加跨文档的关联分析。现在的处理是逐条进行的，没有考虑资料之间的关系。如果能加上跨文档的实体链接和事件关联，最终汇编的质量会高很多，尤其是时间线的重建。
第三个是把编排逻辑可视化。现在调度逻辑是写在代码里的，改起来要动代码。如果能把状态机和调度规则抽成配置文件，甚至做成可视化界面，维护成本会低很多。
我在实际使用中发现，这套架构最大的价值不在于它多智能，而在于它把"不可控的大问题"拆成了"可控的小问题"。每一个环节单独看都很朴素，但串起来之后，整个流程的稳定性和可维护性比"一个大模型搞定"高出一个量级。踩过几次坑之后我越来越确信，做资料汇编这种事，工程化的思路比追求模型能力更重要。最后再分享一个小技巧：每次调整架构之前，先把当前版本的中间结果完整备份一份，这样万一改坏了，还能退回去对比。这个习惯帮我避免了好几次"改完发现还不如不改"的尴尬。
