W
AI-Wiki
SOURCE

CLI Workflow Guide 摘要

文档概览

该页是一份按步骤组织的 Hyper-Extract CLI 工作流指南，主线场景是“研究论文分析”。它不是只列命令，而是把一个从输入文档到抽取、探索、检索、问答、增量更新再到索引维护的完整流程串起来。页面结构依次覆盖：

  • 准备文档
  • 解析知识
  • 探索知识
  • 搜索信息
  • 与知识问答
  • 扩充知识库
  • 重建索引
  • 完整脚本示例
  • 批处理
  • 常见模式
  • 故障排查

文中反复使用的示例输入文件是 transformer_paper.md，核心模板是 general/concept_graph，语言参数示例为 -l en。这说明该页默认展示的是英文研究论文上的概念图抽取流程，可与 Hyper-Extract CLI Workflow、Hyper-Extract CLI Retrieval and QA、Hyper-Extract Knowledge Base Directory 对照理解。

关键事实

场景与输入前提

页面设定的用户场景是研究者希望从学术论文中抽取并交互式使用知识。指南说明 Hyper-Extract 支持 .md 和 .txt 文件，并给出一个示例研究论文下载链接，要求把文件保存为 transformer_paper.md 以跟随后续命令。

虽然下载链接对应的是一个 .txt 样例，但文档明确要求在工作目录中将其保存为 transformer_paper.md。后续所有命令都围绕这个文件展开。

解析命令：he parse

用于知识抽取的核心命令示例如下：

he parse transformer_paper.md -t general/concept_graph -o ./transformer_kb/ -l en

该命令体现了几个关键参数：

  • 输入文件：transformer_paper.md
  • 模板：-t general/concept_graph
  • 输出目录：-o ./transformer_kb/
  • 语言：-l en

页面对 he parse 之后会发生什么给出了明确说明：

  1. 读取文档。
  2. 如果文档较长，则执行分块。
  3. 由 LLM 抽取实体和关系。
  4. 将结果写入 ./transformer_kb/。

这部分信息很关键，因为它不只是说“做了解析”，而是说明了管线包含长文分块与基于 LLM 的实体/关系抽取两个阶段。

解析结果目录结构

文档给出的输出目录示例如下：

./transformer_kb/
├── data.json # Extracted knowledge
├── metadata.json # Extraction metadata
└── index/ # Vector search index (if built)

可以据此确认，知识抽取结果至少包含：

  • data.json：抽取出的知识数据。
  • metadata.json：抽取相关元数据。
  • index/：向量检索索引；文中注明为“if built”，说明索引目录是否存在取决于是否已经建立索引。

这与 Hyper-Extract Knowledge Base Directory 直接相关，因为该页实际展示了一个最小可用知识库目录的典型组成。

查看统计：he info

探索知识的第一步是查看统计信息，命令示例如下：

he info ./transformer_kb/

页面给出的输出样例如下：

Knowledge Abstract Info

Path ./transformer_kb/
Template general/concept_graph
Language en
Created 2024-01-15 10:30:00
Updated 2024-01-15 10:30:00
Nodes 12
Edges 15
Index Built

从这个样例可见，he info 至少会展示这些统计字段或状态：

  • 路径（Path）
  • 模板（Template）
  • 语言（Language）
  • 创建时间（Created）
  • 更新时间（Updated）
  • 节点数（Nodes）
  • 边数（Edges）
  • 索引状态（Index Built）

文中没有额外解释这些字段的内部计算方式，但通过样例已经能确认这是用来快速审查知识库当前状态的命令。

图谱可视化：he show

页面给出的可视化命令是：

he show ./transformer_kb/

其作用不是在终端输出文本，而是在浏览器中打开交互式图谱。页面明确说明，这个图会显示：

  • 节点（Nodes）：例如 authors、concepts、models、metrics
  • 边（Edges）：表示这些节点之间的关系

这表明 he show 针对的是图结构的交互式浏览，而不是单纯导出静态图。示例中列出的节点类别也能帮助理解研究论文场景下抽取出的知识类型。

页面把信息检索分成语义搜索和更具体的查询两部分。基础搜索示例如下：

he search ./transformer_kb/ "neural network architecture"

文档特别强调其特征是：即使关键词不精确匹配，也能找到相关信息。也就是说，这不是严格的关键词全文匹配，而是语义检索。

返回结果样例如下：

Found 3 result(s):

Result 1:
{
"name": "Transformer",
"type": "model",
"description": "A neural network architecture based solely on attention mechanisms"
}

Result 2:
{
"name": "Attention Mechanism",
"type": "concept",
"description": "Mechanism to draw global dependencies between sequences"
}
...

这个结果样例说明每条命中结果至少以类似 JSON 的结构展示，字段包括：

  • name
  • type
  • description

并且示例中第一条把“neural network architecture”的查询映射到了 Transformer，这正是“关键词不必精确匹配”的直接证据。

页面还给出一个更具体的查询示例：

he search ./transformer_kb/ "performance metrics" -n 5

这里的 -n 5 表示控制返回结果数量。

问答：he talk

页面将问答分为单轮问题和交互模式。单轮命令示例如下：

he talk ./transformer_kb/ -q "What is the main contribution of this paper?"

示例回答指出，该论文的主要贡献是提出 Transformer 架构；该架构在机器翻译任务上达到 state-of-the-art，同时比循环或卷积架构更易并行，并且显著减少训练时间。这个回答说明 he talk 不是简单摘录某一条节点描述，而是能基于知识库组织成自然语言答案。

交互模式命令为：

he talk ./transformer_kb/ -i

页面给出了一段完整会话：

  • 进入交互模式后，提示输入 exit 或 quit 停止。
  • 提问作者是谁时，回答列出了论文作者：Ashish Vaswani、Noam Shazeer、Niki Parmar、Jakob Uszkoreit、Llion Jones、Aidan N. Gomez、Lukasz Kaiser、Illia Polosukhin。
  • 提问 BLEU 分数时，回答模型在 WMT 2014 英译德任务上达到 28.4 BLEU。
  • 输入 exit 后会结束并显示 Goodbye!。

这部分是研究论文分析场景下最具体的一组例子，说明系统可在同一会话内连续回答关于作者、实验指标等问题，属于 Hyper-Extract CLI Retrieval and QA 的直接来源材料。

扩充知识库：he feed

在已有知识库上添加新文档的示例如下：

# Download another paper
curl -o bert_paper.md https://example.com/bert.md

# Add to existing knowledge abstract
he feed ./transformer_kb/ bert_paper.md

该步骤表达的是增量更新而不是重建新库：把另一篇论文 bert_paper.md 加入已有的 ./transformer_kb/。

添加之后，页面要求再次执行：

he info ./transformer_kb/

并特别指出应注意两个变化：

  • 节点数/边数增加
  • 更新时间戳更新

这说明 he feed 会改变现有知识库的内容规模与元数据时间信息。

重建索引：he build-index

在新增文档后，页面建议按需重建搜索索引。命令示例如下：

he build-index ./transformer_kb/

如果需要强制完整重建，则使用：

he build-index ./transformer_kb/ -f

文中的语境是“After adding documents, rebuild the search index”，即在执行过 he feed 等增量写入后，为了让检索索引与数据同步，需要重新建索引。-f 则表示强制执行完整重建。

模板列表：he list template

页面在故障排查表中提到，当遇到“Template not found”时，解决办法是列出可用模板：

he list template

这虽不是主流程中的步骤命令，但属于排错时的重要辅助命令。

重要细节

完整脚本示例

页面给出了一份 bash 脚本，把解析、查看信息、执行搜索、打开可视化串成一个自动化流程。脚本中的配置变量是：

INPUT_FILE="paper.md"
OUTPUT_DIR="./paper_kb/"
TEMPLATE="general/concept_graph"
LANGUAGE="en"

随后依次执行：

  1. he parse "$INPUT_FILE" -t "$TEMPLATE" -o "$OUTPUT_DIR" -l "$LANGUAGE"
  2. he info "$OUTPUT_DIR"
  3. he search "$OUTPUT_DIR" "main contributions" -n 2
  4. he show "$OUTPUT_DIR"

这个脚本与前文逐步演示是同一套工作流的自动化包装，适合作为 Hyper-Extract CLI Workflow 的最小脚本模板。

批处理

页面的高级部分展示了如何一次处理多个文档。第一种方式是显式创建多个输出目录并逐个执行：

mkdir -p ./ka/paper1 ./ka/paper2 ./ka/paper3

he parse papers/paper1.md -t general/concept_graph -o ./ka/paper1/ -l en
he parse papers/paper2.md -t general/concept_graph -o ./ka/paper2/ -l en
he parse papers/paper3.md -t general/concept_graph -o ./ka/paper3/ -l en

第二种方式是使用循环：

for file in papers/*.md; do
name=$(basename "$file" .md)
he parse "$file" -t general/concept_graph -o "./ka/$name/" -l en
done

这里的关键点在于：每个文档都有独立输出目录，模板仍是 general/concept_graph，语言仍是 en。

常见模式

页面列出三种工作模式示例，适合用于理解 CLI 在不同项目中的使用方式。

模式 1：持续构建知识库

# Initial extraction
he parse initial_doc.md -t general/biography_graph -o ./ka/ -l en

# Weekly updates