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

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 "人卫社的网址"

六、常见问题排查

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

七、总结

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