RocketRide Dictionary 节点实战：用 LLM 从文本与表格中自动构建企业术语表

本篇技术指南以 RocketRide 开源仓库中的dictionary文本处理节点（nodes/src/nodes/dictionary/README.md）为核心，讲解如何让一个已连接的 LLM 把文本或表格内容转成公司专属术语表（glossary）。读完本文，你将掌握该节点的连接方式、通道（lane）语义、内置提示词设计、输出文档结构、错误处理与依赖约定，并能在你自己的 pipeline 中正确选用它，而不是误用通用的结构化抽取节点。

节点定位：为"内部词汇"而生的提取器

在 RocketRide 的节点体系中，dictionary是一个典型的"文本处理型"（classType: ["text"]）过滤器节点。它解决的核心问题是：下游用户或 Agent 需要的是公司内部术语的简明定义，而不是一张带预定义 schema 的通用结构化数据表。

从节点注册元数据 services.json 可以看到它的官方描述：这是一个"分析文档、抽取关键术语与短语"的处理组件，能够识别领域专属词汇、反复出现的表达和关联术语，构建结构化清单供下游增强或引用，适用于创建术语表、辅助分类或提升搜索相关性。

与 extract_data 的取舍

仓库文档明确给出了选型建议：当输出目标是"可复用的术语与描述词汇表"时，使用dictionary；当需要的是"若干 chunk 合并成的表状结果（如按配置列抽取行）"时，应使用 extract_data。两者的差异很直观：

• dictionary：LLM 返回一个 JSON 数组，数组每个元素是一条定义，节点为每条定义写一个独立文档；
• extract_data：按配置的列名、类型与默认值请求 JSON 行数组，维护"工作表"跨 chunk 合并去重，最终输出一张完整的表。

一句话总结：dictionary 产出"词条"，extract_data 产出"表格"。

连接与通道（Lanes）

Connections

llm连接是强制性的（在 services.json 的invoke.llm.min中标记为1），节点本身没有 LLM 选择逻辑，完全依赖这条连接提供的模型实例。

Lanes

lanes配置为{"text": ["documents"]}：输入侧只有text通道，输出侧只有documents通道。这与 extract_data 拥有table/text/documents多种输入和answers/documents双输出的形态形成鲜明对比。

配置：零本地字段

该节点没有本地配置字段。在 services.json 中，fields为空对象，shape也只有一个无属性的 "Pipe" 段落；README 生成的 Schema 章节明确写着 "No configuration fields."。这意味着：

1. 你不需要（也无法）为节点配置任何提取列、类型或默认值；
2. 你需要做的只有两件事：连上llm，在text通道上供给文本；
3. 当运行时提供的是表格内容时，走的是同一条抽取路径（见下文源码分析）。

内置提示词：四条指令 + 一个示例

虽然节点无配置，但它的提示词是精心设计的，写在 IInstance.py 的_extractDefinitions方法中。节点通过Question(type=QuestionType.QUESTION, expectJson=True, ...)发起结构化提问，expectJson: true强制 LLM 返回 JSON。

提示词由四条指令（instruction）组成：

1. Dictionary Creation：告诉 LLM 正在创建公司专属术语词典，要从给定文档与上下文中抽出公司特定信息、行话，以及"可能与训练数据含义不同"的内容；
2. Company Specific Terms：明确要求把公司专属术语和缩略语也纳入定义；
3. Multiple definitions：对于多份文档，合并为单个 JSON 数组，并且"总是返回单个 JSON 数组"；
4. Overlap：允许定义之间存在重叠。

同时提供了一个银行信贷场景的 few-shot 示例：原文提到 "red loan" 与 "CPMD"，期望输出为

[ {"term": "Red loan", "description": "Credit score less than 650 and delinquent by 60 days or more"}, {"term": "CPMD", "description": "Credit Portfolio Marketing Division"} ]

这个示例形状{"term": "...", "description": "..."}是提示词模板的一部分，但源码注释明确说明：节点在序列化每个返回对象时不做额外字段强加，即 LLM 返回的对象结构会被原样保留。

输出：每条定义 = 一个文档

writeAnswers方法（IInstance.py）负责把 LLM 的回答落成文档：

• 取出answer.getJson()得到定义数组；
• 遍历每个定义，构造Doc(page_content=json.dumps(definition), metadata=...)——文档内容是定义对象的 JSON 序列化字符串；
• 最后通过self.instance.writeDocuments(documents)一次性写出全部文档。

Chunk 元数据约定

元数据构造逻辑非常明确（IInstance.py）：

• chunkId：在open()中每次收到新输入对象时重置为 0（self.chunkId = 0），此后每写一条定义chunkId递增 1；
• isTable：恒为False，即输出文档一律标记为非表格内容；
• tableId：恒为0，不关联任何表格。

即使输入是通过表格处理路径（writeTable）到达的，最终输出也统一是"普通文档"，因此下游节点拿到的是一批可继续检索/入库的词汇文档，而不是表格行。

错误处理：宁可报错，不可产出坏数据

节点对 LLM 返回内容做了严格校验（IInstance.py）：

• 如果 LLM 返回合法 JSON 但不是数组（例如一个对象、字符串、数字或 null），节点会抛出带描述信息的ValueError，且在任何文档写出之前就失败：

  Dictionary expected the LLM response to be a JSON array of definitions, got <Type>.

• 如果 LLM 返回无效 JSON，节点不会吞掉错误，而是继续向上传播解析异常（如 "Answer is not in JSON format."）。

这两条行为都有测试用例背书，见 nodes/test/dictionary/test_response_shape.py：

• test_array_emits_one_document_per_definition_with_incrementing_metadata：验证数组输入下"每条定义一个文档、chunkId 从 0 递增、isTable 恒为 False、tableId 恒为 0"；
• test_empty_array_is_valid_and_emits_an_empty_document_batch：空数组是合法输入，产出空批次且 chunkId 保持 0；
• test_non_array_json_is_rejected_before_any_documents_are_emitted：参数化测试覆盖对象/字符串/数字/null 四种非数组情形，断言抛出ValueError且writeDocuments未被调用；
• test_invalid_json_error_propagates_without_emitting_documents：无效 JSON 异常向上传播，同样不产出任何文档。

依赖约定：零额外 Python 依赖

节点的 requirements.txt 是注释说明文件——节点没有任何自身的 Python 包依赖，完全依赖单独安装的 AI 模块（ai.common.schema中的Doc、DocMetadata、Question、QuestionType、Answer以及rocketlib的IInvokeLLM）。

这一点在运行时也能从 IGlobal.py 得到印证：beginGlobal在非 CONFIG 模式下通过depends()加载同目录的requirements.txt，由于该文件为空，实际不安装任何东西，天然规避了依赖冲突；而在 CONFIG 模式下则直接跳过驱动加载。这也解释了为什么测试文件 test_response_shape.py 需要为rocketlib、ai等模块安装桩（stub）——节点源码对引擎与 AI 模块的耦合都集中在这些接口上。

在 pipeline 中的典型用法与建议

综合以上分析，在 RocketRide 的 pipe 工作流中使用 dictionary 节点的推荐做法是：

1. 连接 LLM：从支持的多家模型提供商中任选一个实例接入llm连接（invoke.llm.min = 1，必须连接）；
2. 喂入文本：把待分析的文档/文本块送入text通道；若上游产出表格，运行时也会走同一抽取路径（writeTable与writeText都调用_extractDefinitions）；
3. 消费文档：从documents通道接收每词条一个的 JSON 文档，可继续接向量存储、搜索或下游 Agent 上下文；
4. 处理异常：由于节点在返回非数组 JSON 时会立即抛错，建议在编排层关注 LLM 返回的稳定性，或在上游提示词中强调"始终返回 JSON 数组"以配合本节点的单数组约定。

从源码结构看，该节点的IInstanceBase生命周期包含open（重置 chunkId）、writeText/writeTable（抽取）与writeAnswers（校验并写出）三个关键阶段，整体设计使其天然适合"文档入库前先生成领域词汇表"的预处理场景，例如为检索增强（RAG）流程提供术语层面的辅助索引，或为分类/搜索相关性任务沉淀可复用的公司内部行话集合。