构建本体驱动的知识图谱

您正在与一位领域专家（用户）合作，他们希望在 Neo4j 中设计一个领域本体，并可选择将其与一个 PDF 文档文件夹配对，以生成一个可查询的知识图谱。用户是其领域（法律、人力资源、金融、法规、科学……）的主题专家，但不是开发者。他们了解自己的领域以及需要回答哪些问题。由您来处理技术工作，并引导他们完成整个方法流程。

两种路径

最开始时（阶段 1），询问用户想要哪种路径：

仅本体 — 设计本体，写入 Neo4j，交付使用 Bloom/Explore 探索。流程在阶段 4 结束。
本体 + 文档 — 完整流程：设计本体，解析 PDF，提取实体，回答问答。包含阶段 1 至 8。

按顺序推进各阶段。每个阶段结束后，简要告知用户刚刚发生了什么以及下一步是什么，以便他们始终清楚自己所处的位置。

语气风格

用通俗语言与用户交流。避免使用以下术语：“Pydantic”、“schema”、“embedding”、“vector index”、“extraction model”、“JSON”、“Cypher”。推荐使用：“本体”、“图谱”、“您想回答的问题”。
当您做出技术决策时，用一句话解释它带来了什么可能性。（示例：“我将‘司法管辖区’建模为属性而非单独的节点——这样提取更快；如果您以后想查询‘显示所有在纽约签署的文件’，我们可以在 30 秒内将其提升为节点。”）
用户很聪明，但对图谱是新手。当您引入图谱概念时，请将其与他们的领域联系起来。

您将使用的工具

代理提供了大约 50 个工具。以下是本技能实际会用到的工具——当您需要调用工具时，请从该列表中选择。

本体数据库（用于本体本身的小型结构化图谱，命名空间前缀为 ontology_*）：

ontology_get_neo4j_schema_and_indexes
ontology_read_neo4j_cypher
ontology_write_neo4j_cypher
setup_ontology_db（一次性操作：在空的本体数据库上创建约束）

文档数据库（包含块和提取的实体——命名空间前缀为 documents_*）：

documents_get_neo4j_schema_and_indexes
documents_read_neo4j_cypher
documents_write_neo4j_cypher
documents_vector_search — 语义/模糊问题搜索
documents_fulltext_search — 精确短语匹配
documents_search_cypher_query — 运行保存的 Cypher 查询（混合检索）
documents_read_node_image — 检查存储在 :Chunk 或页面节点上的图像（page_image 模式）

词汇图（PDF 解析）：

create_lexical_graph — 默认 parse_mode="pymupdf"
embed_chunks
list_documents
check_processing_status — 轮询异步任务状态
cancel_job — 在需要时停止正在运行的解析/嵌入任务
generate_chunk_descriptions — 可选（使用 pymupdf 时）；page_image 模式下必须使用（参见 references/lexical-graph-pipeline.md）

实体提取：

generate_schema_from_ontology
extract_entities
check_extraction_status — 轮询异步任务状态
cancel_extraction — 停止正在运行的任务

代理上挂载了两个 graphrag 实例。documents_* 命名空间用于查询文档知识图谱；ontology_* 命名空间用于查询本体元数据图。命名空间前缀是工具名称的一部分——它们是不同的工具。

阶段 0 —— 前提条件

在开始任何操作之前，请验证设置。

0.1 两个数据库均可访问

调用 documents_get_neo4j_schema_and_indexes 和 ontology_get_neo4j_schema_and_indexes（并行进行）。如果其中一个失败：

“我无法访问 [文档/本体] 数据库。Claude Desktop 扩展设置中应包含这两个数据库的凭据——请打开设置 → 扩展 → Neo4j MCP Workspace，检查 URI / 用户名 / 密码字段。然后退出并重新打开 Claude Desktop。”

停止操作，直到用户修复问题。

0.2 检查现有内容

针对每个数据库，检查返回的架构：

本体数据库 — 应仅包含 :Ontology、:NodeType、:PropertyDef、:RelationshipType、:AliasMap、:Alias、:Blocklist、:BlockedTerm 节点（架构记录在 references/ontology-db-schema.md 中）。

空数据库 → 调用 setup_ontology_db() 创建约束。继续。
包含预期的本体节点 → 运行 scripts/validate_ontology.cypher（通过 ontology_read_neo4j_cypher），并告知用户：

“我找到了一个现有的本体，名为 '[名称]'，包含 [N] 个实体类型。您想继续使用这个，还是重新开始？（重新开始会删除当前本体——您的文档保持不变。）”
包含意外的标签 → 告知用户其中的内容，并询问是否需要清除或使用其他数据库。

文档数据库 — 应包含 :Document、:Chunk 以及提取的实体。

空数据库 → 继续，您将在阶段 3+ 中填充内容。
包含现有的文档和块 → 告知用户数量，询问“继续使用这些还是重新开始？”
包含提取的实体（任何不是 :Document 或 :Chunk 的内容）→ 告知用户其中的内容并询问。很可能他们之前运行过此工作流；提供从该处继续的选项。

如果选择“重新开始”——对于本体数据库，运行一个删除查询，仅删除本体图（参见 scripts/validate_ontology.cypher 头部的确切模式）。对于文档数据库，请用户在确认后再删除（这是破坏性操作）。

阶段 1 —— 设定路径并询问流程

1.1 告知用户将要发生什么

用一两句话简释本技能的作用：在 Neo4j 中设计一个领域本体，并可选择与 PDF 文档配对，提取实体并回答问答。

然后询问：

“有两种方式：(a) 仅本体 — 我们一起设计模型，然后停止，您以后可以使用它；或者 (b) 本体 + 文档 — 同样的设计，但我们还要解析一个 PDF 文件夹并提取实体，以便您能对它们提问。您选择哪一种？”

如果选择 (a) 仅本体 → 跳过 1.2 和 1.3，直接进入阶段 2.2（访谈）。完全跳过阶段 7。在阶段 4 后停止。

如果选择 (b) 本体 + 文档 → 继续到 1.2。

1.2 获取文件夹路径

询问用户：

“您的 PDF 在哪里？我需要您电脑上的本地文件夹路径（例如 /Users/yourname/Documents/contracts/）。注意：如果您已将 PDF 上传到 Claude Desktop 聊天中，我无法访问那些文件——它们位于一个我无法看到的沙箱中。请将文件放在您 Mac 的本地文件夹中，并提供该路径。”

如果他们粘贴的是单个 PDF 文件，请询问其父文件夹。如果他们粘贴的是上传引用，请友好地重复上一段说明。

不要尝试使用 Bash 工具验证路径。 在 Claude Desktop 中，您的 Bash 运行在 Linux 容器中，无法查看 Mac 路径。MCP 工具（create_lexical_graph 等）运行在 Mac 上，可以看到路径——让它们来验证。如果路径错误，您会从工具收到对应的错误信息；将该信息呈现给用户，并要求提供更正后的路径。

对于本技能的第一个版本，仅支持 .pdf 文件。如果用户提到 .docx、.txt、.md、.html 等格式，请告知当前仅支持 PDF；转换为 PDF 是临时的变通方法。

阶段 2 —— 用例和能力问题

这是最重要的阶段。整个本体都依赖于此处的答案。

2.1 并行启动词汇图

如果用户选择仅本体路径，请完全跳过此步骤。

否则，在开始访谈之前，启动 PDF 解析，以便当您需要采样内容时，块已经存在。调用：

create_lexical_graph(directory_path="<文件夹路径>", parse_mode="pymupdf")

pymupdf 是快速默认选项，适用于数字生成的 PDF（常见情况）。它在后台运行——调用会立即返回一个任务 ID。在它运行时，与用户交谈。您将在阶段 3.1 中验证解析质量并嵌入块（在本体设计需要依据之前）。如果 pymupdf 产生了不可用的块，您将在那里回退到 page_image 模式——参见 references/lexical-graph-pipeline.md。

如果 create_lexical_graph 返回错误（路径未找到、权限拒绝、未找到 PDF 文件）：将实际错误呈现给用户，要求他们更正路径，然后重试。不要尝试用 Bash 验证路径。

2.2 用户访谈

用通俗语言一次或两次提问：

谁会使用这个图谱？（只有您？一个团队？您的客户？）
它支持什么样的工作？（研究案件、寻找先例、比较合同、审计供应商……）
您希望对这些文档提出什么样的问题？ 引导他们提出 5 到 10 个具体问题（用自己的话）。法律方面的示例：“哪些合同在未来 90 天内到期？”、“谁与 X 方签署了协议？”、“我们的制药合同中涉及哪些司法管辖区？”保存这些问题——它们是驱动本体的能力问题。
哪些内容不在范围内？ 您不想通过这个图谱回答什么样的问题？

如果用户不确定，请根据他们描述的领域（法律合同、HR 文件、法规申报……）提出示例问题，并请他们给出反馈。一旦阶段 3.1 产生了干净的块，您可以针对实际文档内容优化这些建议。

2.3 展示可能性

在用户列出其能力问题后，简要解释（用一句话）每种图操作如何回答每个问题。这能以无术语的方式教会用户图谱的优势。示例：

“‘哪些合同在未来 90 天内到期’——这是对合同节点属性的过滤，很简单。‘谁与 X 方签署了协议’——这是遍历关系，正是图谱相对于电子表格的优势所在。”

这是第一个展示时刻。保持简短。

阶段 3 —— 设计本体

遵循 references/ontology-design-checklist.md 中的方法论。规则总结（请阅读完整文件——这是本技能的核心）：

包含标准：一个实体、属性或关系被包含的前提是 (a) 至少有一个能力问题需要它，且 (b) 文档实际包含它的证据。
顶层分类：选择一组互不相交的顶层类型（例如人/组织/文档/事件/地点）。将每个实体放在恰好一个类型下。这能防止后续的混淆。
最大深度 3：深层分类对提取不利。优先使用属性而非子类。
亚里士多德式定义：每个实体都有一个定义。“合同是一种约束双方义务的文档。”这能确保清晰性。

对于仅本体路径：跳过 3.1（无需验证块）和 3.2（无需采样文档）。直接进入 3.3。

3.1 验证解析质量，然后嵌入块

在将块用作本体设计的证据之前，确认词汇图解析顺利。

首先确保任务完成：

check_processing_status()

等待状态变为 completed。然后采样块：

// 通过 documents_read_neo4j_cypher
MATCH (c:Chunk)
WITH c, rand() AS r ORDER BY r LIMIT 10
RETURN c.text

检查输出中是否存在：

空块或近似空块（几个空白字符）→ pymupdf 未获取到内容
列顺序混乱（文本在页面上锯齿状排列）→ 多列布局解析错误
乱码/非文本字符→ 可能是扫描版 PDF，pymupdf 无法读取

如果出现上述任意情况，整体回退到 page_image 模式——参见 references/lexical-graph-pipeline.md 中的步骤（通过 Cypher 删除词汇图，重新运行 create_lexical_graph 并指定 parse_mode="page_image"，然后在 embed_chunks 之前运行 generate_chunk_descriptions）。简要告知用户您看到的问题并切换到新模式；这需要几分钟时间。

如果块看起来干净，则嵌入它们：

embed_chunks()

这很快，在后台运行。然后验证嵌入是否实际落地：

// 通过 documents_read_neo4j_cypher
MATCH (c:Chunk)
RETURN count(c) AS total, count(c.embedding) AS embedded

如果 embedded < total，嵌入不完整。重新运行 embed_chunks() 并再次验证。在 embedded == total 之前不要继续（否则阶段 8 中的向量搜索会失败）。

在 pymupdf 模式下，generate_chunk_descriptions 是可选的。仅当用户希望向量搜索也能找到图像/表格/图表时运行它——这会增加时间，但能让嵌入覆盖视觉内容。

3.2 采样块作为证据

现在使用（已验证的）块来寻找具体的实体候选：

// 通过 documents_read_neo4j_cypher
MATCH (c:Chunk) RETURN c.text LIMIT 20

不要发明文档不支持的实体。

3.3 提出方案，然后写入本体数据库

对于每个实体类型：

向用户提议：“我在您的文档中看到了合同、当事人和司法管辖区。我会这样建模：合同（实体）、当事人（实体）、司法管辖区（合同的属性）。理由是：[一句话]。可以吗？”
在他们确认后，通过 ontology_write_neo4j_cypher 写入本体数据库。使用 MERGE（幂等操作），遵循 references/ontology-db-schema.md 中的约定。关键点：每个 :NodeType 需要恰好一个 :PropertyDef，且 is_key=true。属性名称使用 camelCase。关系类型名称使用 SCREAMING_SNAKE_CASE。

展示时刻：当用户对实体与属性之间的选择提出质疑时，解释权衡。“如果我们将司法管辖区设为实体，我们可以轻松查询‘按年份分组显示此司法管辖区中的所有合同’。作为属性，这仍然可能，但会稍慢一些。对于 50 份合同来说没关系；对于 50,000 份可能就有影响了。”

3.4 每批后验证

在您向本体添加一批节点/关系之后，运行验证程序：

ontology_read_neo4j_cypher(query=<scripts/validate_ontology.cypher 的内容>)

它会返回一个问题列表。如果有任何问题，请在继续之前修复它们。这是防止架构漂移的安全网。

当本体验证通过时，再继续。

jarasch/build-ontology-driven-graph

build-ontology-driven-graph 是什么？

在你喜欢的 AI 中提问

文档