Hyper-Extract 架构深潜：三层架构与数据流完全解析-开发者社区

Hyper-Extract 架构深潜：三层架构与数据流完全解析

【免费下载链接】Hyper-ExtractHypergraph is more powerful. Transform unstructured text into structured knowledge with LLMs. Graphs, hypergraphs, and spatio-temporal extractions — with one command.项目地址: https://gitcode.com/GitHub_Trending/hy/Hyper-Extract

Hyper-Extract 是一个用 LLM 将非结构化文本转化为结构化知识的开源工具，其核心由模板（Template）、方法（Methods）、自动类型（Auto-Types）组成的三层架构驱动，配合"分块 → 提取 → 合并 → 索引"的数据流，一条命令即可生成图谱、超图、时空结构等 8 种知识形态。本文带你完整走查它的架构设计与数据流转过程。

上图展示了完整的分层视图：顶层是he命令行接口，中层是核心引擎（左接 Templates、右接 Methods），底层是 8 种 Auto-Types 数据结构。

一、三层架构总览：从命令到知识

Hyper-Extract 的设计可以概括为"三个问题"：长什么样（数据结构）、怎么提（算法）、怎么配置（领域），分别对应三层组件。

层级	组件	职责	源码位置
第 1 层：数据层	Auto-Types（8 种类型）	定义提取输出的数据结构，内置搜索、可视化、保存能力	hyperextract/types/base.py
第 2 层：算法层	Methods（RAG + 典型方法）	决定如何处理文本、识别实体与关系	hyperextract/methods/registry.py
第 3 层：接口层	Templates + CLI / Python SDK	80+ 预设模板封装领域配置，用户一条命令即可用	hyperextract/utils/template_engine/template.py

这种自底向上的分层意味着：用户只接触第 3 层（模板名 + 一条命令），算法与数据结构被完全封装。想深入设计文档，可参考 docs/zh/concepts/architecture.md。

1. 自动类型（Auto-Types）：8 种知识容器

自动类型是整个架构的地基。它们分为三大类：

记录类型：AutoModel（单条结构化记录）、AutoList（有序列表）、AutoSet（去重集合）
图谱类型：AutoGraph（二元关系）、AutoHypergraph（多实体关系）、AutoTemporalGraph（时间线）、AutoSpatialGraph（空间）、AutoSpatioTemporalGraph（时空结合）
语料类型：AutoDocument（块级检索，零提取成本）

每种类型都是"自包含"的：基于 Pydantic 的类型校验保证数据一致性，同时内置search()、chat()、show()、dump()/load()等操作，源码见 hyperextract/types/ 目录。

图中左侧为记录类型（AutoModel / AutoList / AutoSet），右侧为图谱类型（AutoGraph 到 AutoSpatioTemporalGraph），直观展示了"数据结构层"的完整家族。

2. 方法（Methods）：可插拔的提取算法

方法层提供两套算法路线：

路线	代表方法	适合场景
典型方法（直接提取）	iText2KG、KG-Gen、Atom	中小文档，追求三元组质量
基于 RAG	GraphRAG、LightRAG、Hyper-RAG、Cog-RAG	大文档、复杂查询

方法采用注册表（Registry）插件架构：每个方法在导入时向全局注册表登记自己的类、类型和描述，核心引擎按模板声明的方法名查找并实例化。这套机制让新算法只需实现约定接口、调用一次注册即可接入，是典型的开闭原则实践，实现见 hyperextract/methods/registry.py。

3. 模板引擎（Template Engine）：用户唯一的入口

模板是 YAML 文件，声明"提取什么（schema）、怎么提示 LLM（guideline）、如何标识（identifiers）、如何显示（display）"。模板引擎由三个组件协作：

Template YAML → Gallery(发现) → Parser(解析/校验) → Factory(工厂) → Auto-Type 实例

Gallery：扫描 hyperextract/templates/presets/ 下 finance、legal、medical、tcm 等领域目录，提供模板查找与列表
Parser：解析 YAML 并生成 Pydantic schema，同时负责多语言本地化
Factory：根据type字段调用create_graph()、create_list()等工厂方法，装配 LLM 客户端与 Embedding 客户端，返回可用的 Auto-Type 实例

对 Python 用户来说，一切归结为一行代码Template.create("general/biography_graph")，统一入口实现见 hyperextract/utils/template_engine/template.py。

二、数据流全解析：从一段文本到可查询知识

以一条典型的he parse命令为例，文本在系统内经历四个阶段。

三阶段概览：文档输入 → AI 处理 → 结构化知识输出（List / Set / Graph / Hypergraph / Timeline）。

阶段 1：输入处理与分块

原始文本超过块大小（默认 2048 字符，重叠 256 字符）时会被自动切分为多个 chunk，切分点优先落在段落、句子边界上。分块让 LLM 调用可控，也让长文档具备并行处理的基础。

阶段 2：LLM 并行提取

每个 chunk 进入模板生成的 Prompt，调用 LLM 的结构化输出能力，响应被直接解析为 Pydantic 模型——这一步由 hyperextract/types/base.py 中的parse()方法驱动。默认 10 个并发工作线程同时处理各块，大幅缩短大文档的端到端耗时。

阶段 3：合并（Merge）

各块的结果并非简单拼接，合并阶段会执行三项关键操作：

实体去重——按模板定义的 identifier 规则识别同一实体
关系组合——跨块出现的相同关系边被聚合
冲突解决——同一字段出现矛盾值时按合并策略裁决

合并策略（merge strategy）可在模板的 options 中声明，解析器实现位于 hyperextract/utils/template_engine/parsers/options.py。

阶段 4：索引构建与查询

合并完成即得到一个填充好数据的 Auto-Type 实例。调用build_index()建立向量索引后，search()做检索、chat()结合上下文生成回答；feed_text()还支持增量更新——同来源的新文本会触发旧事实的回滚，保证知识库与源文档同步。整个持久化（dump/load）与查询链路都封装在类型实例内部，对用户完全透明。

三、数据流中的关键设计点

类型安全贯穿全程：从模板 YAML 到 LLM 结构化输出，全部经 Pydantic schema 校验，杜绝"LLM 自由发挥"导致的脏数据
配置即代码：换领域 = 换一个 YAML，无需改代码；80+ 预设模板覆盖金融、法律、医疗、工业、中医等场景，格式参考 docs/zh/concepts/templates-format.md
插件式扩展：自定义方法只需注册，自定义类型只需继承基类，两个扩展点互不干扰
标准格式互操作：提取结果以 JSON/YAML 落盘，并可导出 Obsidian、GraphML 等格式，方便与现有知识工作流集成

四、架构小结

Hyper-Extract 的三层架构把"知识提取"拆解为职责清晰的三个平面：Auto-Types 回答数据长什么样，Methods 回答知识怎么提，Templates 回答针对这个领域提什么；而"分块 → 并行提取 → 合并 → 索引"的数据流则保证了从单段文本到百万字文档的一致体验。理解这条链路后，无论你是想选择方法、定制模板还是扩展新类型，都能快速在正确的层级找到切入点。