企业官网建设流程全解析

open-notebook 的 Transformations 功能全解：模板化批处理源文档、批量生成结构化笔记

【免费下载链接】open-notebookAn Open Source implementation of Notebook LM with more flexibility and features项目地址: https://gitcode.com/GitHub_Trending/op/open-notebook

导读：Transformations（转换/批处理）是 open-notebook 中"把同一套分析模板批量作用于多个源文档（Sources）"的核心能力。与逐条提问的 Chat、自动检索的 Ask 不同，它把重复性分析变成"定义一次、应用多次"的自动化流程。读完本文，你将掌握内置模板与自定义模板的完整用法、提示词设计要点、批量应用流程，以及从 REST API → LangGraph 图 → LLM 生成 → 笔记持久化的底层实现原理。

关联阅读：用户指南原文、Chat vs Transformations 概念对比。

一、什么是 Transformations，何时应该使用

Transformations 的理念非常直接：对多个源文档同时应用同一种分析。与其对 10 篇论文逐一重复提问"帮我总结一下"，不如定义一次总结模板，然后一次性跑完所有内容。

使用时机对比

典型例子：你有 10 篇论文，想对每篇都生成一段摘要。用 Transformations，一次操作即可全部完成，而不是在 Chat 里逐个粘贴、逐个提问。

三个相近功能的关系可以这样概括：Transformations 是"同模板 × 多文档 → 结构化笔记"，Chat 是"你的问题 × 所选文档 → 对话"，Ask 是"你的问题 → 自动检索 → 综合答案"。

二、Transformations 的执行链路与实现原理

在深入实操之前，先理解底层架构，这对你判断"处理要多长时间""结果存在哪里""能不能并行"都很有帮助。open-notebook 后端对一次转换的执行可概括为一条明确的调用链：

前端操作（Sources/Transformations 页面） → REST API（POST /transformations/execute 或后台命令 run_transformation） → LangGraph 图（open_notebook/graphs/transformation.py） → provision_langchain_model() 按需装配 LLM → SystemMessage + HumanMessage 调用模型 → 清洗 thinking 内容 → source.add_insight() 持久化为笔记

2.1 数据模型：Transformation 实体

一个转换模板在后端对应Transformation领域对象，定义于 open_notebook/domain/transformation.py，存储在 SurrealDB 的transformation表（table_name = "transformation"）中：

schema 中apply_default的默认值为False，created/updated由数据库自动维护（见 迁移脚本 5.surrealql）。

同一个文件中还定义了全局"默认转换指令"配置对象DefaultPrompts（open_notebook/domain/transformation.py），固定记录 ID 为open_notebook:default_prompts。它通过transformation_instructions字段存放一段会前置拼接到每个模板提示词之前的系统级指令（例如"只输出请求内容，不要寒暄"），后续会详述。

2.2 执行核心：transformation 图

转换执行被封装为一个 LangGraph 状态图，代码位于 open_notebook/graphs/transformation.py。它的状态定义只有四个键：

class TransformationState(TypedDict): input_text: str source: Source transformation: Transformation output: str

图的拓扑非常简单（这也是为什么每个转换本质上是单次"一段 prompt 进、一段文本出"）：

START → agent（run_transformation） → END

run_transformation（open_notebook/graphs/transformation.py）的核心逻辑值得关注几点：

1. 输入文本回退：若状态中没有input_text，则自动使用source.full_text（源文档全文）作为待转换内容（assert source or content, "No content to transform"）。
2. 指令组装顺序：模板自身的transformation.prompt是主体；若全局DefaultPrompts.transformation_instructions存在，则会被拼接到最前面。
3. 模板安全渲染：用户写的 prompt 是自由文本，不会被当作 Jinja 模板源码编译（避免注入），而是作为普通渲染变量传入固定的开发者模板transformation/execute（见 prompts/transformation/execute.jinja）。这是针对安全公告 GHSA-f35w-wx37-26q7 的修复，相关讨论见 docs/7-DEVELOPMENT/security.md。
4. 模型装配：通过provision_langchain_model(..., "transformation", max_tokens=8192)装配聊天模型，且可以按转换执行时传入的model_id（config 中的configurable.model_id）选择具体模型。
5. 输出清洗：对模型响应先extract_text_content抽取纯文本，再用clean_thinking_content去掉思维链（thinking）内容，保证入库的笔记干净。
6. 结果持久化：若状态带source，则调用await source.add_insight(transformation.title, cleaned_content)，把转换标题作为笔记类型写入。

由于prompts/transformation/execute.jinja是统一外壳，它还顺带给每次转换补充了数学公式排版约定：展示型公式用$$...$$、行内公式用$...$包裹，除非用户明确要 LaTeX 源码，否则不使用 ```latex 代码块。这意味着你可以在转换提示词中放心要求模型产出数学内容。

2.3 持久化与命名：insight 是怎么变成笔记的

add_insight定义在 open_notebook/domain/notebook.py。它是一个fire-and-forget 的异步命令：提交create_insight命令后立即返回，命令在后台队列中执行写入（含自动重试），并继续派发embed_insight做向量化。选择异步而非同步，是为了批量转换场景下的吞吐量——这正是"处理在后台运行、你可以继续干别的活"这一产品体验的来源。

笔记的持久化对象是SourceInsight（表source_insight，见 open_notebook/domain/notebook.py），核心字段为insight_type（= 转换的title）与content。当需要把洞察落成独立 Note 时，save_as_note()（open_notebook/domain/notebook.py）会生成标题f"{insight_type} from source {source.title}"——即"转换类型 + 来源标题"，与用户指南中"[转换名] - [来源标题]"的命名直觉一致。

2.4 可靠性设计

转换运行时的模型异常会被统一交给classify_error（open_notebook/utils/error_classifier.py）归类后重新抛出，交由全局异常处理器映射成合适的 HTTP 状态码。测试 tests/test_add_insight_failure_propagation.py 专门验证了：如果add_insight的异步提交失败，异常必须从run_transformation中向上传播而不是被吞掉，防止"转换报告成功但笔记从未落库"的静默丢数据问题。

三、快速开始：创建你的第一个转换

界面操作路径如下（对应前端页面 frontend/src/app/(dashboard)/transformations/page.tsx/transformations/page.tsx)）：

1. 进入你的笔记本（Notebook） 2. 在导航中点击 "Transformations" 3. 选择一个内置模板（例如 "Summary"） 4. 选择要转换的源文档 5. 点击 "Apply" 6. 等待后台处理 7. 新的笔记自动出现在笔记面板中

四、内置转换模板

用户指南把现成模板按分析目的做了归类。这里的模板本质上是"写好的 prompt + 结构化的输出期望"，你可以直接选用，也可以参考它们设计自己的模板：

Summary（摘要）

作用：生成 200-300 词的概览 输出：关键要点、主要论点、结论 适用：快速查阅、快速了解文档大意

Key Concepts（关键概念）

作用：抽取主要思想与术语 输出：概念列表 + 解释 适用：学习新主题、建立术语表

Methodology（方法论）

作用：抽取研究采用的方法与流程 输出：研究如何实施 适用：学术论文、综述研究

Takeaways（要点/行动项）

作用：抽取可执行的洞见 输出：你应该如何利用这些信息 适用：商业文档、实操指南

Questions（问题）

作用：生成该来源引发的问题 输出：开放性问题、空白点、后续研究方向 适用：文献综述、研究规划

需要提醒的是："内置模板"的具体清单以仓库实际初始化的数据为准。在 SurrealDB 迁移脚本 open_notebook/database/migrations/5.surrealql 中，系统首次建库时会自动插入一组默认转换，包括Analyze Paper（论文分析）、Key Insights（关键洞见）、Dense Summary（稠密摘要，apply_default: True）、Reflections（反思提问）、Table of Contents（目录生成）、Simple Summary（简单摘要），并为每个模板内置了相当精细的分步式 prompt（例如 Analyze Paper 要求按 PURPOSE / CONTRIBUTION / KEY FINDINGS / IMPLICATIONS / LIMITATIONS 分节输出，并对每条 bullet 的字数做了约束）。如果列表与你所在部署看到的不完全一致，请以实际初始化数据为准，因为模板集合会随版本演进调整。

五、创建自定义转换模板

5.1 分步操作

1. 进入 "Transformations" 页面 2. 点击 "Create New"（新建） 3. 输入名称，例如 "Academic Paper Analysis" 4. 编写你的提示词模板： "Analyze this academic paper and extract: 1. **Research Question**: What problem does this address? 2. **Hypothesis**: What did they predict? 3. **Methodology**: How did they test it? 4. **Key Findings**: What did they discover? (numbered list) 5. **Limitations**: What caveats do the authors mention? 6. **Future Work**: What do they suggest next? Be specific and cite page numbers where possible." 5. 点击 "Save" 保存 6. 你的转换出现在列表中

5.2 每个字段到底填什么（API 视角）

从 REST 请求体（api/models.py 中的TransformationCreate）可以看到创建转换需要提供的全部字段：

• name：模板名称，必填；
• title：展示标题，必填，同时作为生成笔记的类型标签；
• description：用途说明，必填；
• prompt：提示词正文，必填；
• apply_default：是否默认应用，选填，默认false；
• model_id：可选，为该模板绑定默认模型；传了就必须是真实存在的模型，否则后端在创建时就返回 404（api/routers/transformations.py），避免无效模型 ID 入库后到运行时才失败。

编辑场景对应TransformationUpdate：所有字段都可选（部分更新），其中model_id支持显式清空为None以回落到全局模型配置。

5.3 提示词模板设计要点

明确指定输出格式：

好： "List 5 key points as bullet points" 坏： "What are the key points?"

要求分节结构：

好： "Create sections for: Summary, Methods, Results" 坏： "Tell me about this paper"

主动要求引用/出处：

好： "Cite page numbers for each claim" 坏： （不提引用要求）

设定长度预期：

好： "In 200-300 words, summarize..." 坏： "Summarize this"

5.4 全局默认转换指令（Default Prompt）

前面提到的DefaultPrompts.transformation_instructions会在每次执行时自动拼接到每个模板 prompt 之前。它通过 api/routers/transformations.py 的GET /transformations/default-prompt与PUT /transformations/default-prompt读取/更新，前端在 DefaultPromptEditor.tsx/transformations/components/DefaultPromptEditor.tsx) 中提供编辑入口。迁移脚本初始化出的默认内容约相当于："你是我的学习助手……下面的文本是我自己的内容，不要给我版权/抄袭警告；只输出请求的内容，不要以 'Sure, I can help…' 之类的客套开场；不要在生成中途停下来提问。"（见 open_notebook/database/migrations/5.surrealql）。如果你的所有模板都需要遵守某些输出纪律，放在这里比复制到每个模板里更高效。

六、应用转换：单个源与批量源

6.1 转换单个来源

1. 在 Sources 面板中找到该来源，点击菜单（⋮） 2. 选择 "Transform" 3. 选择转换模板 4. 点击 "Apply" 5. 完成后自动生成笔记

这条路径在后端对应run_transformation后台命令（commands/source_commands.py）：它接收source_id + transformation_id，加载来源与转换对象，然后调用transform_graph.ainvoke({source, transformation})，并把transformation.model_id传入 configurable 作为本次执行模型。整个过程包含 LLM 调用与笔记创建，属于耗时后台任务。

6.2 批量转换多个来源

1. 进入 Transformations 页面 2. 选择你的模板 3. 勾选多个源文档 4. 点击 "Apply to Selected" 5. 处理并行进行 6. 每个来源各自生成一条笔记

6.3 处理时间参考

处理在后台异步执行，你可以继续使用界面做其他事情。以下为指南给出的典型量级（实际耗时取决于所选模型、文档长度与机器负载）：

从实现上看，耗时主要花在"读取源全文 → 提交给 LLM → 清洗输出 → 异步落库"这条链路上（见 2.2/2.3 节），且单次转换的max_tokens上限为 8192，文档过大时输出可能被截断——这正是指南建议"超长来源先切分再转换"的深层原因。

七、经典模板示例（可直接套用）

文献综述模板（Literature Review）

名称：Literature Review Entry 提示词： "For this research paper, create a literature review entry: **Citation**: [Author(s), Year, Title, Journal] **Research Question**: What problem is addressed? **Methodology**: What approach was used? **Sample**: What population/data was studied? **Key Findings**: 1. [Finding with page citation] 2. [Finding with page citation] 3. [Finding with page citation] **Strengths**: What did this study do well? **Limitations**: What are the gaps? **Relevance**: How does this connect to my research? Keep each section to 2-3 sentences."

会议纪要模板（Meeting Notes）

名称：Meeting Summary 提示词： "From this meeting transcript, extract: **Attendees**: Who was present **Date/Time**: When it occurred **Key Decisions**: What was decided (numbered) **Action Items**: - [ ] Task (Owner, Due Date) **Open Questions**: Unresolved issues **Next Steps**: What happens next Format as clear, scannable notes."

竞品分析模板（Competitor Analysis）

名称：Competitor Analysis 提示词： "Analyze this company/product document: **Company**: Name and overview **Products/Services**: What they offer **Target Market**: Who they serve **Pricing**: If available **Strengths**: Competitive advantages **Weaknesses**: Gaps or limitations **Opportunities**: How we compare **Threats**: What they do better Be objective and cite specific details."

技术文档总结模板（Technical Documentation）

名称：API Documentation Summary 提示词： "Extract from this technical document: **Overview**: What does this do? (1-2 sentences) **Authentication**: How to authenticate **Key Endpoints**: - Endpoint 1: [method] [path] - [purpose] - Endpoint 2: ... **Common Parameters**: Frequently used params **Rate Limits**: If mentioned **Error Codes**: Key error responses **Example Usage**: Simple code example if possible Keep technical but concise."

这四个模板展示了同一种方法论：通过标题式（Markdown 加粗小节）的显式结构把输出"钉死"，再辅以"2-3 句""引用页码""编号列表"等局部约束。把它们与你实际文档类型结合改写，就是最稳妥的自定义起点。

八、管理转换模板

编辑转换

1. 进入 Transformations 页面 2. 找到你的模板 3. 点击 "Edit" 4. 修改提示词 5. 点击 "Save"

删除转换

1. 进入 Transformations 页面 2. 找到该模板 3. 点击 "Delete" 4. 确认删除

排序规则

内置（初始）转换排在最前，之后是自定义转换，按名称字母序排列。后端GET /transformations读取时即按name asc排序（api/routers/transformations.py），因此无论界面还是接口拿到的列表顺序是一致的。

九、转换输出说明

结果去向

• 每个被转换的来源产生一条笔记；
• 笔记出现在笔记本的 Notes 面板；
• 笔记带转换名称标签（insight_type = 转换 title）；
• 笔记与原始来源关联（source_insight表保存来源引用）。

笔记命名

界面约定： "[转换名] - [来源标题]" 代码实现： f"{insight_type} from source {source.title}" （save_as_note，见 open_notebook/domain/notebook.py#L390-L399） 示例： "Summary - Research Paper 2025.pdf"

编辑输出

1. 点击生成的笔记 2. 点击 "Edit" 3. 精炼内容 4. 保存

转换输出被有意设计为"起点"而非"终稿"——所有生成的笔记都可以像普通笔记一样继续编辑。

十、最佳实践

模板设计

1. 从具体开始—— 含糊的提示词只会得到含糊的结果；
2. 使用格式化指令—— 标题、列表、编号等结构会显著提升可用性；
3. 要求引用—— 让结果可验证（如"为每个论断给出页码"）；
4. 设定长度—— 避免输出过长或过短；
5. 先小规模测试—— 批量前先在单个来源上验证一次。

来源选择

1. 内容相近—— 对相似类型的来源使用同一转换效果最好；
2. 规模合理—— 超长来源可能需要先拆分（这与单次调用 8192 token 上限的实现约束相符）；
3. 确认已处理完成—— 只对处理完成的来源执行转换，否则可能拿不到完整full_text。

质量控制

1. 抽样检查—— 批量结果先抽查前几个输出再信任整批；
2. 按需编辑—— 转换结果是起点，不是最终交付物；
3. 迭代提示词—— 依据输出反馈持续打磨模板。

十一、常见问题排查

从源码角度，当批量执行中某次转换抛错时，错误会经 api/routers/transformations.py 的全局异常处理映射为 HTTP 状态码返回（例如模型不存在返回 404、非法输入返回 400），前端相应提示。绝大多数"处理失败"都可归结为来源未处理完、模型配额/网络问题或提示词过复杂三类。

十二、Transformations vs Chat vs Ask（横向对比）

三条路线的图谱实现分别位于 open_notebook/graphs/transformation.py、open_notebook/graphs/chat.py 与 open_notebook/graphs/ask.py。简单说：Ask 走自动检索 + 生成综合答案；Chat 保留多轮对话状态；而 Transformation 不对话、不检索，只"模板 × 全文 → 一条结构化笔记"，因而最适合批处理。

十三、给开发者：转换 REST API 速查

前端Transformations页面与各对话框最终都通过以下接口工作（路由集中在 api/routers/transformations.py）：

直接调用execute接口时，请求体为transformation_id + input_text + 可选 model_id；模型选择优先级是请求体显式 model_id > 转换自身绑定的 model_id > 全局默认转换模型（api/routers/transformations.py）。这一优先级逻辑在 tests/test_transformations_api.py 中有系统性覆盖（含"未传 model 时用存储模型""请求 model 覆盖存储模型"等用例）。

注意：execute接口接收的是纯文本（如一段粘贴的文档内容），并不会自动绑定来源生成笔记；绑定来源、自动生成笔记的入口是界面上的 Transform / 批量应用，对应后台run_transformation命令。

十四、总结

Transformations = 批量 AI 处理 用法： 1. 定义模板（或使用内置模板） 2. 选择源文档 3. 应用转换 4. 得到结构化笔记 何时使用： - 对大量来源做同一种分析 - 需要一致的输出格式 - 构建结构化知识库 - 节省重复性任务的时间 要点： - 提示词要具体 - 明确要求输出格式 - 批量之前先小范围测试 - 输出可继续编辑

一言以蔽之：Transformations 把重复性分析变成一键操作——定义一次，应用多次。模板化、结构化、可追溯（带来源引用与类型标签）的批量笔记产出，正是它区别于 Chat 与 Ask 的独特价值所在。

【免费下载链接】open-notebookAn Open Source implementation of Notebook LM with more flexibility and features项目地址: https://gitcode.com/GitHub_Trending/op/open-notebook