打造自己的知识图谱构建工具

微信 ezpoda免费咨询：AI编程 | AI模型微调| AI私有化部署
AI工具导航 | Tripo 3D | Meshy AI | ElevenLabs | KlingAI | ArtSpace | Phot.AI | InVideo

LLM可以总结法律合同、回答关于医疗记录的问题、从研究论文中提取实体。但要求它们从任何这些文档中生成结构化、可信赖的知识图谱，你会花更多时间清理幻觉关系和断开连接的节点，而不是自己阅读文本。

所以你围绕它构建工具。如果你曾经这样做过，你知道它如何结束：一堆特定于提供商的脚本、硬编码的提示，以及一个run_pipeline_v3_FINAL_fixed.py，只有你能理解——而且只有在状态好的时候。

通用知识图谱提取器几乎每次都会比领域特定的提取器表现差——这是公认的。真正的问题始于你尝试使你的工具领域特定：突然间，你为每个领域维护单独的脚本，在提供商之间复制逻辑，看着一个干净的原型崩溃成一堆硬编码路径和复制粘贴提示的混乱。

Knowledge Graph Builder围绕一个特定的赌注构建——你可以在没有那些样板代码的情况下实现完整的领域专业化。框架中的每个组件都是独立可替换的，但整个东西仍然可以从单个命令运行。

在本文中，我们将介绍其架构：每个模块如何工作，它们如何组合成一个完整的提取-增强-可视化管道，以及为什么交换提供商、领域或输出格式只需更改一个标志——而不是重写你的管道。

你将学到什么：

• 五个独立模块——客户端、构建器、领域、 I/O（读取器和写入器）和可视化——如何通过注册表连接成单个管道。
• 为什么BaseLLMClient将有根据的提取与无约束的增强分开——以及为什么这种区分对图谱质量很重要。
• 自定义提供商子类如何让本地模型与云API一起工作，而无需对核心管道进行任何更改。
• 领域模块如何打包提示、少量示例和模式，以便从--domain legal切换到--domain medical会改变整个提取词汇。
• YAML配置的管道和CLI如何将四步工作流程变成单个可重现的命令，促进重用和存储而无需样板代码。

1、核心理念：抽象是大脑，CLI是心脏

Knowledge Graph Builder是一个模块化的Python框架，从非结构化文本中提取知识图谱，使用Google的langextract库获取有根据的三元组——锚定到源文本中特定字符位置的提取。从那里，它可以推断关系来增强这些图谱，将它们转换为标准格式，并可视化结果。

Knowledge Graph Builder架构概览：Builder协调Domains和Clients进行知识图谱构建，而Pipeline将完整工作流——从输入解析到可视化——包装在单个CLI下。图片由作者提供。

框架的架构围绕一个原则：

每个容易变化的组件都应该易于替换，保持整个框架用于创建知识图谱的可用性。

• LLM提供商变了？换客户端。
• 需要新的生成策略？添加构建器。
• 新领域？只需添加一个文件夹。
• 新的数据集输入格式？添加读取器。
• 新的图谱输出格式？添加写入器。

框架不强制你修改其核心来扩展它。

有五个主要模块：

• 客户端——LLM提供商的抽象包装器（Gemini、Ollama、LM Studio等）。
• 构建器——指示LLM执行不同任务以获取和改进知识图谱的核心逻辑。
• 领域——打包的提示模板、少量示例和实体/关系模式。
• I/O（读取器和写入器）——输入格式检测和图谱格式转换。
• 可视化——具有溯源颜色编码的交互式图谱渲染，专注于根据获取方法区分图谱元素。

每个模块都有一个注册表，将字符串键映射到实现，使它们可以通过CLI访问，而无需任何条件导入或冗长的配置。另外，你可以将完整过程包装在管道中，这是一个生活质量的改进，让你可以存储你喜欢的配置。

让我们逐一介绍它们。

2、构建器：实际工作发生的地方

在接触任何客户端或提供商之前，值得了解构建器——因为这是实际工作发生的地方。客户端不实现自己的提取逻辑；它们委托给构建器。

构建器定义了框架为获取知识图谱可采取行动的蓝图。

提取构建器

提取构建器处理提示构建、少量示例注入和三元组标准化。所有这些都统一到一个函数中，使用langextract集成其他模块。

目前，提取总是通过langextract有根据的，这意味着它返回的每个三元组都带有字符级源跨度——你总是确切知道文档中声明来自哪里。

使用LangExtract，每个三元组都锚定到源文本中的确切字符——所以你总是可以追溯声明产生它的句子。

增强构建器

增强构建器更加开放。它使用策略注册表——一种基于协议的模式，其中每个增强策略是一个使用装饰器将策略存储在注册表中的类。

协议指定所需的最小签名（客户端、领域提示、示例和真实三元组），但每个策略实现自己的逻辑。

这样，我们可以清晰地定义所需的最小参数，你可以专注于你的用例场景的特定逻辑。

目前唯一实现的策略是连接性，它通过推断桥接三元组来减少图谱中的断开连接组件。

添加新策略意味着编写一个类并应用装饰器。

提取和增强的区别

将提取与增强混合，你会失去使图谱可信赖的一点：知道哪些三元组来自文本，哪些是模型自己推断的。

将它们分开意味着你总是知道哪些三元组是断言的，哪些是推断的——这种区分对于依赖信任或可验证性的任何下游任务都极其重要。

3、一个接口，每个提供商

客户端层是提供商多样性被驯服的地方。每个提供商——无论是云API还是本地托管的模型——都必须实现BaseLLMClient，一个强制两个方法的抽象类：

class BaseLLMClient(ABC):

    @abstractmethod
    def extract(self, text, prompt_description, examples=None,
                format_type=None, temperature=None, max_tokens=None, **kwargs):
        """有根据的提取——返回带有源字符位置的三元组。"""
        pass

    @abstractmethod
    def augment(self, text, prompt_description, format_type,
                temperature=None, max_tokens=None, **kwargs):
        """无根据的增强——推断的三元组，不需要源跨度。"""
        pass

extract()和augment()之间的分离是有意的，因为它匹配构建器逻辑：

• 有根据的提取问：这个文本中明确陈述了什么？
• 增强问：给定我们所知道的以及增强策略，我们可以推断哪些节点和关系来填充图谱？

另外，每个提供商子类实现from_config()，它将扁平的ClientConfig对象转换为对其自身构造函数的调用。

这就是使CLI符合人体工程学的原因：你不必指定--api-key、--base-url、--timeout和--model作为在不同提供商之间含义不同的单独标志，而是传递单个配置对象，让每个客户端处理自己的默认值。

# 这三个调用从CLI的角度看行为相同：
ClientFactory.from_config(client_type="gemini",  model_id="gemini-2.0-flash", api_key="...")
ClientFactory.from_config(client_type="ollama",  model_id="gemma3:27b",       base_url="http://localhost:11434")
ClientFactory.from_config(client_type="lmstudio",model_id="gemma-3-27b-it",   base_url="http://localhost:1234")

ClientFactory维护提供商类的注册表，在导入时由每个提供商文件上的@client装饰器填充。

CLI不需要知道每个提供商是如何构建的——它只需调用ClientFactory.create(config)并返回一个完全初始化的实例。

4、领域：切换领域，改变一切

从语言模型获得好的输出——特别是对于像知识图谱提取这样的结构化任务——需要的不仅仅是一个聪明的提示。

你需要领域适当的词汇、精心选择的少量示例和约束输出的模式。领域模块将所有这些打包在一起，因为每个领域都是一个具有可预测结构的文件夹。这是法律领域的一个示例：

legal/
├── extraction/
│   ├── prompt.md
│   └── examples.json
├── augmentation/
│   └── connectivity/
│       ├── prompt.md
│       └── examples.json
└── schema.json

KnowledgeDomain抽象类从磁盘加载这些资源，提供组装提示所需的所有构建块。

增强策略有自己的子目录，所以每个策略都有自己的提示和示例，没有任何命名冲突。根据你的用例，可能有很多增强策略。

实际意义是显著的：

切换领域会改变整个提取词汇，而无需触及管道代码

领域注册表（使用与客户端注册表相同的装饰器模式）使领域可以通过名称在CLI中访问。这是框架一致的模式：到处都是基于约定的字符串注册，所以CLI保持精简。

5、I/O：无摩擦地获取数据进出

对于结构化提取，干净地获取数据进出与提取本身一样重要。

读取器子模块根据扩展名自动处理JSON、JSONL和CSV文件的格式检测和加载。load_records()函数接受可选的字段名称覆盖和限制参数，使在语料库子集上运行实验变得简单。

写入器子模块目前通过规范化管道输出**GraphML**，该管道在序列化之前清理和去重LLM生成的三元组。GraphML是正确的默认值：它与NetworkX、Gephi和大多数图谱分析工具兼容。

设计使添加新写入器变得容易——用于本体工作流的turtle，用于Neo4j的Cypher…

连接两者的Triple数据模型值得注意。每个三元组携带一个推理字段，标记为显式（直接陈述的）或上下文（增强步骤推断的），以及可选的上下文三元组理由。这种溯源一直保留到GraphML输出。

6、可视化：使图谱可读

即使获取的知识图谱的JSON输出格式适合存储所有信息，它在视觉上并不令人愉悦。

为了轻松评估生成的知识图谱的质量，可视化模块是必不可少的，因为它使结构对于策划或验证输出的领域专家可读。

在这个意义上，Knowledge Graph Builder保留了langextract的原始可视化用于真实检查——它在源文本中高亮显示提取的实体和关系，通过字符偏移标记。

通过langextract进行真实检查：提取的实体在源文本中高亮显示，按角色（头或尾）颜色编码，具有字符级偏移，让你可以追溯每个三元组到产生它的确切句子。回放控件逐一查看实体，便于按记录审核提取质量。图片由作者提供。

对于图谱本身，交互式网络可视化在浏览器中渲染完整的知识图谱。图谱一目了然地区分几个属性：

• 真实和增强的三元组通过颜色和边样式清晰区分，因此你可以立即看到连接性策略对图谱结构的改变程度。
• 每个节点的大小与度中心性成比例，使连接最多的实体显而易见。
• 节点可拖动，搜索栏实时过滤实体。
• 内置的路径查找器高亮任意两个节点之间的最短路径——对于追踪实体如何在图谱中连接很有用。
• 你可以切换布局，在深色和浅色主题之间切换，并将当前视图导出为PNG、SVG或JSON。

我们出于所有这些原因保留了HTML交互式可视化！

提取知识图谱的交互式网络可视化：节点大小反映度中心性，边颜色区分真实三元组和增强三元组，标签通过力导向布局保持可读。大的中心节点标记图谱中连接最多的实体——这种模式一目了然，但会埋没在原始JSON输出中。为了保持布局干净，只有连接最多的节点直接显示标签；其余的在悬停时显示名称，因此即使图谱增长，图谱也保持可读。图片由作者提供。

但对于更大的图谱，这种可视化变得不太实用——这是一个已知的限制，可能是未来工作的目标。

7、构建器作为知识图谱协调器

在这一点上，值得退后一步看看构建器如何与我们刚刚介绍的模块相关。构建器是唯一同时接触领域和客户端的组件——它从领域提取提示和示例，通过客户端路由它们，并验证结果。这使它成为涉及语言模型的所有内容的自然协调层：提取、增强、提示组装和输出验证都住在这里。

但构建器只关心LLM端。它不处理输入格式、图谱转换或可视化。对于完整的数据工程工作流，我们需要将构建器的协调包装到更广泛的管道中的东西——这正是下一个模块提供的。

构建器内部：输入记录流经提示组装和LLM执行（通过客户端），然后通过验证（受领域模式约束）后作为输出图谱离开。领域提供资源，客户端处理模型调用，构建器协调两者。图片由作者提供。

8、管道：一切融为一体

构建器有效地抽象了所有语言模型在构建知识图谱中的使用，但对于整个数据工程管道来说还不够。

上面的所有五个模块单独使用都有用，但真正的价值来自于组合它们。

为了解决这个问题，管道模块提供外部协调层——一种将完整提取工作流声明为可重用、版本控制配置的方式。

该模块有三个组件：

• PipelineContext是数据载体：它保存记录ID、源文本、累积的三元组、元数据和错误，供单个文档在管道中流动时使用，保持可追溯性。
• PipelineRunner对一批上下文执行有序的步骤列表，使用ThreadPoolExecutor进行并行处理。
• YAML配置文件将整个管道——客户端、领域、输入和步骤参数——声明为单个可移植文档。

目前，管道中注册了六个步骤：

以下是一个管道YAML文件示例，为你的实验集成所有先前的操作：

client:
  type: gemini
  model: gemini-2.0-flash

domain:
  name: legal
  extraction_mode: open

input:
  path: data/legal/legal_background.jsonl
  text_field: text

output_dir: outputs/kg_extraction

steps:
  - extract
  - augment:
      max_disconnected: 1
      max_iterations: 5
  - convert
  - visualize-network

此配置可重现、可共享且可覆盖：任何值都可以在调用时通过CLI标志替换，因此你可以使用相同的基底配方配合不同的输入文件或模型配置。

但如果我们不介绍蛋糕上的樱桃：CLI，我们就无法完成对框架的讨论，这是我们用于轻松执行我们已存储的所有不同配置的最后生活质量功能。

9、CLI：一个命令运行所有

以上描述的所有内容都可以从单个kgb控制台脚本访问。每个命令做一件事，并产生下一个命令可以消费的输出。

我们可以用CLI运行每个细粒度的步骤来构建管道（提取、增强、转换、可视化…）。

# 第1步——有根据的提取：带有字符级源锚点的三元组
kgb extract --input data/legal/legal_background.jsonl \
            --domain legal --client gemini --model gemini-2.0-flash

# 第2步——增强：推断桥接三元组以减少断开连接的组件
kgb augment connectivity --input data/legal/legal_background.jsonl \
            --domain legal --client gemini --max-disconnected 1 --max-iterations 5

# 第3步——转换为GraphML
kgb convert --input outputs/kg_extraction/extracted_json

# 第4步——可视化
kgb visualize network --input outputs/kg_extraction/graphml --dark-mode
kgb visualize extraction --input data/legal/legal_background.jsonl \
            --triples outputs/kg_extraction/extracted_json

或者直接使用命令run-pipeline执行定义的YAML中存储的管道。

# 基于标志：切换各个阶段
kgb run-pipeline --input data/legal/legal_background.jsonl \
                 --domain legal --client gemini \
                 --extract --augment --convert --visualize

# 基于配置：加载可重用的YAML配方
kgb run-pipeline --config kgb/pipeline/configs/legal_gemini.yaml

另外，只运行"kgb"不带参数会启动一个带有readline历史和制表符补全的交互式终端，在测试配置时很有用。这个工具是用Typer CLI构建的。

10、这个架构真正为你带来了什么

值得退后一步阐述模块化设计实现了什么——而不仅仅是它包含什么。

提供商独立性。对Gemini、本地Ollama实例和LM Studio运行相同的提取不需要对管道进行任何更改。这对于成本管理（迭代用本地模型，生产用云API）和我们将在下一篇文章中探讨的比较评估都很重要。

领域可移植性。相同的管道代码可以通过切换一个标志来处理法律文档、医疗记录或科学文献。提取词汇、示例和约束都随领域文件夹走，而不是代码。

可重现性。YAML管道配置可版本控制和共享。任何可以访问相同模型和领域的人都可以精确重现你的图谱。

增量采用。你可以使用预先存在的数据进入管道的任何阶段。如果你已经有JSON格式的提取三元组，你不需要重新运行提取来测试新的可视化。

11、接下来是什么

框架架构是基础。但框架只有在你投入工作时才能证明其价值。

在下一篇文章中，我们将对13个模型配置运行系统评估——覆盖Gemini 2.0 Flash、Gemini 2.5 Flash、几个Gemini 3变体，以及通过Ollama和LM Studio的多个Gemma模型——针对法律语料库。我们将比较提取质量、增强行为，以及通过云API与本地推理运行这些模型的实际差异。

结果揭示了一些真正令人惊讶的模式——关于哪些提供商实际上在提取质量上有所表现，模型大小真正有多重要，以及本地推理在哪里与云API相当。并不总是你预期的结果。

从run_pipeline_v3_FINAL到kgb run-pipeline

开头的那堆特定于提供商的脚本和复制粘贴的提示？Knowledge Graph Builder用五个可交换的模块、保持CLI精简的注册表模式，以及一个可以版本控制和共享的YAML配置替换了它。一个命令，完整的溯源，任何提供商。

Knowledge Graph Builder仓库可在GitHub上获取。它附带每个后端的shell脚本、我们即将进行的评估中使用的法律领域配置，以及用于入门的YAML管道模板。

原文链接: From Text to Knowledge Graph in One Command: Building a Modular LLM-Backed Framework

汇智网翻译整理，转载请标明出处