最近一个朋友跟我吐槽公司想把内部项目文档、产品说明、甚至聊天记录做成一个能自动问答的智能库但数据敏感绝对不能传到云端API去。我直接甩给他一套方案——GraphRAG Ollama 本地化部署。整套东西跑在公司一台普通工作站上8G显存的显卡就能转起来数据不出内网问答效果比普通向量检索强一大截。这篇文章我就把从零搭建的完整过程、踩过的坑、还有背后的原理掰开揉碎讲清楚适合有一定Python基础、想在企业内网或本地环境落地知识库问答的同学参考。先说清楚这个组合到底干了什么。Ollama负责把大模型跑在本地并提供一套OpenAI兼容的APIGraphRAG负责把文档里的实体和关系抽出来建知识图谱再用图谱结构增强问答推理。两者一组合等于你本地就有一台既能做全局理解、又能做多跳推理的问答引擎而且整个链路不依赖公网。1. 先想清楚为什么是GraphRAG而不是普通向量检索1.1 普通RAG答不了跨文档推理类问题传统RAGRetrieval-Augmented Generation检索增强生成流程大家应该都熟文档切块、向量化、存向量库用户提问时把问题也向量化然后做相似度检索把最相关的几块文本拼进提示词交给大模型回答。这套方案在答案就藏在某一段文字里的场景下很好用比如产品A的保修期是多久。但遇到需要跨多个段落、甚至跨多份文档推理的问题就抓瞎了。举个例子你问研发中心负责人王总和供应商腾飞科技的法人是同一个人吗答案可能分散在员工档案、供应商登记表、董事会决议三份材料里。普通RAG检索时每一块文本和问题的向量相似度都不高排在前面的可能是完全不相关的段落大模型自然答不出来。这个问题的根源在于向量相似度只能衡量字面相关没法表达逻辑关系。而现实中的知识库问答偏偏大量问题都是关系型的。1.2 GraphRAG用图谱把碎片信息串起来GraphRAG最早是微软在2024年开源的研究项目核心思路分两步走。第一步索引阶段把原始文档交给大模型让它抽取出实体人、组织、产品、地点等和关系甲是乙的CEO丙被丁收购然后把这些实体和关系组织成一张图。接下来对这张图做社区检测常见算法是Leiden把联系紧密的实体聚成一个个社区再让大模型为每个社区生成一份摘要报告。第二步查询阶段当用户提问时系统不再去匹配原文片段而是去匹配社区报告和实体关系。比如问公司去年最大的供应商是谁模型会先定位到相关社区读取社区里聚合好的信息再综合推理。这就解决了普通RAG答不了全局性问题、跨文档问题的痛点。我实际体验下来GraphRAG对两类问题提升特别明显全局性问题如整个项目里涉及哪些合规风险文档中提到的主要合作伙伴有哪些。这类问题在传统RAG里基本没法答因为答案没有聚焦在某一段文字。多跳推理问题如A产品的负责人所在部门和B项目有合作吗。需要先找到A负责人再跳转到部门再关联到B项目图谱上的路径检索天然适合这种需求。1.3 为什么偏偏选Ollama做推理引擎GraphRAG官方默认接入的是OpenAI等云端模型。但对于企业内部知识库来说把业务文档发给第三方API本身就是很多公司接受不了的事。Ollama的价值在于把模型权重、推理服务、API封装成一个本地命令就能搞定的工具相当于你机器上装了个本地版OpenAI。支持Llama、Qwen、DeepSeek、Mistral等主流开源模型尤其是Qwen2.5和DeepSeek系列的中文能力相当能打。对硬件要求不算离谱7B~8B的量化模型6G~8G显存就能流畅运行如果纯CPU推理内存32G以上也能凑合跑只是速度慢一些。提供OpenAI兼容接口GraphRAG、Dify、FastGPT这些上层工具可以直接对接不用改多少代码。所以我最后的选型就是Ollama跑Qwen2.5系列做抽取和推理加一个嵌入模型做向量化GraphRAG负责图谱构建和查询编排。整套链路完全本地化断网也能用。2. 环境准备先把Ollama这块地基打牢2.1 安装Ollama时就要规划好路径和模型Ollama的安装本身不复杂但有几个细节我建议提前处理否则后面有得折腾。Windows上直接去官网下载exe安装包。但注意默认安装会进C盘模型文件也会放在C盘用户目录下的.ollama/models几十个G的模型塞进C盘系统盘分分钟爆掉。我一般装完第一件事就是改环境变量# Windows用户右键此电脑 - 属性 - 高级系统设置 - 环境变量 # 新建两个用户环境变量 OLLAMA_MODELSD:\ollama\models OLLAMA_HOST0.0.0.0:11434OLLAMA_MODELS指定模型存放路径OLLAMA_HOST0.0.0.0:11434则是把服务暴露到局域网这样同一网段的同事也能访问你机器上的模型。如果是纯个人本机用OLLAMA_HOST保持默认的127.0.0.1:11434就行。Linux/macOS用户直接用官方脚本curl -fsSL https://ollama.com/install.sh | sh装完之后验证一下ollama --version ollama serve看到服务监听在11434端口就算成功。注意在Windows上安装程序会自动注册成后台服务一般不需要手动执行ollama serve。2.2 模型拉取与离线导入下载太慢的真实解法Ollama的使用逻辑很简单先拉模型再对话# 拉取模型 ollama pull qwen2.5:7b ollama pull deepseek-r1:8b # 列出本地模型 ollama list # 测试对话 ollama run qwen2.5:7b 你好简要介绍一下你自己但很多同学卡在了第一步——拉模型极慢甚至直接报错max retries exceeded。这个报错我遇到过太多次了根因是Ollama拉模型时要访问海外存储节点网络链路不稳定时就会反复重试然后失败。我的经验是别死磕ollama pull改用曲线救国的方案去国内能正常访问的模型社区比如魔搭ModelScope下载GGUF格式模型文件然后通过Modelfile导入Ollama。整个过程全内网可完成速度能跑满带宽。具体步骤# 1. 在ModelScope上搜索对应模型的GGUF文件并下载比如 qwen2.5-7b-instruct-gguf # 2. 编写Modelfile FROM /data/models/qwen2.5-7b-instruct-q4_k_m.gguf # 3. 用ollama create导入 ollama create qwen2.5:7b -f Modelfile # 4. 验证 ollama list提示GGUF文件有不同的量化等级常见q4_k_m、q5_k_m、q8_0。q4_k_m体积最小质量损失不大7B模型大约4.7G对8G显存很友好。追求效果就上q8_0但显存占用会明显增加。嵌入模型也很关键。GraphRAG做向量化时需要嵌入模型我推荐用nomic-embed-text直接在Ollama里拉ollama pull nomic-embed-text如果你对中文嵌入效果要求更高也可以试试bge-m3这个在Ollama里也能找到。2.3 验证Ollama API可用GraphRAG对接Ollama本质是走一个OpenAI兼容的HTTP接口。装完先验证一下接口通不通curl http://localhost:11434/v1/models能看到模型列表就说明环境基本OK了。如果想测对话接口curl http://localhost:11434/api/chat -d { model: qwen2.5:7b, messages: [{role: user, content: 你好}] }这里我强烈建议把Ollama服务版本固定下来别随便升级。我遇到过两次Ollama升级后GraphRAG调用时偶发连接被重置的问题回滚到稳定版本就好了。生产环境求稳不追新这是第一条经验。3. GraphRAG工作原理解读明白流程才能调好参3.1 索引阶段把文档读成一张知识图谱GraphRAG的完整流程可以拆成两个阶段。索引阶段是重头戏也是最耗时间、最耗Token或者说最耗本地模型推理次数的环节。第一步是文本切块。原始文档会被切成固定大小的chunk默认大概1200个词左右相邻chunk之间有重叠避免关系被切断裂开。第二步是实体和关系抽取。这一步会把每个chunk交给大模型让它识别里面的实体Entity和它们之间的关系Relationship。比如这段文档写的是张三于2023年加入腾飞科技担任研发总监模型会抽出实体张三人、腾飞科技组织、研发总监职位关系张三 - 任职于 - 腾飞科技张三 - 担任 - 研发总监第三步是构建图结构。所有chunk抽出来的实体和关系会被合并成一张大图同一个实体会被合并成一个节点。然后做社区检测把联系紧密的实体划到同一个社区里。这一步用的通常是Leiden算法它的好处是不用提前指定社区数量能自动发现层次化的社区结构。第四步是生成社区报告。GraphRAG会让大模型针对每个社区生成一份概括性描述这个社区涉及哪些实体、它们之间的关系是什么、有哪些关键信息。这就是后续全局检索时的索引卡片。最后还会为实体、社区报告等对象生成向量嵌入用于局部检索时的语义匹配。3.2 查询阶段全局搜索和局部搜索两条路径GraphRAG提供两种查询模式我实际用下来互补性很强。全局搜索Global Search适合回答整个知识库里……这类跨文档、全局性的问题。流程是找出与问题语义最相关的若干社区报告把所有报告拼接起来分批次让大模型提炼要点这一步称为map再把要点合并起来生成最终答案称为reduce。因为看到了全图的社区摘要所以能回答公司面临哪些主要风险文档里涉及了哪些关键人物这类问题。局部搜索Local Search适合回答某一实体相关的具体问题。流程是根据问题找到相关实体然后沿图谱扩展把相邻实体、相关关系、原始文本、社区报告全部取出来一起交给大模型做推理。因为信息是围绕实体聚合的所以回答张三负责哪些项目这种问题时信息完整度远高于普通的向量检索。理解了这两条路径后面的参数调优才有方向。比如全局搜索慢可以把社区报告层级调低一点减少输入量局部搜索答不准可以增加实体扩展的跳数。3.3 为什么图谱结构比向量更擅长多跳推理我再用一个更直观的比喻。向量库像一本字典你要查一个词按偏旁部首翻到那一页只能看到这个词的释义。图谱则像一张人际关系网每个实体是一个节点节点之间用关系线相连。当问题需要跳好几次才能找到答案时字典式检索无能为力但图谱可以沿着关系线一步步走每次跳转都有明确依据。GraphRAG的聪明之处在于它不是让大模型在推理时实时去遍历整张图——那太慢了——而是在索引阶段就把全局结构消化成了社区报告查询时只需要在浓缩过的信息上做推理。这就是它比普通RAG更适合做知识库问答的根本原因。4. 实战记录从初始化到跑通全流程4.1 安装GraphRAG并初始化项目环境准备好后开始装GraphRAG。用独立的Python虚拟环境是基本操作python -m venv .venv source .venv/bin/activate # Windows下是 .venv\Scripts\activate pip install graphrag然后初始化项目python -m graphrag init --root ./demo执行完会在demo目录下生成两类文件settings.yaml核心配置文件包括LLM服务地址、模型名、嵌入模型、各类参数。.env存放环境变量如API Key。GraphRAG比较麻烦的一点是不同版本的配置方式有差异。老版本靠环境变量新版本统一收敛到settings.yaml。我建议以你安装的版本官方文档为准这里列一份我用过的、能跑通的配置供参考llm: api_key: ollama type: openai_chat model: qwen2.5:7b api_base: http://localhost:11434/v1 max_tokens: 4000 request_timeout: 300.0 model_supports_json: true embedding: api_key: ollama type: openai_embedding model: nomic-embed-text api_base: http://localhost:11434/v1 chunks: size: 1200 overlap: 200 parallelization: enabled: true num_threads: 8提示api_key这里随便填一个占位符就行Ollama不校验Key。但GraphRAG代码里如果没读到Key会直接报错所以不能留空。重要model_supports_json要看情况开。GraphRAG抽取实体时要求模型输出严格JSON格式Qwen2.5系列本身支持JSON模式可以开但有些模型对JSON输出支持不好开了反而更容易出错可以先关掉跑通再说。4.2 准备语料执行索引构建在demo目录下创建input文件夹把文档放进去。纯文本txt就行PDF需要额外装解析库我建议起步阶段统一转成txt或md省去一堆麻烦。语料准备好后执行索引构建python -m graphrag index --root ./demo这一步非常考验耐心。以一份50页左右的文档为例我用7B模型在单张8G显存的卡上跑大概需要30到50分钟。索引过程会大量调用本地模型做实体抽取、社区报告生成每一步都要等推理完成所以慢是正常的。跑完以后output目录下会生成一批parquet文件包括entities实体表relationships关系表communities社区划分结果community_reports社区摘要报告看到这些文件说明知识图谱已经建好了。我习惯先看一眼entities.parquet的规模确认抽取出的实体数量在合理范围——如果一份50页的文档只抽出几十个实体说明抽取prompt或模型有问题要排查。4.3 用命令行跑通问答索引构建完成先直接用命令行验证效果# 全局搜索 python -m graphrag query --root ./demo --method global --query 这套文档中提到了哪些核心技术方向 # 局部搜索 python -m graphrag query --root ./demo --method local --query 研发总监张三参与了哪些项目全局搜索通常需要20到40秒局部搜索会快一些。如果两条命令都能得到结构合理的回答恭喜整套链路通了。命令行跑通之后我习惯再封装一个Python脚本方便集成到内网系统里from graphrag.query import parse_query_mode def ask_question(question: str, method: str local) - str: # 这里可以调用graphrag提供的查询接口 # 也可以直接解析CLI输出或者封装Indexer和Search器 ...说实话GraphRAG官方查询接口在不同版本里变化比较大直接写Python调用容易踩版本坑。我更推荐的做法是先用命令行走通流程然后如果你要接Web应用把命令行封装成后端服务接口或者去对接Dify/FastGPT这类现成的编排平台——它们已经做了图形化界面Ollama的模型可以直接接入Graphrag的能力也能通过插件方式挂进去。这样开发成本最低交付速度最快。4.4 用脚本把问答能力API化如果一定要自己写服务我给一个最小可用的封装思路用subprocess调CLI或者用FastAPI包一层HTTP接口内部调用GraphRAG的查询入口。这里要注意GraphRAG查询时会做大量并行调用如果你同时跑多个查询请求Ollama那边很容易出现并发排队显存不够时甚至会OOM。所以我的建议是Ollama侧可以设置环境变量OLLAMA_NUM_PARALLEL控制并发数一般设1或2服务层加上简单的请求队列避免把本地模型压垮。本地部署不比云端API并发是把双刃剑宁可排队慢一点也不要直接崩掉。5. 常见问题排查与避坑指南5.1 Ollama端我从报错狂魔到稳定运行的几板斧报错一max retries exceeded: get https://huggingface.co这是Ollama拉模型时的经典报错本质是网络链路问题。解决办法前面写过别死磕ollama pull去国内模型社区下载GGUF文件再导入。这条路最稳速度也快。报错二model not found 或 run file does not exist一般有两个原因一是模型名没写对用ollama list查一下准确的名称和标签二是模型没拉成功但残留了记录可以删掉重新导入。执行ollama rm 模型名清理后重试。报错三Ollama服务只能在本地访问检查环境变量OLLAMA_HOST是否设置为0.0.0.0:11434。修改环境变量后Windows需要重启Ollama服务Linux需要重启ollama进程sudo systemctl restart ollama报错四显存不足OOM这是本地跑大模型的常态。我的处理顺序是先换更小的量化版本比如q4_k_m换成q4_k_s再检查是否同时加载了太多模型用ollama ps查看当前加载的模型不用的用ollama stop 模型名卸载最后降低GraphRAG的并发线程数比如从8降到4。5.2 GraphRAG端索引慢、内存爆、格式错索引速度太慢慢的根源是本地7B模型逐块推理。提升手段有几种换更小的模型如qwen2.5:3b做抽取速度会快几倍但抽取质量可能下降。如果显存够可以试试把并发数调高让Ollama同时处理多个请求单次推理吞吐量会提升。先拿小数据量跑通再逐步扩大语料避免一上来就让模型啃几百页文档调参都调不动。LLM返回格式不正确导致索引中断GraphRAG对实体抽取的JSON格式要求很严格模型一旦输出不规范的JSON整个流程就会报错。除了前面提到的model_supports_json参数我还会在配置里打开重试并适当增加request_timeout。如果频繁出错我建议换一个对JSON输出更友好的模型——Qwen2.5和Llama 3.1在这方面的表现都比较稳。内存和磁盘占用过高索引过程中会生成大量中间数据parquet、缓存、向量库都占空间。起步阶段建议控制语料量不要在第一次就把全部历史文档倒进去。我踩过的教训是一次导入800MB文档结果索引跑到一半磁盘满了最后还得清数据重来。小步快跑先把流程打通再逐步扩量。5.3 回答质量调优的几个有效方向如果回答质量不理想我的排查顺序是先看实体抽取质量。打开entities.parquet看看实体是不是明显缺漏。如果实体抽取就漏了后面所有环节都会跟着错。处理方法优化输入语料的格式去掉多余噪音页眉页脚、无关表格或者换更大的模型做抽取。再看问题类型和查询模式是否匹配。全局性问题用global局部实体问题用local混用容易答非所问。调chunk大小。实体抽取是基于chunk的chunk太小跨段关系容易被截断chunk太大单个chunk里的噪音信息过多。我常用的范围是800到2000配合10%~20%的overlap。升级模型。7B模型做抽取和社区报告生成质量上限就摆在那里。如果预算和硬件允许换14B甚至更大尺寸的模型效果提升是立竿见影的。6. 最后分享几个我踩出来的小经验这套 GraphRAG Ollama 的本地化方案我在搭完之后最大的感受是真正的难点不是安装部署而是语料治理和参数调优。一份干净、结构化、噪声少的语料能让你在后面的每个环节都省心反过来语料乱七八糟后面模型再好也救不回来。第二个体会是不要一开始就追求把所有数据都灌进去。先拿几十页高质量文档跑通全流程再逐步增加数据量。每增加一批数据都重新审视实体抽取质量和回答效果。知识图谱不像向量库它的构建成本高、结构性更强前期多花时间做小样验证远比后期返工划算。最后再分享一个小技巧GraphRAG索引构建过程中如果你发现某个chunk频繁触发重试不妨把那块原始文本拿出来看一眼往往是有特殊格式、特殊符号或者表格结构被切碎了。把这些文本清洗一下再放回去整个流程会顺畅很多。如果你公司内部也想做一套数据不出内网的知识库问答系统这套组合目前是我认为性价比很高的方案。硬件门槛不高软件全免费唯一需要投入的就是时间和调优的耐心。