GraphRAG+Ollama 本地部署，保姆教程，踩坑无数，闭坑大法

GraphRAG最近可谓风头正劲，微软开源之后迅速成为技术圈的热点。作为一个在RAG领域实践的开发者，我也第一时间尝试部署，但直接使用OpenAI接口对网络环境有要求。于是，一个更实际的想法冒了出来：能否用本地的开源模型来替换它？

动手实践的过程远比预想的曲折，途中踩了不少“坑”。好在经过一番调试，最终成功地将GraphRAG完美部署到了纯离线环境中。下面就把整个经过和关键步骤梳理出来，既是一次分享，也为日后自己复现留个记录。

官方安装流程

GraphRAG的安装本身并不复杂，通过pip即可完成。但需要注意官方要求的Python版本范围是3.10到3.12。

pip install graphrag

安装完成后，需要建立一个工作目录来存放你的知识数据。当前GraphRAG支持txt和csv格式的文件。

mkdir -p ./ragtest/input

接下来，将准备好的数据文件放入/ragtest/input目录下。为了演示，这里使用了一份截取后的中文文本数据。

初始化工作区是第一步，运行以下命令：

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

执行完毕后，目录结构会发生变化，主要生成了两个关键文件：.env和settings.yaml。

• .env文件包含了运行GraphRAG管道所需的环境变量，默认定义了GRAPHRAG_API_KEY，如果使用云端服务需要在此处配置API密钥。
• settings.yaml文件则是整个管道的配置核心，我们可以通过修改它来适配本地模型。

关键配置：连接本地Ollama

接下来就是改造settings.yaml文件的核心部分。前提条件是，你已经在本地通过Ollama安装好了以下两个模型：

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

那么，你可以将以下配置内容复制到settings.yaml中。关键点在于将LLM和Embedding的接口指向本地的Ollama服务。

encoding_model: cl100k_base
skip_workflows: []
llm:
  api_key: ollama
  type: openai_chat
  model: gemma2:9b # 替换为你Ollama中的本地LLM模型
  model_supports_json: true
  max_tokens: 2048
  api_base: http://localhost:11434/v1 # 注意LLM接口路径是/v1
  concurrent_requests: 1

parallelization:
  stagger: 0.3

async_mode: threaded

embeddings:
  async_mode: threaded
  llm:
    api_key: ollama
    type: openai_embedding
    model: quentinz/bge-large-zh-v1.5:latest # 替换为你Ollama中的本地Embedding模型
    api_base: http://localhost:11434/api # 注意Embedding接口路径是/api
    concurrent_requests: 1

# 以下是数据处理、缓存、存储等配置，可根据需要调整
chunks:
  size: 300
  overlap: 100
  group_by_columns: [id]

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

cache:
  type: file
  base_dir: "cache"

storage:
  type: file
  base_dir: "output/${timestamp}/artifacts"

# ... 其他任务（实体提取、社区报告等）的配置保持默认或根据模型能力微调

配置完成后，就可以启动索引构建管道了：

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

这个过程会开始构建索引和知识图谱，耗时取决于数据量的大小。

核心修改：绕过源码中的“坑”

仅完成配置还不够，进行本地查询时可能会遇到错误，因为GraphRAG原生代码在某些环节仍会调用OpenAI的SDK。因此，需要对两处源码进行修改。

1. 修改Embedding生成逻辑

找到文件：graphrag/llm/openai/openai_embeddings_llm.py（具体路径在你的Python site-packages目录下）。

用以下内容替换原有代码，其核心是将嵌入生成调用重定向到Ollama的本地接口：

# ... 文件头部版权和导入部分 ...
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的embeddings接口，model名称需与settings.yaml中一致
            embedding = ollama.embeddings(model="quentinz/bge-large-zh-v1.5:latest", prompt=inp)
            embedding_list.append(embedding["embedding"])
        return embedding_list

2. 修改查询时的Embedding模型包装器

找到文件：graphrag/query/llm/oai/embedding.py。

用以下内容替换。这个修改使得在查询阶段，系统会使用LangChain的OllamaEmbeddings来调用本地模型。

# ... 文件头部版权和导入部分 ...
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(...)
            for attempt in retryer:
                with attempt:
                    # 关键修改：使用OllamaEmbeddings生成向量
                    embedding = (
                        OllamaEmbeddings(
                            model=self.model,
                        ).embed_query(text)
                        or []
                    )
                    return (embedding, len(text))
        except RetryError as e:
            # ... 错误处理 ...
            return ([], 0)
        else:
            return ([], 0)

    async def _aembed_with_retry(
        self, text: str | tuple, **kwargs: Any
    ) -> tuple[list[float], int]:
        try:
            retryer = AsyncRetrying(...)
            async for attempt in retryer:
                with attempt:
                    embedding = (
                        await OllamaEmbeddings(
                            model=self.model,
                        ).embed_query(text) or []
                    )
                    return (embedding, len(text))
        except RetryError as e:
            # ... 错误处理 ...
            return ([], 0)
        else:
            return ([], 0)

完成这两处源码修改后，主要的“坑”就算跨过去了。

测试效果

1. 本地查询 (Local Search)

运行以下命令，测试针对具体事实的查询：

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

如果配置和修改都正确，系统会从构建的知识图谱中返回相关的实体和信息。对于较小的演示数据集，它能准确抓取并解析到文本中提及的网址等信息，证明图谱构建是成功的。

2. 全局查询 (Global Search)

运行以下命令，测试更高层次的概括性查询：

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

全局查询会尝试理解问题的意图，并可能从更综合的角度（例如实体描述、上下文关联）返回信息。成功返回结果意味着整个GraphRAG管道——从索引构建到查询检索——已经在本地模型上跑通了。

至此，一个完全基于本地开源模型的GraphRAG系统就部署完成了。大家可以参照这个流程尝试，主要的障碍应该都已扫清。