yifanfeng97 Hyper-Extract README 摘要

文档概览

• README 首页把 Hyper-Extract 直接定义为 Smart Knowledge Extraction CLI。
• 它的核心承诺是：Transform documents into structured knowledge with one command，即用一条命令把文档转成结构化知识。
• README 对项目的完整定位是：这是一套由 LLM 驱动的知识抽取与演化框架，用来把“高度非结构化文本”转换为持久化、可预测、强类型的 Knowledge Abstract。
• 这里的“强类型”不是泛泛而谈。README 明确强调输出可以落到具体的数据结构上，从简单集合、Pydantic Model，一直到知识图谱、超图、时空图。
• README 同时把项目包装成一条完整工作流，而不是单一抽取脚本：既支持命令行抽取，也支持 Python API、语义搜索、图可视化、Obsidian 导出，以及通过 MCP Server 暴露给 Claude Desktop 与 IDE agents。

关键事实

项目定位

• README 的一句话定位是：Smart Knowledge Extraction CLI。
• 它希望解决的问题不是“让模型总结一下”，而是把非结构化文档转为：
• 1. 结构化：输出有明确 schema 与字段。
• 2. 持久化：结果可以保存为知识库，而不是一次性会话答案。
• 3. 可预测：抽取结果依赖模板与类型约束，减少自由发挥。
• 4. 强类型：输出落在预定义知识结构中，而非松散 JSON。

README 强调的核心能力

• 8 种知识结构。
• 10+ extraction engines。
• 80+ YAML 模板。
• 增量演化：新文档可以随时继续喂给已有知识库，以扩展和修正知识。
• Obsidian 导出：任意抽取出的图可以转成包含 Markdown 笔记与 wikilinks 的 vault。

支持的知识结构类型

README 在架构说明中把 Auto-Types 明确列成 8 种强类型结构：

• Model
• List
• Set
• Graph
• Hypergraph
• Temporal Graph
• Spatial Graph
• Spatio-Temporal Graph

这 8 种类型也是 README 中“Supported Knowledge Structures”部分的核心卖点，表示项目不仅做普通知识图谱，还覆盖时间、空间和超边关系。

支持的平台与模型

README 明确说 Hyper-Extract 依赖 LLM 的结构化输出能力，即需要模型支持 json_schema 或 Function Calling。

已验证的平台与模型包括：

• OpenAI：gpt-4o、gpt-4o-mini、gpt-5
• Anthropic：claude-opus-4-8、claude-sonnet-4-6、claude-haiku-4-5
• 阿里云百炼：qwen-plus、qwen-turbo、deepseek-r1
• 本地 vLLM：Qwen3.5-9B (GPTQ-Marlin)

关于 embedding，README 给出的约束很明确：

• 语义搜索所用 embedding 模型必须能通过 OpenAI-compatible endpoint 访问。
• README 举的 embedding 例子包括：text-embedding-3-small、百炼的 text-embedding-v4、本地 vLLM 的 bge-m3。
• 也就是说，LLM provider 可以是 Anthropic 或其他平台，但 embedding 这部分仍要求兼容 OpenAI 风格接口。

Anthropic 还有一条额外边界条件：

• Claude 只用于 LLM。
• Anthropic 没有 embeddings API。
• 因此必须搭配一个 OpenAI-compatible embedder。README 直接给出示例：create_client(llm="anthropic", embedder="openai:text-embedding-3-small")。
• 使用 Anthropic 还需要安装额外依赖：pip install 'hyperextract[anthropic]'。

快速开始工作流

README 的“30-Second Quick Start”给出了一条完整 CLI 路径：

# Install
uv tool install hyperextract

# Configure API key
he config init -k YOUR_OPENAI_API_KEY

# Extract knowledge from a document
he parse examples/en/tesla.md -t general/biography_graph -o ./output/ -l en

# Query it
he search ./output/ "What are Tesla's major achievements?"

# Visualize
he show ./output/

# Export to an Obsidian vault (Markdown notes + wikilinks)
he export obsidian ./output/ -o ./vault/

这个流程对应的步骤分别是：

• 安装 CLI：uv tool install hyperextract。
• 初始化 API key：he config init -k YOUR_OPENAI_API_KEY。
• 抽取：he parse，示例使用 general/biography_graph 模板，把 tesla.md 解析到 ./output/，并显式指定语言 -l en。
• 检索：he search，说明输出不是静态文件，还可以做语义查询。
• 可视化：he show，用于展示抽取后的知识图。
• 导出：he export obsidian，把结果导成可在 Obsidian 中浏览的 Markdown + wikilinks 知识库。

Python API 最小示例

README 把 Python API 压缩成一个非常短的最小用法，核心是 Template.create、parse、show：

from hyperextract import Template

ka = Template.create("general/biography_graph")

with open("examples/en/tesla.md") as f:
    result = ka.parse(f.read())

result.show()

从这个例子可以看出：

• 入口类是 Template。
• 先通过 Template.create("general/biography_graph") 生成一个模板实例。
• 再把文档内容作为字符串传给 parse()。
• 返回结果对象支持 show()，说明 Python API 也具备可视化或展示能力。
• README 对 Python 安装建议是：uv pip install hyperextract。

三层架构

README 在“What's under the hood?”部分明确给出三层架构：

• Auto-Types：8 种强类型数据结构。
• Methods：抽取算法层。
• Templates：80+ 预设模板，覆盖 6 个领域，主打 zero-code setup。

其中 Methods 层 README 明确列出的代表方法包括：

• KG-Gen
• GraphRAG
• LightRAG
• Hyper-RAG
• Cog-RAG

README 其他部分还把 GraphRAG、LightRAG、Hyper-RAG、KG-Gen 反复拿来做对比或卖点展示，说明项目不是只实现单一 RAG 路线，而是把多种抽取/构图方法纳入同一个模板化框架。

重要细节

README 中列出的新增功能

“What's New”部分给出若干近期新增点，能看出项目已经从单纯抽取扩展到周边工具链：

• MCP Server：可以通过 he-mcp 从 Claude Desktop 和 IDE agents 查询知识抽象。标注为 PR #40。
• Anthropic Claude Support：可直接使用 claude-opus-4-8、claude-sonnet-4-6、claude-haiku-4-5。标注为 PR #38。
• Obsidian Export：任意图可导成带 wikilinks 的 Obsidian vault。标注为 PR #37。
• he clean：可移除某个 KA 的索引或整个知识抽象。标注为 PR #39。
• Reliability Fixes：包括 multi-chunk embeddings 采用真实 mean、限制 OpenAI-compatible 批量大小、修复多词 llm_* merge strategies。对应 PR #35、#36、#41。

这些更新说明 README 所称的“knowledge extraction and evolution framework”不仅包含解析，还包括索引、清理、导出和面向 Agent 的接入。

用例定位

README 用三个简短场景示范项目边界：

• 研究者场景：给一篇 20 页论文，得到关键概念、作者、引用关系的交互图。示例命令是 he parse paper.pdf -t general/academic_graph -o ./paper_kb/，之后 he show ./paper_kb/。
• 金融分析场景：从财报中自动识别公司、高管、财务指标及其关系。示例模板是 finance/earnings_graph，并用 he search 询问 “What are the key risk factors?”。
• 本地部署场景：用 vLLM 本地运行 Qwen3.5-9B + bge-m3，并明确声称“没有数据离开你的机器”。对应示例里 LLM 与 embedder 都走本地 http://localhost:8000/v1 与 http://localhost:8001/v1。

本地 vLLM 代码示例如下：

from hyperextract import create_client
llm, emb = create_client(
    llm="vllm:Qwen3.5-9B@http://localhost:8000/v1",
    embedder="vllm:bge-m3@http://localhost:8001/v1",
    api_key="dummy",
)

这里有两个值得保留的条件：

• 本地模式下依然使用 provider 字符串约定来声明模型和 endpoint。
• 示例里 api_key 使用 dummy，说明对于本地 OpenAI-compatible 服务，形式上可能仍需要传 key 参数，但不一定是真实远程密钥。

与其他方案的比较口径

README 用一个对比表把自己和 GraphRAG、LightRAG、KG-Gen、ATOM 放在一起，强调的优势点主要有：

• 支持普通 Knowledge Graph。
• 支持 Temporal Graph。
• 支持 Spatial Graph。
• 支持 Hypergraph。
• 支持 Domain Templates。
• 支持 Interactive CLI。
• 支持 Multi-language。

其中 README 的比较口径尤其突出几个差异：

• Spatial Graph 与 Hypergraph 是 Hyper-Extract 独有卖点。
• Domain Templates 被视为关键能力，而不只是附带资源。
• Interactive CLI 与 Multi-language 也被当作和学术方案区分的产品化特征。

模板系统的具体含义

README 把模板系统描述为“80+ presets across 6 domains”，并强调零代码使用。

• 这意味着用户不一定要先写 schema 或 prompt，可以直接选预设模板。
• README 点名的覆盖领域包括：Finance、Legal、Medical、TCM、Industry、General。
• 模板文件采用 YAML。
• README 同时提供两个方向：浏览现成模板，以及创建自定义模板。

README 给出的 Graph 类型模板示例包含以下关键结构：

language: en
name: Knowledge Graph
type: graph
tags: [general]
description: 'Extract entities and their relationships.'
output:
  entities:
    fields:
      - name: name
        type: str
      - name: type
        type: str
      - name: description
        type: str
  relations:
    fields:
      - name: source
        type: str
      - name: target
        type: str
      - name: type
        type: str
identifiers:
  entity_id: name
  relation_id: '{source}|{type}|{target}'

这个示例说明模板不只是 prompt 别名，而是至少包含：

• 语言 language
• 模板名 name
• 结构类型 type
• 标签 tags
• 说明 description
• 输出字段定义 output
• 实体与关系的标识规则 identifiers

尤其 relation_id: '{source}|{type}|{target}' 这类配置，说明 README 所说的“predictable”与“persistent”依赖稳定 ID 设计，而不是简单抽取后丢出一份文本。

MCP Server 的边界

README 单独列出 MCP Server，并说明它是把知识抽象暴露给支持 MCP 的助手。

• 目标客户端包括 Claude Desktop 和 IDE agents。
• 安装方式：pip install 'hyperextract[mcp]'。
• 启动命令：he-mcp。
• 运行形式：stdio MCP server。
• 权限描述是 read + export only，也就是偏只读与导出，不强调远程写入知识库。

README 列出的 MCP tools 包括：

• list_templates
• info
• search
• ask（RAG）
• export_obsidian

这说明 MCP 并不是简单把 CLI 包一层，而是暴露了一组围绕模板、检索、问答和导出的可调用工具。

Obsidian 导出的意义

README 多次强调 Obsidian 导出，不只在 quick start 里提一次。

• 导出对象是“any extracted graph”。
• 产物是一个 Obsidian vault。
• 内容形态是 Markdown notes。
• 节点之间通过 wikilinks 关联。

这意味着 Hyper-Extract 的输出目标并不局限于程序消费，还明显面向个人知识管理与人工浏览场景。

安装与环境约束

README 首页给出了几个明确的技术边界：

• Python 版本要求：3.11+。
• License：Apache-2.0。
• 文档站点在线可访问。
• PyPI 包名为 hyperextract。

这些信息虽然是徽章和附属信息，但对部署与依赖判断是有效事实。

安全与镜像

README 末尾有两条常被忽略但应记录的信息：

• 项目已由 MseeP.ai 做过 security assessed。README 没有展开审计范围、方法或结论细节，只给出评估声明。
• 另提供 AtomGit mirror，用于在中国更方便访问与克隆，地址为 https://atomgit.com/yifanfeng97/Hyper-Extract。README 把它描述为同步镜像。

相关条目

• Hyper-Extract
• Knowledge Abstract
• Auto-Types
• 知识抽取模板
• Obsidian
• GraphRAG
• LightRAG
• Hyper-RAG
• KG-Gen
• MCP Server