GraphRAG 安装时 LiteLLM 构建失败排查记录

在 Windows 环境中使用 uv 安装 GraphRAG：

uv add graphrag

依赖解析能够正常完成，但安装过程在构建 litellm==1.92.0 时失败。

环境信息#

操作系统：Windows x64
Python：CPython 3.12（原本使用Python 3.14 但LiteLLM 1.92.0 没有 CPython 3.14 Wheel）
包管理工具：uv
GraphRAG：3.1.1
LiteLLM：1.92.0
Rust：1.97.1

为什么安装 GraphRAG 会构建 LiteLLM#

litellm 不是 graphrag 顶层包直接声明的依赖，而是由 graphrag-llm 引入的间接依赖：

graphrag-demo 0.1.0
└── graphrag 3.1.1
    └── graphrag-llm 3.1.1
        └── litellm 1.92.0

GraphRAG 使用 LiteLLM 作为统一的大模型调用层，主要承担以下工作：

调用聊天模型，包括同步、异步和流式请求；
调用 Embedding 模型生成文本向量；
统一 OpenAI、Azure OpenAI 等不同模型服务的请求参数、响应和异常；
进行 Token 编码、解码和上下文长度控制；
获取模型费用信息，并为调用指标统计提供数据。

在 GraphRAG 的实际流程中，实体与关系提取、社区摘要、查询向量化以及最终答案生成都会用到这些能力。LiteLLM 本身不负责知识图谱构建、社区检测或向量存储，它位于 GraphRAG 与模型 API 之间。

为什么 Windows 下触发了本地构建#

litellm 1.92.0 在 PyPI 上没有提供适用于 win-amd64 的预编译 Wheel，只提供了 Linux Wheel 和源码包。uv 在 Windows 上找不到可直接安装的 Wheel，因此会下载源码包，并通过 maturin、Cargo 和 MSVC 构建其中的 Python/Rust 混合扩展。

构建过程大致如下：

uv
└── maturin
    └── cargo
        └── rustc + MSVC linker

因此，这次报错并不是依赖解析失败，而是 Windows 本地原生扩展构建环境出现了问题。

找不到 link.exe#

执行安装时，Rust 编译器已经能够启动，但无法找到 MSVC 链接器：

error: linker `link.exe` not found

note: the msvc targets depend on the msvc linker but `link.exe` was not found
note: please ensure that Visual Studio 2017 or later, or Build Tools for Visual Studio were installed

这说明 Rust 工具链本身不是主要问题。当前使用的是 x86_64-pc-windows-msvc 目标，它除了需要 rustc 和 Cargo，还依赖 Visual Studio C++ Build Tools 提供的编译器、链接器和 Windows SDK。

解决方案#

主要方案就是补全系统里缺少的环境依赖。

前往Visual Studio Installer页面下载Build Tools for Visual Studio。

下载后会默认给你安装一个Visual Stuido Installer，我们可以在这里面安装需要的依赖。

针对这次的问题，最小只需要勾选以下两条。

安装完毕后，重启终端再次安装GraphRag依赖即可。