构建廉价且正确的 Agent 检索知识库:Claude Managed Agents 的 knowledge-wiki 实战指南

原创2026-09-13 12:09:551,337 阅读
文章标签:示例工程人工智能AI 应用AI Agent工具调用浏览器控制GUI 自动化

构建廉价且正确的 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 会逐一展开),也是整篇文章的骨架:

  1. 装配语料(Assemble your corpus):收集 Agent 会反复查询的文档——数据室、取证集、支持知识库。工作示例从公开申报文件中抓取了一个真实的 M&A 数据室。
  2. 将每种文件类型归一化为带出处标记的文本(Normalize):把 PDF、Word、表格、邮件、幻灯片各自路由到纯文本,并加上 [SOURCE: …] 头;遇到不支持的格式要大声失败——一个静默跳过的加载器会让维基"看起来完整,实际上不完整"。
  3. 并行抽取进一个共享记忆存储——那个存储就是维基(Extract):将语料分批,每批开一个并发的 Agent 会话,每个会话向存储写入结构化笔记。把笔记 schema 放在存储的 attachment instructions 上,并让每份源文档拥有独立的单写者路径(single-writer path),使并发会话互不覆盖。
  4. 在合并前消解维基的开放问题(Resolve):让一次 pass 交叉阅读维基,关闭抽取遗留的开放问题;确实缺失的内容标记为"已确认不可解"(confirmed-unresolvable),绝不猜测。
  5. 用一次受控的 Dream 进行合并(Consolidate):Dreaming 是服务端合并 pass——"睡眠时计算":它读取各构建会话的记录和存储,然后写出一个重新组织过的新存储:去重后的实体、把探索式读取变成一次查找的索引、排序后的升级(escalations)文件、修复后的链接。它从不接触原始语料——因此维基中一切为真的事实,都是在抽取阶段赢得的。
  6. 每次提问从全新会话以只读方式查询(Query):以只读方式挂载合并后的存储,要求每条事实都带出处,并把未命中行为写成脚本("数据室里没有"——点名需要补上的文档,绝不猜测)。
  7. 运营:定期对真实使用记录做 Dream(Operate):积累足够真实查询后,把工作记录与维基一起 Dream,让它围绕用户真正问的内容重组。
  8. 评估与调优(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 中列出的关键注意点:

  1. 先确认两项能力已开通:Managed Agents 与 Dreaming 缺一不可(缺后者合并步骤 404)。若在 client.beta.memory_stores.create 报错,大概率是组织未启用 Managed Agents。
  2. 认证变量别混用:不要同时设置 ANTHROPIC_API_KEY 与 ant auth login 配置文件——过期的导出 key 会静默遮蔽 profile;key 与 ANTHROPIC_AUTH_TOKEN 并存会让 SDK 同时发送两个头,API 会拒绝。用 ant auth status 查看胜出的凭据来源。
  3. EDGAR_USER_AGENT 必须设置:缺失时 EDGAR 会拒绝请求(fetch 脚本虽会降级为占位 UA 并打印警告,但 SEC 可能限流占位 UA)。
  4. 不要试图自行获取预览 SDK:Dreaming 的 SDK 构建由预览版 onboarding 提供,组织注册后按官方指引安装即可。
  5. CLAUDE.md 提醒:notebook 是事实源,其已保存输出是真实运行的记录——不要重新生成、重跑或手工编辑它们以匹配后续源码变更。

十、本模式与仓库定位

该知识维基模式本质上是把"文档检索问答"从每次提问重读原文重构为构建期一次蒸馏 + 查询期只读查表,用构建期的固定成本换取查询期的边际成本下降,并以"带出处的 Markdown 存储"守住正确性底线(不猜测、大声失败、未命中点名缺档文档)。它是 claude-quickstarts 仓库中 managed-agents 目录下以 Claude Managed Agents 与 Dreaming 为核心的一组实践之一;本目录所有辅助脚本(清单构建、数据室抓取、文档生成、轮询工具)都只为 notebook 这一可运行产物服务,而 notebook 中已保存的输出就是一份可自上而下通读的真实案例研究——即使你的组织尚无预览访问权限,也可以不运行任何代码、把它当作完整演练从头读到尾。

登录后查看全文
claude-quickstarts