构建廉价且正确的 Agent 检索知识库:Claude Managed Agents 的 knowledge-wiki 实战指南
构建廉价且正确的 Agent 检索知识库:Claude Managed Agents 的 knowledge-wiki 实战指南
本指南讲解 claude-quickstarts 仓库中 managed-agents/knowledge-wiki 的完整用法:它演示了如何把一份"缓慢变化、会被 Agent 反复查询"的文档语料(以真实 M&A 数据室为工作示例)一次性读入一个由 Claude Managed Agents 记忆存储支撑的纯 Markdown 知识维基(knowledge wiki),此后所有问答都从维基作答而非重读原始文档。读完本文,你将掌握语料装配、格式归一化、并行抽取、问题消解、Dreaming 合并与只读查询的完整流水线,以及如何评估该模式在成本与正确性上的收益。
一、核心思路:把"阅读税"一次性付清
当 Agent 通过检索文档语料来回答问题时,每一次提问都要重新付出"阅读税"——把原始文档重新喂给模型、重新理解、重新提取。knowledge-wiki 的思路恰恰相反:
语料只读一次,蒸馏成一个 knowledge wiki(Managed Agents 记忆存储中的纯 Markdown),之后所有问题都从 wiki 作答,而不是重读文档。
由此得到的直接收益是:每次回答的成本只有原始文档检索的一个零头,且每条事实都带有出处(provenance)。该模式适用于任何"变化缓慢、被反复查询"的语料:
- M&A 尽职调查(本项目的完整工作示例);
- 法律取证(legal discovery);
- 面向产品文档的客服支持。
仓库主文档(README.md)明确给出了成本量级:默认 mini 档从端到端约 $35 / 1 小时,更小的 quickstart 档约 $25 / 40 分钟;两个数字来自仓库已提交的真实运行记录,会随模型选择、语料与 API 定价变化。
二、工作示例:一份真实的 42 份 SEC 文件数据室
工作示例不是合成数据,而是一笔真实完成、已交割的私有化交易:Squarespace, Inc.(CIK 1496963)2024 年 Permira 私有化。语料为 42 份公开 SEC 申报文件,覆盖从交易宣布到交割的 11 个月。
选择它的原因在文档中有明确交代:公开可获取、具有值得映射的叙事结构,而且在最大程度上具备对抗性——中途变化的价格、外观相似的壳实体(shell entities)、代号、以及只存在于图表中的数字。这意味着知识维基必须处理:
- 实体消解(同名/近似名的不同实体);
- 时间线覆盖(同一事实被后续文件修订/取代);
- 图表内数值的提取;
- 内部文档与申报文件之间的冲突检测。
所有文档都通过 accession number 从 SEC EDGAR 实时抓取,仓库不转发任何原始内容。此外,两个小型合成文件(在文件自身文本中明确标记为 synthetic)扮演真实交易室内内部文档的角色,其中一份故意与申报文件冲突——你可以观察到维基如何捕捉并处理该冲突。
语料清单(仓库内文件)
| 文件 | 作用 |
|---|---|
distill_documents_into_knowledge_wiki.ipynb |
主菜谱(cookbook),自上而下运行 |
build_manifest.py |
查询 SEC EDGAR,写出分档的文档清单(manifest) |
fetch_data_room.py |
按档下载申报文件并转换为带出处标记的文本 |
fetch_real_deck.py |
下载真实的董事会 deck(13E-3 附件中的扫描幻灯片)并拼成 PDF |
make_analyst_docx.py |
生成标记为合成的 Word 分析师简报 |
utilities.py |
会话轮询辅助函数 |
example_data/ |
合成伴生文件(分析师简报、厂商 CSV) |
三、八步流水线:从语料到可查询的维基
以下是 README 中给出的完整步骤(notebook 会逐一展开),也是整篇文章的骨架:
- 装配语料(Assemble your corpus):收集 Agent 会反复查询的文档——数据室、取证集、支持知识库。工作示例从公开申报文件中抓取了一个真实的 M&A 数据室。
- 将每种文件类型归一化为带出处标记的文本(Normalize):把 PDF、Word、表格、邮件、幻灯片各自路由到纯文本,并加上
[SOURCE: …]头;遇到不支持的格式要大声失败——一个静默跳过的加载器会让维基"看起来完整,实际上不完整"。 - 并行抽取进一个共享记忆存储——那个存储就是维基(Extract):将语料分批,每批开一个并发的 Agent 会话,每个会话向存储写入结构化笔记。把笔记 schema 放在存储的 attachment instructions 上,并让每份源文档拥有独立的单写者路径(single-writer path),使并发会话互不覆盖。
- 在合并前消解维基的开放问题(Resolve):让一次 pass 交叉阅读维基,关闭抽取遗留的开放问题;确实缺失的内容标记为"已确认不可解"(confirmed-unresolvable),绝不猜测。
- 用一次受控的 Dream 进行合并(Consolidate):Dreaming 是服务端合并 pass——"睡眠时计算":它读取各构建会话的记录和存储,然后写出一个重新组织过的新存储:去重后的实体、把探索式读取变成一次查找的索引、排序后的升级(escalations)文件、修复后的链接。它从不接触原始语料——因此维基中一切为真的事实,都是在抽取阶段赢得的。
- 每次提问从全新会话以只读方式查询(Query):以只读方式挂载合并后的存储,要求每条事实都带出处,并把未命中行为写成脚本("数据室里没有"——点名需要补上的文档,绝不猜测)。
- 运营:定期对真实使用记录做 Dream(Operate):积累足够真实查询后,把工作记录与维基一起 Dream,让它围绕用户真正问的内容重组。
- 评估与调优(Evaluate and tune,本包未附带):用评估器按固定评分表给每个交付物打分,再依据失败原因迭代提示文件(抽取规则、存储 schema、分析师指令、Dream 方向盘)。本包不附带评分框架或调优循环——这是你有了自己的语料评分表之后自然的下一步。
四、访问前提:Managed Agents 与 Dreaming 两项能力
在运行前,组织(organization)必须开通两项能力:
- Managed Agents——构建运行所依赖的记忆存储与 Agent 会话;
- Dreaming——一个受控研究预览(gated research preview)。没有它,
POST /v1/dreams会返回 404,notebook 会在第 5 步停止;此前的所有步骤仍可运行。
申请入口为 claude.com/form/claude-managed-agents。Dreaming 不随 PyPI 上的公开 anthropic 包发布,而是打包在专门的预览 SDK 构建中——预览版 onboarding 会在你的组织注册后告知安装方式。验证预览 SDK 是否就位,可用:
python3 -c "import anthropic; print(hasattr(anthropic.Anthropic().beta, 'dreams'))"
打印 False 即意味着 notebook 只能跑到合并步骤之前。
五、快速开始:先让 Claude 带你走一遍
最快的路径是让 Claude 驱动整个设置:
cd managed-agents/knowledge-wiki
claude "walk me through setting up the knowledge-wiki quickstart"
(仓库内 CLAUDE.md 说明:此时应读取并逐步遵循同目录的 skill.md,不要即兴发挥设置过程——SDK 构建、SEC user-agent 与抓取顺序都很关键。)
拿到访问权限并安装预览 SDK 后,也可按下面的步骤手工操作:
pip install -r requirements.txt
export EDGAR_USER_AGENT="your-name your-email" # SEC 要求留下联系方式
python3 build_manifest.py
python3 fetch_data_room.py --tier=mini # 26 份文档,约 0.5 MB 文本
python3 fetch_real_deck.py # 真实董事会 deck 的 6 张幻灯片(约 1 MB)
python3 make_analyst_docx.py
jupyter lab distill_documents_into_knowledge_wiki.ipynb
认证走标准的 Anthropic 凭据链——无参数构造客户端,它自动采用适用于你的 API key、ant auth login 配置文件或 Workload Identity Federation 中的任意一种。
六、依赖与各脚本的源码级细节
依赖清单(requirements.txt)
requirements.txt 的注释揭示了两个关键点:
- 不要
pip install anthropic——含client.beta.dreams的 SDK 构建尚未上 PyPI,需按 README Quickstart 安装研究预览 wheel; openpyxl与python-pptx并非已提交的 EDGAR 运行所需,而是normalize_any()帮助函数处理.xlsx/.pptx语料时的可选依赖——你自己的文档室可能用得上。
httpx>=0.27
python-docx>=1.1
pillow>=10.0
python-dotenv>=1.0
jupyter>=1.0
openpyxl>=3.1 # 处理 .xlsx 语料时使用
python-pptx>=0.6 # 处理 .pptx 语料时使用
build_manifest.py:分档清单的生成逻辑
build_manifest.py 是纯标准库实现,它:
- 以
CIK = "0001496963"查询 SEC submissions 索引,窗口为2024-02-01至2024-11-01; - 区分核心表单(
8-K、DEFM14A、SC 13E3、SC TO-T、SC 14D9等)与背景表单(10-K、10-Q、DEF 14A,取 2023-01-01 之后); - 按文件大小划分档位:核心表单中
> 700KB归standard,否则归mini;超过MAX_STANDARD_BYTES = 10_000_000的大文件归full;每个交易窗口内的8-K(< 3MB)都归mini,因为"每份窗口期 8-K 都在讲述交易故事"; - Form 4(内幕人交易)按大小筛选(
> 12_000字节)且最多收 30 份,mini档最多 4 份,slug 追加 accession 末四位去重; - 最后手工排序
quickstart档:选取"跨文档连通性"最好的约 8 份——合并协议及其修订对、窗口期 8-K、代理声明与两份 Form 4——从而在约 40 分钟的构建里同时覆盖实体消解、时间覆盖与代号识别三种难点。
输出四个清单文件:manifest_quickstart.json、manifest_mini.json、manifest_standard.json、manifest_full.json,其中每份文档含 slug、form、filed、accession、url、bytes、tier 字段(可查看 manifest_mini.json)。
fetch_data_room.py:下载与"带出处标记的文本"转换
fetch_data_room.py 同样是纯标准库:
- 用 HTMLParser 子类
TextExtractor抽取可读文本:跳过script/style/head,把td/th用|连接、块级标签换行,从而尽量保留表格结构,让财务表格转换后仍可解读; - 每份文本文件以
[SOURCE: SEC EDGAR | form: … | filed: … | accession: … | url: …]开头——这就是 README 中"带出处标记的文本"的落地形态; - 若抽取结果少于 500 字符或仍有未闭合的跳过标签,会打印
WARNING ... suspiciously empty extraction——正是"对不支持的格式大声失败"的体现; - 下载带缓存:
.url标记文件记录来源 URL,清单变更会自然使陈旧 raw 文件失效;每次请求间time.sleep(0.5),保持在 EDGAR 10 req/s 限制之下; --convert模式只做 raw → text 转换(python3 fetch_data_room.py --convert),适合重跑抽取。
成功运行后 data_room/docs/ 下每个文档对应一个 .txt 文件:quickstart 档 8 个,mini 档 26 个。
fetch_real_deck.py 与 make_analyst_docx.py:合成与真实并存
- fetch_real_deck.py 从 13E-3 附件 (c)(ii)(accession 0001140361-24-030374)下载 Centerview Partners 的扫描版董事会 deck 前 6 张幻灯片(每张是 JPG),用 pillow 拼成一个真实 PDF——给 notebook 一份"以图表为主"的真实文档用于归一化,对应 README 中"只存在于图表中的数字"这一对抗性设计。
- make_analyst_docx.py 用 python-docx 生成
analyst_note.docx,正文与表格明确标注SYNTHETIC DOCUMENT;它引用的 Consolidated EBITDA(Credit Agreement 口径,约 $252M)与公司自己披露的 adjusted EBITDA($235.4M)故意不可比——维基必须把两个数字连同各自口径一起记录,这正是冲突检测的教学点。其 Markdown 版本可见 analyst_note_synthetic.md。
七、并发抽取与轮询:utilities.py 的工程细节
utilities.py 提供 notebook 复用的两个关键帮助函数:
poll_until_end_turn:以轮询events.list的方式驱动 Managed Agents 会话,直到回合结束,而非保持一条长 SSE 流。原因写得很直白:长抽取回合走单条长连接很脆弱,代理会重置长连接;轮询让每个请求短小且可独立重试,网络抖动只损失一次 poll 而非整个回合。它打印 agent 文本、以+/~标记维基文件写入(对应单写者路径),并统计"reads/searches"次数(任何检查存储而非写入存储的工具调用)。它还能收集 token 用量(input / cache_write / cache_read / output)——这是 README "查询比原始检索便宜约 5 倍"论点的度量基础。wait_for_idle_status:吸收 SSE 的session.status_idle事件与服务端 status 字段之间的小竞态——流结束后立刻archive()会因状态仍为 running 而 400;它先以 0.25s 间隔短轮询 30s,再以 5s 间隔兜底轮询至多 300s,超时抛TimeoutError。会话中途可能被服务端 RESCHEDULED,工作仍会完成,因此默认超时很慷慨。
八、成本与档位预期
| 档位 | 文档数 | 墙钟时间 | 约计成本 |
|---|---|---|---|
quickstart |
8 | ~40 分钟 | ~$25 |
mini(默认) |
26 | ~1 小时 | ~$35 |
standard |
37 | 数小时 | 数十美元 |
full |
42 | 数小时 | 更高 |
- notebook 中所有已保存输出均来自
mini档;skill.md 补充说明成本估算来自已提交运行(默认模型claude-sonnet-5),请把所有成本视为数量级参考,实际会随模型选择、语料与当前定价变化。 - 对成品维基的一次查询,大约比用原始文档搜索同一问题便宜 5 倍——notebook 对两者都做了实测并展示盈亏平衡点。
- 一个操作性提醒(来自 skill.md):Dream 步骤可能耗时 20–60 分钟,建议启动后去做别的事再回来看;若想对比,可用 Opus 档的 dream 模型(
claude-opus-5)与默认claude-sonnet-5做 A/B。
九、常见问题与设置陷阱
汇总 skill.md 中列出的关键注意点:
- 先确认两项能力已开通:Managed Agents 与 Dreaming 缺一不可(缺后者合并步骤 404)。若在
client.beta.memory_stores.create报错,大概率是组织未启用 Managed Agents。 - 认证变量别混用:不要同时设置
ANTHROPIC_API_KEY与ant auth login配置文件——过期的导出 key 会静默遮蔽 profile;key 与ANTHROPIC_AUTH_TOKEN并存会让 SDK 同时发送两个头,API 会拒绝。用ant auth status查看胜出的凭据来源。 EDGAR_USER_AGENT必须设置:缺失时 EDGAR 会拒绝请求(fetch 脚本虽会降级为占位 UA 并打印警告,但 SEC 可能限流占位 UA)。- 不要试图自行获取预览 SDK:Dreaming 的 SDK 构建由预览版 onboarding 提供,组织注册后按官方指引安装即可。
- CLAUDE.md 提醒:notebook 是事实源,其已保存输出是真实运行的记录——不要重新生成、重跑或手工编辑它们以匹配后续源码变更。
十、本模式与仓库定位
该知识维基模式本质上是把"文档检索问答"从每次提问重读原文重构为构建期一次蒸馏 + 查询期只读查表,用构建期的固定成本换取查询期的边际成本下降,并以"带出处的 Markdown 存储"守住正确性底线(不猜测、大声失败、未命中点名缺档文档)。它是 claude-quickstarts 仓库中 managed-agents 目录下以 Claude Managed Agents 与 Dreaming 为核心的一组实践之一;本目录所有辅助脚本(清单构建、数据室抓取、文档生成、轮询工具)都只为 notebook 这一可运行产物服务,而 notebook 中已保存的输出就是一份可自上而下通读的真实案例研究——即使你的组织尚无预览访问权限,也可以不运行任何代码、把它当作完整演练从头读到尾。