Hyper-Extract Knowledge Base Directory
定义
Hyper-Extract Knowledge Base Directory 是 Hyper-Extract CLI 使用的本地知识库目录，用来持久保存一次或多次抽取后的知识图数据与元数据。
它通常由 he parse ... -o <目录> 首次创建，然后被后续命令继续读取和利用，包括 he show、he search、he talk、he info、he build-index，以及用于增量追加内容的 [he feed - Hyper-Extract 摘要](/wiki/it/ai/source/he%20feed%20-%20Hyper-Extract%20%E6%91%98%E8%A6%81)。
在增量更新语境里，这个目录不是“随便指定一个输出路径”即可，而是 he feed 的目标对象本身：命令会把它当作一个已经存在、已经初始化完成、并且可继续合并写入的 knowledge abstract 目录。
在命令行工作流中的语境
在 Hyper-Extract CLI Workflow 中，常见顺序是先用 he parse 生成初始目录，再在后续时间点不断向同一目录执行 he feed。
典型流程是：
- 第一次抽取：
he parse <输入> -o ./kb/ ... - 浏览当前结果：
he show ./kb/ - 增量加入新文档：
he feed ./kb/ <新输入> - 如需让新增内容参与搜索或问答：
he build-index ./kb/ - 然后再用
he search ./kb/或he talk ./kb/
因此，这个目录既是展示、检索、问答的持久化基础，也是持续增量写入的承载对象。
作为 he feed 目标时的硬性约束
he feed 的命令格式是：
he feed KA_PATH INPUT [OPTIONS]
其中 KA_PATH 明确要求是“existing knowledge abstract directory”，也就是一个现有的知识库目录，而不是一个尚未创建的新目录。
这意味着：
- 不能把一个空目录直接当作有效目标；
- 不能把普通文件目录误当作知识库目录；
- 不能跳过
he parse或其他合法初始化步骤，直接对任意路径执行he feed。
如果目录不具备有效结构，he feed 会拒绝继续。
有效目录的校验方式
文档给出的直接校验方式是检查目录内是否包含以下两个关键文件：
data.jsonmetadata.json
命令示例：
ls ./ka/
# Should contain: data.json, metadata.json
如果缺少这些关键文件，命令会报错：
Not a valid Knowledge Abstract directory
因此，data.json 与 metadata.json 不只是实现细节，而是 he feed 判断目标目录是否为有效 knowledge abstract 的最基本结构标志。
关键机制：he feed 读取旧状态后再合并写回
这个目录在增量喂入时的核心机制，不是“把新文档重新解析后覆盖整个目录”，而是“先读旧知识，再并入新知识”。
he feed 的描述明确包含四个步骤：
- Loads existing knowledge：先读取目录中的当前知识状态；
- Extracts from new document：再对新输入文档执行抽取；
- Merges intelligently：把新旧结果做智能合并，并处理重复；
- Updates metadata：最后更新元数据中的更新时间。
这说明 Hyper-Extract Knowledge Base Directory 在 he feed 场景下是一个可累积演化的知识容器，而不是每次重新生成的静态产物。
合并行为：目录内容会如何变化
根据 he feed 的合并规则，目录中的数据会随着新增文档而增加或更新，而不是简单追加原始文本。
文档列出的典型合并场景包括：
| 场景 | 行为 |
|---|---|
| Same entity | 合并为同一实体，描述会组合在一起 |
| Same relation | 使用较新的信息更新该关系 |
| New entities | 作为新实体加入知识库 |
| New relations | 作为新关系加入，并连接已有实体或新实体 |
这意味着目录中的 data.json 所承载的图数据会出现以下变化：
- 节点数量可能增加；
- 边数量可能增加；
- 已存在节点的描述可能更完整；
- 已存在关系的内容可能被更新为更新的信息；
- 新文档中的知识可能连接到旧文档中已经存在的实体，而不是孤立保存。
这一行为与 Hyper-Extract Incremental Merge Behavior 直接相关：增量喂入的价值不只是“追加文件”，而是把多轮输入统一沉淀到同一个可演化知识图中。
元数据变化：更新时间会刷新
除了图数据本身，目录中的元数据也会在每次 feed 后发生变化。
文档明确指出，he feed 会执行 Updates metadata，并“Records the update timestamp”。因此，metadata.json 中的更新时间戳会在每次成功喂入后刷新。
验证喂入是否成功时，官方建议重点查看三类变化：
- 节点数是否增加；
- 边数是否增加；
- 时间戳是否更新。
所以，这个目录的“最新状态”不只是体现在图谱内容上，也体现在元数据的更新时间上。
模板与语言：可覆盖，但最好与现有目录保持一致
he feed 提供两个可选参数：
--template/-t：覆盖模板；若省略，则使用元数据中的模板；--lang/-l：覆盖语言；若省略，则使用元数据中的语言。
这说明目录中的元数据本身保存了后续喂入所需的上下文配置，he feed 默认会沿用现有目录的模板与语言设定，而不是要求每次都重新显式指定。
虽然命令允许通过参数覆盖，但最佳实践仍然是与现有目录保持一致：
- 模板最好保持兼容，尤其应使用同类图抽取模板；
- 语言最好保持一致，以获得更稳定的抽取与合并结果。
文档在 Best Practices 中明确建议：
- Use same template：喂入应使用兼容模板；
- Match language：保持语言一致以获得最佳结果。
如果模板不一致，文档还专门列出 Template mismatch 作为错误处理场景，并给出覆盖示例：
he feed ./ka/ doc.md -t general/biography_graph
因此，模板与语言虽然不是绝对不能改，但它们与目录已有元数据之间存在明显的兼容性边界；覆盖参数是例外手段，不应成为默认做法。
与索引的关系：增量喂入后常常还不够
Hyper-Extract Knowledge Base Directory 在 he feed 后虽然已经保存了更新后的知识图，但如果要把新增内容用于搜索或聊天，还需要处理索引层。
he feed 文档的最佳实践明确写到：
- Rebuild index after —
he build-index ./ka/for search/chat
这表示目录中的图数据更新，并不自动等价于检索与问答索引已经同步更新。
因此，对于依赖 Hyper-Extract CLI Retrieval and QA 的场景，应理解为两层状态：
- 知识目录本身已经通过
he feed更新； - 但如果要让
he search或he talk使用这些新增知识，通常还要重新执行he build-index。
在工作流示例中，这一点也很清楚：在连续多次 he feed 后，才执行 he build-index ./research_kb/，然后再进行 he talk 提问。
适用场景
这个目录结构特别适合以下增量知识构建场景：
- 随时间逐步建设知识库；
- 对同一主题持续加入更新版本文档；
- 把多个来源的相关资料汇入同一个知识图。
文档示例包括：
- 先解析初始论文，再在第 7 天喂入更新版，第 14 天再喂入相关工作；
- 先解析人物早年经历，再喂入职业阶段，再喂入晚年阶段；
- 连续向同一目录喂入多个
doc1.md、doc2.md、doc3.md； - 从标准输入把新内容管道传给
he feed ./ka/ -。
这些例子共同说明：目录的价值在于长期复用同一个知识容器，而不是每份输入都生成一个彼此独立的新结果目录。
细节与边界
1. 目录必须先存在
he feed 面向的是“existing knowledge abstract directory”。如果目录还没初始化，应先通过 he parse 创建知识库目录，再进行喂入。
2. 有效性不是只看路径存在
即使路径存在，只要缺少 data.json 或 metadata.json，仍会被判定为无效目录，并报 Not a valid Knowledge Abstract directory。
3. 默认行为是沿用目录元数据
省略 -t 或 -l 时，命令会使用目录现有元数据中的模板和语言。这使得目录不仅保存知识数据，也保存后续增量操作的默认上下文。
4. feed 更新的是知识状态，不是搜索索引
目录内容更新后，不代表检索与问答已经自动同步。若后续要搜索或聊天，需要重建索引。
5. 成功与否可通过结构化迹象验证
除了命令返回是否报错，还可以通过查看节点数、边数、更新时间戳是否变化来判断喂入是否生效。