数据截至 (上游 commit fb951af7744d)
04 · 工程精华、边界与代码地图
这一章是“带走的精华”:STORM 里那些不显然但很实用的小设计;它刻意不做什么、会在哪崩;以及完整的代码跳转地图。
1. 巧妙之处(可借鉴的技术)
1.1 引用编号的“局部→全局”统一与越界裁剪
妙在哪: 每个章节是并行写的,LLM 只看到本节资料的局部编号 [1][2];但全文需要一套统一编号,而且 LLM 经常会引用不存在的编号。STORM 用一个占位符两步替换法既统一编号、又不会“替串”。
update_citation_index(utils.py:540-550)先把所有旧编号换成 __PLACEHOLDER_n__,再把占位符换成新编号——避免“把 [1] 换成 [10] 时又被后续规则误伤”:
# 示意,源码精简自 utils.py:540-550
for original in citation_map: # 第一遍:全换成占位符
s = s.replace(f"[{original}]", f"__PLACEHOLDER_{original}__")
for original, unify in citation_map.items(): # 第二遍:占位符→新编号
s = s.replace(f"__PLACEHOLDER_{original}__", f"[{unify}]")
配合 update_section(storm_dataclass.py:249-299):它先正则抓出本节用到的引用号,把超过资料条数的越界引用直接删掉(max_ref_num > len(info_list) 时清除),再只保留真正被引用的资料并重映射编号。最后 reorder_reference_index(storm_dataclass.py:374-412)按引用在全文出现顺序重排成 1,2,3…,并删掉没被引用的参考。
1.2 砍掉被 token 上限截断的“半截句”
妙在哪: LLM 输出常因 max_tokens 在句子中间断掉,留下半句脏话。remove_uncompleted_sentences_with_citations(utils.py:367-425)用正则找最后一个“句末标点(可带引用)”,只保留到那里。顺手还把 [1, 2, 3] 拆成 [1][2][3] 并去重排序,统一引用风格。
1.3 取材用 嵌入相似度,不是全量塞
妙在哪: 资料可能很多,全塞进 prompt 又贵又超窗。StormInformationTable.retrieve_information(storm_dataclass.py:119-145)对每个章节查询,用 SentenceTransformer 编码后算 cosine 相似度取 top-k,再按 URL 聚合 snippet返回。Co-STORM 的信息归位也用同一招做候选排序(information_insertion_module.py:149-163)。
1.4 一切皆 dspy.Signature:prompt 即“带类型的函数签名”
妙在哪: STORM 的每个 LLM 调用都写成一个 dspy.Signature 子类(如 AskQuestionWithPersona、WriteSection、InsertInformation),docstring 是指令、InputField/OutputField 是输入输出。好处是 prompt 集中、可读、可被 dspy 优化器调。with dspy.settings.context(lm=...) 在不同步骤切换不同模型;多处 show_guidelines=False 是为了“对不同 LLM 家族更鲁棒”(见 article_polish.py:88-89 的注释)。
1.5 用命名约定做自动统计
妙在哪: LMConfigs 用 if "_lm" in attr_name 反射式地遍历所有以 _lm 结尾的属性来统计 token 用量、收集调用历史(interface.py:443-482);Retriever 同理用 _rm 后缀统计查询数。新增一个模型只要按约定命名即可被自动纳入统计。
2. 边界与局限(诚实)
- 不是成品文章。 作者明说产出“需要大量编辑才能发表”,定位是写作前的调研辅助(
README.mdOverview)。 - 专家“只取每条结果的第一个 snippet”。
TopicExpert.forward注释直言“Simplify this part by directly using the top 1 snippet”(knowledge_curation.py:218-221)——为省成本牺牲了召回深度。 - 强英文偏向 + 安全过滤偏保守。 demo 用的
user_input_appropriateness_check(utils.py:714-768)会拒绝非英文输入、个人经历类、以及“要求执行计算/编程”的非研究类请求,且硬编码用azure/gpt-4o-mini当判官——作者也承认会有误杀(prompt 里反复道歉)。 - Co-STORM
from_dict不恢复 LM 配置。 代码里有FIXME: does not use the lm_config data but naively use default setting(engine.py:556-558)——反序列化会丢失自定义模型配置。 - 引言/结论被流水线“吃掉”。 成文阶段显式跳过 introduction/conclusion/summary 章节(
article_generation.py:96-103), 开篇综述完全交给润色阶段的 lead;如果润色没跑,文章就没有像样的开头。 - 不做多跳引用。
Retriever.retrieve注释说明会先remove_citations清掉来源里的引用,“STORM 不考虑多跳引用”(interface.py:300-305)。
3. 横向对比(同 shelf 的不同取舍)
STORM 属于 ai-frontier-reference 的 rag-context / academic 区。和常见 RAG / agent 写作方案相比,它的特异取舍:
| 维度 | STORM 的做法 | 常见 RAG 写作的做法 |
|---|---|---|
| 怎么决定“查什么” | 多视角模拟对话逼出深问题 | 直接对 query 检索 |
| 信息组织 | STORM 用扁平信息表;Co-STORM 用LLM 导航的思维导图 | 向量库 + top-k |
| 多 agent 协调 | Co-STORM 有显式轮次策略 + 主持人 | 多为固定流程或简单 ReAct |
| 模型抽象 | dspy Signature + litellm,每阶段可换模型 | 多直接拼 prompt 字符串 |
| 人的角色 | Co-STORM 让人实时插话引导 | 多为一问一答 |
Co-STORM 的“思维导图作为人机共享概念空间”和“主持人用未被使用的信息开新话题”,是它相对一般多 agent 讨论框架的两个鲜明增量。
4. 代码地图(导航索引)
| 主题 | 文件路径 | 关键符号 |
|---|---|---|
| STORM-Wiki 流水线入口 | knowledge_storm/storm_wiki/engine.py | STORMWikiRunner.run、run_knowledge_curation_module、STORMWikiLMConfigs |
| 抽象接口/数据类 | knowledge_storm/interface.py | Engine、KnowledgeCurationModule、Article、Information、Retriever、LMConfigs |
| 知识采集(模拟对话) | knowledge_storm/storm_wiki/modules/knowledge_curation.py | ConvSimulator、WikiWriter、TopicExpert、AskQuestionWithPersona、AnswerQuestion |
| 视角生成 | knowledge_storm/storm_wiki/modules/persona_generator.py | StormPersonaGenerator.generate_persona、CreateWriterWithPersona、get_wiki_page_title_and_toc、GenPersona |
| 大纲生成 | knowledge_storm/storm_wiki/modules/outline_generation.py | WriteOutline.forward、WritePageOutline、WritePageOutlineFromConv |
| 分节成文 | knowledge_storm/storm_wiki/modules/article_generation.py | StormArticleGenerationModule.generate_article、ConvToSection、WriteSection |
| 润色 | knowledge_storm/storm_wiki/modules/article_polish.py | StormArticlePolishingModule.polish_article、PolishPageModule、WriteLeadSection、PolishPage |
| STORM 数据类/信息表 | knowledge_storm/storm_wiki/modules/storm_dataclass.py | StormInformationTable.retrieve_information、StormArticle.update_section、reorder_reference_index |
| Co-STORM 引擎/轮次策略 | knowledge_storm/collaborative_storm/engine.py | CoStormRunner.step、DiscourseManager.get_next_turn_policy、TurnPolicySpec、warm_start |
| Co-STORM agents | knowledge_storm/collaborative_storm/modules/co_storm_agents.py | CoStormExpert、Moderator、SimulatedUser、PureRAGAgent |
| 思维导图(知识库) | knowledge_storm/dataclass.py | KnowledgeBase.reorganize、KnowledgeBase.insert_information、KnowledgeNode、ConversationTurn |
| 信息归位/节点扩展 | knowledge_storm/collaborative_storm/modules/information_insertion_module.py | InsertInformationModule.layer_by_layer_navigation_placement、ExpandNodeModule._expand_node、InsertInformation |
| 接地式问答 | knowledge_storm/collaborative_storm/modules/grounded_question_answering.py | AnswerQuestionModule.forward、QuestionToQuery、AnswerQuestion |
| 文本处理工具 | knowledge_storm/utils.py | ArticleTextProcessing.update_citation_index、remove_uncompleted_sentences_with_citations、clean_up_outline、user_input_appropriateness_check |
| 检索层 / 模型层 | knowledge_storm/rm.py / knowledge_storm/lm.py | BingSearch 等 RM、LitellmModel |
5. 相关阅读
- 本库内:index · 01 流水线 · 02 知识采集 · 03 Co-STORM 思维导图
- 论文:STORM(NAACL 2024,arXiv:2402.14207)、Co-STORM(EMNLP 2024,arXiv:2408.15232)