GraphRAG 结合 Ollama 实现本地化部署完整教程

随着检索增强生成（RAG）技术的持续火热，微软开源的 GraphRAG 方案因其构建知识图谱的能力而备受关注。为了在保护数据隐私的同时利用大模型能力，将 GraphRAG 与本地运行的 Ollama 模型结合是一个理想的实践路径。本文档详细记录了从环境准备、安装配置到源码适配及测试验证的全过程，旨在帮助开发者在无外部 API 依赖的情况下，完美部署 GraphRAG 系统。

一、环境准备

1. Python 环境

GraphRAG 对 Python 版本有明确要求，建议使用 Python 3.10 至 3.12 版本。请确保已安装对应版本的 Python 并配置好环境变量。

python --version

2. Ollama 服务

需要在本地部署 Ollama 服务，用于提供 LLM 和 Embedding 模型的推理能力。

安装 Ollama：访问官网下载并安装对应操作系统的版本。
启动服务：默认情况下，Ollama 会在 http://localhost:11434 启动。

3. 模型拉取

根据 GraphRAG 的配置需求，需要预先拉取合适的语言模型和嵌入模型。本教程推荐使用以下模型组合：

LLM 模型：gemma2:9b（或其他支持 JSON 输出的本地模型）
Embedding 模型：quentinz/bge-large-zh-v1.5:latest（针对中文优化的嵌入模型）

拉取命令如下：

ollama pull gemma2:9b
ollama pull quentinz/bge-large-zh-v1.5:latest

二、安装与初始化

1. 安装 GraphRAG

通过 pip 安装官方库：

pip install graphrag

2. 创建项目目录

建立一个文件夹存放知识数据。目前 GraphRAG 仅支持 .txt 和 .csv 格式的文件。

mkdir -p ./ragtest/input

将待处理的文本数据放入 ./ragtest/input 目录下。建议文件编码为 UTF-8。

3. 初始化工作区

运行初始化命令，这将生成配置文件结构。

python -m graphrag.index --init --root ./ragtest1

执行完成后，目录中将包含 .env 和 settings.yaml 两个关键配置文件。

.env：包含运行管道所需的环境变量，如 API 密钥等。
settings.yaml：包含管道的核心设置，需在此处修改以适配 Ollama。

三、配置文件详解 (settings.yaml)

这是部署的核心部分。我们需要修改 settings.yaml 以指向本地 Ollama 接口，而非 OpenAI 云端。

1. 基础设置

input:
  type: file
  file_type: text
  base_dir: "input"
  file_encoding: utf-8
  file_pattern: ".*\.txt$"

2. LLM 配置

指定本地使用的语言模型。注意 api_base 必须指向 Ollama 的 v1 兼容接口。

llm:
  api_key: ollama
  type: openai_chat
  model: gemma2:9b
  model_supports_json: true
  max_tokens: 2048
  api_base: http://localhost:11434/v1
  concurrent_requests: 1

3. Embeddings 配置

指定本地使用的嵌入模型。注意接口路径是 /api 而非 /v1。

embeddings:
  llm:
    api_key: ollama
    type: openai_embedding
    model: quentinz/bge-large-zh-v1.5:latest
    api_base: http://localhost:11434/api
    concurrent_requests: 1

4. 分块策略

合理设置分块大小和重叠率有助于提升检索效果。

chunks:
  size: 300
  overlap: 100
  group_by_columns: [id]

5. 其他关键配置

storage: 输出目录，默认为 output/${timestamp}/artifacts。
entity_extraction: 实体提取提示词路径及类型。
cluster_graph: 控制图谱聚类大小。

四、源码适配与补丁

由于 GraphRAG 原生设计主要面向 OpenAI 接口，直接连接 Ollama 时可能会遇到类型不匹配或方法调用的问题。因此需要对源码进行两处关键修改。

1. 修改 Embeddings 调用逻辑

找到 Python 站点包中的 graphrag/llm/openai/openai/_embeddings/_llm.py 文件（路径可能因环境而异，通常在 site-packages 下）。替换原有代码逻辑，使其调用 ollama 库。

修改前：使用 OpenAI 客户端。 修改后：

import ollama

class OpenAIEmbeddingsLLM(BaseLLM[EmbeddingInput, EmbeddingOutput]):
    # ... 初始化代码保持不变 ...

    async def _execute_llm(
        self, input: EmbeddingInput, **kwargs: Unpack[LLMInput]
    ) -> EmbeddingOutput | None:
        args = {
            "model": self.configuration.model,
            **(kwargs.get("model_parameters") or {}),
        }
        embedding_list = []
        for inp in input:
            # 直接调用 ollama 库进行嵌入
            embedding = ollama.embeddings(model="quentinz/bge-large-zh-v1.5:latest", prompt=inp)
            embedding_list.append(embedding["embedding"])
        return embedding_list

注意：请将代码中的 model 参数值修改为你实际在 settings.yaml 中配置的 Embedding 模型名称。

2. 修改 Query 模块 Embedding 实现

找到 graphrag/query/llm/oai/embedding.py 文件。该文件负责查询时的文本向量化，需替换为支持 Ollama 的实现。

修改要点：

引入 langchain_community.embeddings.OllamaEmbeddings。
重写 _embed_with_retry 和 _aembed_with_retry 方法，内部调用 Ollama 接口。

参考代码片段：

from langchain_community.embeddings import OllamaEmbeddings

class OpenAIEmbedding(BaseTextEmbedding, OpenAILLMImpl):
    # ... 初始化代码 ...

    def _embed_with_retry(self, text: str | tuple, **kwargs: Any) -> tuple[list[float], int]:
        try:
            retryer = Retrying(
                stop=stop_after_attempt(self.max_retries),
                wait=wait_exponential_jitter(max=10),
                reraise=True,
                retry=retry_if_exception_type(self.retry_error_types),
            )
            for attempt in retryer:
                with attempt:
                    # 使用 LangChain 封装的 Ollama 嵌入类
                    embedding = (
                        OllamaEmbeddings(model=self.model).embed_query(text)
                        or []
                    )
                    return (embedding, len(text))
        except RetryError as e:
            self._reporter.error(
                message="Error at embed_with_retry()",
                details={self.__class__.__name__: str(e)},
            )
            return ([], 0)
        else:
            return ([], 0)

同样，请确保 self.model 与配置文件中一致。

五、执行索引与查询

1. 构建索引

完成配置和代码修改后，运行索引构建命令。此过程会读取输入文件，提取实体关系，构建知识图谱，耗时取决于数据量。

python -m graphrag.index --root ./ragtest1

观察控制台日志，确认 Entity Extraction 和 Community Report 阶段是否成功。

2. 本地搜索 (Local Search)

本地搜索侧重于上下文相关的精确检索。

python -m graphrag.query --root ./ragtest1 --method local "人卫社的网址"

系统将基于图谱中的局部关系返回答案。

3. 全局搜索 (Global Search)

全局搜索利用社区摘要和整体图谱结构进行回答，适合宏观问题。

python -m graphrag.query --root ./ragtest1 --method global "人卫社的网址"

六、常见问题排查

API Key 报错：在 settings.yaml 中，即使使用本地 Ollama，某些字段仍需保留占位符。确保 api_key: ollama 存在，不要留空。
端口连接失败：检查 Ollama 服务是否正常运行，且防火墙未拦截 11434 端口。
模型名称不匹配：务必保证 settings.yaml 中的模型名与 ollama list 列出的完全一致，包括后缀（如 :latest）。
JSON 解析错误：如果 LLM 返回非 JSON 格式导致崩溃，尝试更换支持 JSON 模式更好的模型，或在 settings.yaml 中调整 model_supports_json 配置。
内存不足：本地部署大模型消耗显存较大。若遇到 OOM，可减小 concurrent_requests 数量，或使用参数量更小的模型。

七、总结

通过将 GraphRAG 与 Ollama 结合，我们实现了完全本地化的知识库构建与问答系统。这不仅避免了数据外泄风险，还降低了对昂贵云 API 的依赖。虽然过程中涉及源码修改和配置细节，但掌握这些步骤后，即可灵活扩展至更多私有化场景。后续可根据业务需求调整分块策略、实体提取提示词或图谱聚类参数，以优化检索精度。

GraphRAG 结合 Ollama 实现本地化部署完整教程