1. GraphRAG 本地复现为什么总卡在依赖与 embedding 配置GraphRAG 是微软开源的一套基于知识图谱的检索增强生成方案它能把你的一堆本地文档抽成实体关系图再配合社区摘要做全局问答。适合谁适合想在自己机器上跑通「文档进、图谱出、问答准」这条链路的人尤其是做知识库、做行业问答、做研究复现的开发者。但真正动手时十个人里有八个会先卡在依赖安装和 embedding 配置上报错五花八门从uv sync装了个寂寞到litellm抛BadRequestError再到向量维度对不上。我自己复现时踩过的坑是明明在仓库根目录跑了uv sync终端也没报错结果一执行uv run poe index就提示找不到graphrag模块。后来才搞明白GraphRAG 仓库早就从「单包」改成了 monorepo 结构根目录的pyproject.toml只是工具链配置真正的 Python 包藏在packages/graphrag/下面。你如果只在根目录同步装的是 lint、test、docs 这些开发工具业务模块根本没进虚拟环境。这篇文章就按「环境初始化 → 依赖安装 → embedding 配置 → 索引验证 → 报错排查」这条完整路径走一遍。每一步都给可复制的命令和配置片段你照着敲就能复现。核心检索词先摆出来GraphRAG 复现、pyproject.toml 依赖、uv sync 安装、litellm embedding 配置。搞懂这几个后面基本就顺了。先说清楚整体链路。GraphRAG 的索引流程大致是读取settings.yaml→ 调用 completion model 抽实体和关系 → 调用 embedding model 把文本转向量 → 写入 LanceDB 向量库 → 生成社区报告。这里面 completion 和 embedding 是两条独立的模型配置任何一条配错索引都会中途挂掉。而依赖安装决定了这些模块能不能被 import 到。所以排查顺序建议是先确认包装对了再确认模型连得通最后确认向量维度一致。下面从最容易被忽略的 monorepo 结构讲起把pyproject.toml和uv sync的关系彻底理清。2. pyproject.toml 与 uv sync 的 monorepo 依赖安装排查GraphRAG 仓库根目录有一个pyproject.tomlpackages/graphrag/下面还有一个pyproject.toml。很多人看到根目录有就直接uv sync然后以为装好了。实际上根目录那份是给整个仓库做统一工具链用的里面可能包含[tool.uv]、[dependency-groups]或者通过 poe 间接引用子包。uv只要看到pyproject.toml就会尝试解析依赖所以uv sync能跑通但它不会把graphrag模块本身装进环境。你可以先用一条命令确认自己装的是哪个包uv pip list | grep -i graphrag如果输出为空说明业务包没装上。这时候要进入真正的 Python 包目录再装cd packages/graphrag uv pip install -e .-e是 editable 模式改源码能直接生效调试阶段强烈建议这么装。装完再验证一次uv run python -c import graphrag; print(graphrag.__file__)能打印出路径就说明import graphrag注册成功了。如果还是报ModuleNotFoundError检查packages/graphrag/下有没有__init__.py以及当前虚拟环境是不是uv管理的那个。如果你想让uv sync一次性把所有子包都装上可以用uv sync --all-packages uv sync --all-extras--all-packages会把 monorepo 里所有 workspace 成员都纳入同步--all-extras会把可选依赖也装上。两个一起用基本能覆盖 GraphRAG 的完整依赖。但要注意有些版本对 workspace 的支持有差异如果--all-packages报错就老老实实进子目录uv pip install -e .。下面给一份可复制的pyproject.toml依赖片段参考放在packages/graphrag/pyproject.toml里重点是dependencies和[project.optional-dependencies][project] name graphrag version 0.3.0 requires-python 3.10,3.13 dependencies [ litellm1.40.0, lancedb0.6.0, pyarrow15.0.0, pydantic2.5.0, numpy1.24.0, pyyaml6.0, tiktoken0.6.0, graspologic-native1.2.0, ] [project.optional-dependencies] dev [ pytest7.4.0, ruff0.4.0, poethepoet0.24.0, ] [tool.uv] dev-dependencies [ pytest7.4.0, ruff0.4.0, ]这里litellm是关键它负责统一调用各家模型接口completion 和 embedding 都走它。lancedb和pyarrow负责向量存储pydantic负责配置校验。版本号不要卡太死但pydantic必须 2.x因为 GraphRAG 的配置模型用的是Literal和BaseModel新特性。装完之后用uv run poe --help看看 poe 任务有没有注册进来。正常应该能看到index、query、test这些任务。如果poe命令找不到说明poethepoet没装补一句uv pip install poethepoet即可。依赖这关过了接下来才是真正的硬骨头embedding 配置。3. settings.yaml 里 litellm embedding 的可复制配置GraphRAG 的模型配置全在settings.yaml里completion 和 embedding 分开写。很多人第一次配的时候把 completion 配通了embedding 随便填了个 ollama结果索引跑到向量化那一步就崩。下面给一份能直接用的配置先讲本地 ollama 方案再讲云端兼容方案。本地 ollama 方案前提是你已经ollama serve起来并且ollama pull nomic-embed-text拉过模型embedding_models: default_embedding_model: model_provider: ollama model: nomic-embed-text api_base: http://localhost:11434 auth_method: api_key api_key: ollama extra_params: encoding_format: float注意这里用的是api_base而不是base_url。GraphRAG 新版本对 litellm 的透传参数做了调整base_url在某些版本里会被忽略导致 litellm 找不到 provider报LLM Provider NOT provided。改成api_base后litellm 能正确识别 ollama 的 OpenAI 兼容接口。云端兼容方案以阿里云 dashscope 的 OpenAI 兼容模式为例embedding_models: default_embedding_model: model_provider: openai model: text-embedding-v3 api_base: https://dashscope.aliyuncs.com/compatible-mode/v1 auth_method: api_key api_key: sk-你的key extra_params: encoding_format: float这里model_provider写openai因为 dashscope 提供的是 OpenAI 兼容接口litellm 走 openai 分支就能通。extra_params里的encoding_format: float是必须的否则某些接口会报encoding_format only support with [float, base64]。如果你用 TaoToken 这类聚合接入服务配置思路一样把api_base换成对应的兼容端点api_key换成你的 keymodel填你要用的 embedding 模型 ID。TaoToken 的 API 地址是https://taotoken.net/api模型对话入口在https://taotoken.net/models接入文档在https://taotoken.net/doc。配置时记得三件套齐全Base URL、Key、Model ID缺一个都会报 provider 找不到。completion 模型也顺手给一份方便你对照completion_models: default_completion_model: model_provider: openai model: deepseek-chat api_base: https://api.deepseek.com/v1 auth_method: api_key api_key: sk-你的key timeout: 300 max_retries: 3 retry: type: exponential_backoff base_delay: 5 max_delay: 60这里有个坑auth_method只能是api_key或azure_managed_identity写none会直接触发ValidationError。因为 GraphRAG 的LLMConfig里用了Literal[api_key, azure_managed_identity]pydantic 会严格校验。配置写完后把settings.yaml放到你的工作根目录下比如./inputs/settings.yaml。GraphRAG 会把--root指定的目录当作 workspace root所有相对路径都基于它查找。输入文本放./inputs/input/prompt 模板放./inputs/prompts/。prompts 目录需要从仓库里复制过去否则索引时会提示找不到模板。4. 索引构建验证与向量维度一致性检查配置就绪后执行索引命令uv run poe index --root ./inputs这条命令会依次跑实体抽取、关系抽取、社区检测、embedding 向量化、写入 LanceDB。成功的话终端最后会打印Pipeline complete并且./inputs/output/下会生成一堆 parquet 文件和 lancedb 目录。验证索引是否真的成功别只看终端。做三个检查动作第一看输出目录结构ls -R ./inputs/output | head -50正常应该能看到create_final_entities.parquet、create_final_relationships.parquet、create_final_communities.parquet这些文件。如果只有stats.json没有 parquet说明流程中途挂了。第二用 python 读一下实体数量uv run python -c import pandas as pd df pd.read_parquet(./inputs/output/create_final_entities.parquet) print(实体数量:, len(df)) print(df[[title, type]].head()) 能打印出实体和类型说明抽取成功。第三检查向量维度。这是最容易出问题的地方。打开./inputs/output/lancedb/下的表或者直接在代码里读uv run python -c import lancedb db lancedb.connect(./inputs/output/lancedb) tbl db.open_table(default-entity-description) print(tbl.schema) 重点看 vector 字段的维度。如果你换了 embedding 模型维度必须和settings.yaml里配置的一致。比如nomic-embed-text是 768 维text-embedding-v3是 1024 维。GraphRAG 内部有个DEFAULT_VECTOR_SIZE默认可能是 1024 或 1536如果你用的模型维度对不上就会报Column 1 named vector expected length 400 but got length 100这类错误。这个报错的本质是LanceDB 建表时按某个维度创建了 FixedSizeListArray但实际写入的向量长度不一样。解决办法有两个一是统一 embedding 模型别混用二是改DEFAULT_VECTOR_SIZE匹配你的模型。改完之后一定要删掉output/和cache/目录因为里面存了旧维度的向量不删会继续报错。rm -rf ./inputs/output ./inputs/cache删完重新跑索引让 LanceDB 按新维度重建表。这一步很多人忘改完配置直接重跑结果还是老报错就是因为缓存没清。5. litellm 报错排查401、BadRequestError 与维度不匹配复现过程中最常见的报错集中在 litellm 这一层下面按真实报错逐条对照。报错一litellm.BadRequestError: LLM Provider NOT provided这个通常是因为settings.yaml里model_provider没写对或者api_base写成了base_url导致 litellm 识别不出 provider。检查三件套model_provider、api_base、model是否齐全。如果是自定义兼容端点model_provider写openaiapi_base写完整路径。报错二401 Unauthorized或AuthenticationErrorkey 错了或者没传。检查api_key字段有没有引号包住yaml 里sk-xxx不加引号可能被解析成特殊类型。另外确认auth_method: api_key写了不然 GraphRAG 不会把 key 透传给 litellm。报错三litellm.BadRequestError: DeepseekException - This response_format type is unavailable now这是 completion 模型返回格式的问题。DeepSeek 某些版本不支持response_format: json_object但 GraphRAG 默认会传。解决办法是在packages/graphrag-llm/graphrag_llm/completion/lite_llm_completion.py里做兼容处理检测到 provider 是 deepseek 时不直接传response_format而是在 messages 末尾追加一句「Please respond in JSON only」再把response_format设成{type: json_object}。同时把返回的response.choices[0].message.content用json.loads解析后塞进response.formatted_response。报错四Column 1 named vector expected length 400 but got length 100向量维度不匹配。前面讲过统一模型 改DEFAULT_VECTOR_SIZE 删 output/cache。如果还不行去packages/graphrag-vectors/graphrag_vectors/lancedb.py的load_documents里加调试输出打印每个向量的 shape 和self.vector_size看看到底哪个环节维度变了。报错五litellm.APIConnectionError: OllamaException - Client error 400 Bad Requestollama 日志里会显示the input length exceeds the context length。这是 chunk 太大超过了 embedding 模型的上下文窗口。调小chunk_size或者换上下文更长的 embedding 模型。改完同样要清 output/cache。报错六encoding_format only support with [float, base64]在settings.yaml的 embedding 配置里加extra_params: encoding_format: float。如果还报去.venv/Lib/site-packages/litellm/llms/openai/openai.py的_base_embedding和_base_embedding_async里在new_args构造后强制加new_args[encoding_format] float。报错七OAuth相关或local proxy failed这类多半是网络层或认证方式不对。确认没有走任何本地代理api_base直连。如果是企业内网检查出口是否放行。GraphRAG 本身不涉及代理配置报这个通常是环境变量里残留了HTTP_PROXY清掉再试。排查时建议开两个终端一个跑索引一个tail -follama 或服务端日志报错能第一时间定位到是哪一步。6. 从环境到模型接入的完整复现路径与 CTA把上面的步骤串起来完整路径是这样的先cd packages/graphrag uv pip install -e .确保包装上再配好settings.yaml的 completion 和 embedding 两段把 prompts 复制到./inputs/prompts/输入文本放./inputs/input/然后uv run poe index --root ./inputs。跑通后检查 output 目录和向量维度出报错就按第 5 节对照排查。如果你不想在本地折腾 ollama 的模型拉取和显存占用可以用聚合接入的方式把 completion 和 embedding 都指向统一的兼容端点。配置时记住三件套Base URL 填https://taotoken.net/apiKey 在控制台生成Model ID 按你要用的模型填。生成 Key 的入口在https://taotoken.net/api-keys接入文档在https://taotoken.net/doc模型列表可以在https://taotoken.net/models里查。想先验证模型通不通直接去https://taotoken.net/models发一条测试消息最快。长期做编码和 Agent 复现的话可以考虑 Coding Plan入口在https://taotoken.net/coding-plan。Claude Code 相关的接入配置在https://taotoken.net/claude-code-anthropic控制台在https://taotoken.net/console。最后留一个实用技巧每次改完settings.yaml里的模型或维度先rm -rf output cache再重跑能省掉一半的「改了没用」的困惑。索引跑通后用uv run poe query --root ./inputs提个问题能返回带社区摘要的答案就说明整条链路真正打通了。