knowledge_graph 详细部署教程

knowledge_graph 是一个能够将任意文本语料转换为知识图谱的开源项目。它通过本地运行的 LLM 从文本中提取概念和关系，并最终生成一个可交互的网络图。本项目采用“无 GPT”方案，依赖本地运行的 Mistral 7B OpenOrca 模型和 Ollama，完全免费且无需 API 调用。

本教程将指导你完成从环境准备到最终生成知识图谱的全流程。

工作原理简介

在开始部署前，了解其核心流程有助于后续操作：

文本分割：将输入的文本语料切分成多个有重叠的文本块（chunk），并分配 ID。
关系提取：对每个文本块，使用本地 LLM（如 Mistral 7B）提取其中的关键概念（节点）及概念间的关系（边）。这是一种语义关系的直接提取。
上下文邻近度分析：将出现在同一文本块中的所有概念两两相连，认为它们存在上下文关联。这是一种基于共现的间接关系。
合并与加权：将所有相同概念对的关系进行合并，累加其权重（即共现次数），并汇总关系描述。
图计算与可视化：使用 NetworkX 进行图分析（如计算节点度、社区发现），最后用 Pyvis 生成一个可交互的 HTML 网页图谱。

准备工作

必备条件

Docker：这是最推荐的部署方式，项目已为你打包好所有依赖。
Git：用于克隆项目仓库。

硬件与系统

操作系统：macOS、Linux 或 Windows（通过 WSL2）。
内存：至少 8GB，推荐 16GB 以上，因为需要运行 7B 参数的 LLM。
存储空间：至少 10GB 可用空间，用于存放模型文件和 Docker 镜像。

使用 Docker 快速部署（推荐）

这是最快捷、依赖最少的方式，Docker 会处理所有环境配置。

第一步：克隆项目

打开终端，执行以下命令：

1 2	git clone https://github.com/rahulnyk/knowledge_graph.git cd knowledge_graph

第二步：构建 Docker 镜像

在项目根目录下，构建名为 knowledge-graph 的 Docker 镜像。这个过程会下载所有必要的依赖和基础模型，可能需要一些时间。

1	docker build -t knowledge-graph .

第三步：运行容器

启动容器，并将容器的 8888 端口映射到本地的 8888 端口。

1	docker run -p 8888:8888 knowledge-graph

当看到终端显示类似 [I ...] Serving notebooks from local directory: /app 的日志时，表示 Jupyter 服务已成功启动。

第四步：访问 Jupyter Notebook

打开你的浏览器，访问 http://localhost:8888。你将看到 Jupyter 的文件列表，核心工作文件是 extract_graph.ipynb。

使用本地 Ollama 部署（高级）

如果你希望更灵活地控制模型或进行二次开发，可以选择本地部署。这种方式不需要 Docker，但需要手动配置 Python 环境和 LLM 服务。

第一步：安装 Ollama

访问 Ollama 官网下载并安装对应你操作系统的版本。

第二步：拉取并运行模型

打开终端，执行以下命令。这会自动下载并启动 zephyr 模型（一个针对指令优化的 Mistral 7B 变体）。

1	ollama run zephyr

保持此终端窗口运行，或让 Ollama 在后台服务。

第三步：设置 Python 环境

项目使用 Poetry 管理依赖。你需要安装 Poetry，然后安装项目依赖。

# 安装 Poetry (如果尚未安装)
pip install poetry

# 在项目根目录安装依赖
poetry install

第四步：配置并运行 Notebook

在项目目录中，使用 poetry shell 激活虚拟环境。
启动 Jupyter Notebook：jupyter notebook。
打开 extract_graph.ipynb 文件。
在 Notebook 的单元格中，确保 Ollama 的配置指向你本地的服务。通常，默认配置无需修改即可工作。
按顺序运行 Notebook 中的所有单元格。

生成你的第一个知识图谱

无论使用哪种方式，核心操作都在 extract_graph.ipynb 文件中。

第一步：准备文本数据

默认输入：项目默认读取 data_input/sample_text.txt 文件作为输入语料。
使用 PDF：项目也提供了从 PDF 提取文本的功能。你可以将你的 PDF 文件放入 data_input/ 目录，并修改 Notebook 中对应的文件读取路径。
自定义文本：你也可以直接在 Notebook 中定义 Python 字符串变量作为输入。

第二步：执行核心提取流程

在 Notebook 中，顺序执行以下主要步骤的单元格：

文本分块：使用 RecursiveCharacterTextSplitter 将长文本切分为约 1500 字符的块（chunk）。
LLM 关系提取：对每个 chunk，调用本地的 Mistral 模型，通过精心设计的 graphPrompt 让模型输出 JSON 格式的概念对和关系描述。
计算共现关系：计算同一 chunk 内所有概念对的共现次数作为权重。
构建图：使用 NetworkX 将节点（概念）和边（关系）组合成一个图数据结构。
社区发现与可视化：运行 girvan_newman 社区发现算法，并使用 Pyvis 生成最终的交互式 HTML 图谱。

第三步：查看结果

HTML 文件：生成的可视化图谱会保存在 data_output/ 目录下，文件名通常为 knowledge_graph.html。用浏览器打开它，你可以拖拽、缩放、点击节点查看详情。
图数据：NetworkX 的图对象 G 中包含了所有节点、边、权重和社区信息，可供你进行进一步的分析。

进阶：自定义与参数调整

你可以修改以下关键参数来适应不同需求：

文本分块大小 (chunk size)：在 Notebook 的 RecursiveCharacterTextSplitter 部分调整。更小的块可能提取更细粒度的关系，但会丢失上下文；更大的块则相反。
LLM 模型：你可以通过修改 Ollama 调用，使用其他本地模型，如 mistral:7b-instruct 或 llama3。注意不同模型的指令遵循能力可能影响提取效果。
提示词 (Prompt)：helpers/prompts.py 文件中的 graphPrompt 定义了如何指导 LLM 提取关系。你可以根据你的领域需求调整描述，例如在提示词中要求输出更具体的关系类型。
权重处理：contextual_proximity 函数的逻辑可以调整，例如可以引入一个权重衰减因子，避免高频但无意义的共现关系权重过高。

常见问题与解决

Q: Docker 构建或运行失败？
- A: 检查网络是否通畅，能否顺利拉取基础镜像。确保 Docker 分配了足够的内存（建议 6GB 以上）。如果失败，可尝试使用本地 Ollama 方式。
Q: 运行 Notebook 时，LLM 没有输出或输出格式错误？
- A: 确保 Ollama 服务正常运行（ollama list 查看已安装模型）。检查 Notebook 中使用的模型名称是否与 ollama run 的模型一致。部分模型可能对 JSON 格式的输出遵循不佳，可尝试修改提示词或更换为 zephyr 模型。
Q: 生成的图谱关系很稀疏或杂乱？
- A: 可以调整文本分块大小和重叠长度，让 LLM 有更好的上下文来提取关系。另外，尝试调整共现边的最小权重阈值（min_weight），过滤掉出现次数过少的弱关系，让图谱更清晰。
Q: 处理长文本或大量文档时很慢？
- A: 这是本地 7B 模型的正常表现。可以考虑使用性能更好的硬件，或尝试使用更小的量化模型（如 zephyr:7b-q4_K_M）以提升速度。