GraphRAG 如何配置 Azure OpenAI 作为聊天与嵌入模型后端？
【免费下载链接】graphragA modular graph-based Retrieval-Augmented Generation (RAG) system项目地址: https://gitcode.com/GitHub_Trending/gr/graphrag
如果你刚在本地装好 GraphRAG，准备用它对文档建索引并回答文档相关问题，但你的模型资源在 Azure OpenAI 上而不是 OpenAI 直连，那么需要把settings.yaml中的默认聊天模型和嵌入模型两个端点改造成 Azure 配置。完成后的目标是：graphrag index能跑完并生成./output结果，graphrag query能基于索引返回答案。
以下内容依据仓库文档 docs/get_started.md、docs/config/models.md 和 docs/config/yaml.md 整理，适用于 GraphRAG 首次安装后切换到 Azure OpenAI 后端的场景。
准备条件
- Python 3.10–3.12。
- 一个可用的 Azure OpenAI 资源，且已经在其中部署了你要使用的聊天模型和嵌入模型。你需要拿到：部署名（deployment name）、实例的 API 地址（形如
https://<instance>.openai.azure.com）、API key（或改用托管身份），以及 API 版本。 - 注意官方提醒：GraphRAG 会消耗较多 LLM 资源，建议先用教程级的小数据集跑通流程，再考虑大的索引任务。
安装并初始化工作区
创建一个独立的项目目录和虚拟环境：
mkdir graphrag_quickstart cd graphrag_quickstart python -m venv .venv激活虚拟环境（Unix/MacOS 用source .venv/bin/activate，Windows 用.venv\Scripts\activate），然后安装：
python -m pip install graphrag在项目目录内运行初始化命令：
graphrag init命令会提示你选择默认聊天模型和嵌入模型，随后在当前目录生成三样东西：
.env：包含运行管线所需的环境变量，初始内容为GRAPHRAG_API_KEY=<API_KEY>；settings.yaml：管线配置文件，模型端点就在其中；input目录：放置待处理的文本文件。
初始化细节可参考 docs/config/init.md。
配置 .env 中的 Azure API Key
打开.env，把GRAPHRAG_API_KEY的值替换为你的 Azure OpenAI API key（使用托管身份的方案除外，见文末可选分支）。
修改 settings.yaml：聊天与嵌入两个模型端点
在settings.yaml中定位模型配置区（文档建议直接搜索models:根配置）。该文件中有两个端点小节：默认聊天端点和默认嵌入端点，两处都要改成 Azure 配置。聊天模型配置的写法如下（摘自 docs/get_started.md）：
type: chat model_provider: azure model: gpt-4.1 azure_deployment_name: <AZURE_DEPLOYMENT_NAME> api_base: https://<instance>.openai.azure.com api_version: 2024-02-15-preview # You can customize this for other versions代码块中的两个占位符需要你按自己的资源替换：
<AZURE_DEPLOYMENT_NAME>：你在 Azure 上该聊天模型的部署名；<instance>：你的 Azure OpenAI 实例名。
api_version文档说明可按需改成其他版本。各字段的完整含义见 docs/config/yaml.md：
model_provider：模型提供方，Azure 环境填azure；api_base：API 基础地址；api_version：API 版本；azure_deployment_name：Azure 上的部署名——如果你的部署名与模型名一致，这一项可以省略；auth_method：取值api_key（默认）或azure_managed_identity。
嵌入模型端点做同样的事：在该小节把model_provider改为azure，并配上你的嵌入模型部署名、api_base、api_version。初始化生成的配置中两个端点位于completion_models:与embedding_models:两个小节下，api_key默认引用${GRAPHRAG_API_KEY}，与.env中的变量对应。
可选分支：使用托管身份认证
如果你的环境用 Azure 托管身份而不是 API key，按文档修改模型配置中的认证方式，并删除api_key行：
auth_method: azure_managed_identity # Default auth_method is api_key同时需要先用az login登录，并选择你的端点所在的订阅。此分支下.env中的 key 不再是认证依据。
运行索引并验证配置生效
在input/目录放一份测试文本（文档给出的示例是从 Project Gutenberg 下载《A Christmas Carol》）：
curl https://www.gutenberg.org/cache/epub/24022/pg24022.txt -o ./input/book.txt执行索引：
graphrag index该过程通常需要几分钟。管线跑完后的判断标准是：当前目录下出现./output文件夹，里面是一组 parquet 文件（如documents.parquet、entities.parquet、text_units.parquet等）。
索引成功后，用查询命令做端到端验证。Global search 问一个整体性问题：
graphrag query "What are the top themes in this story?"Local search 问更具体的问题：
graphrag query \ "Who is Scrooge and what are his main relationships?" \ --method local能返回基于文档内容的回答，说明聊天端点和嵌入端点都正确指向了你的 Azure OpenAI 资源。
限制与注意事项
api_version示例中的2024-02-15-preview只是文档示例值，可按你的资源支持的版本自定义。- 文档同时说明：GraphRAG 用 OpenAI 系列模型构建和测试得最充分；非 OpenAI 模型通过 LiteLLM 接入，且所选模型必须支持按 JSON schema 返回结构化输出。这一点在选择 Azure 上的具体模型部署时需要注意，详见 docs/config/models.md。
- 若索引或查询阶段报错，先回到
settings.yaml的两个模型小节核对：api_base、api_version、部署名，以及认证方式与.env/托管身份是否一致。CLI 各项子命令说明见 docs/cli.md。
【免费下载链接】graphragA modular graph-based Retrieval-Augmented Generation (RAG) system项目地址: https://gitcode.com/GitHub_Trending/gr/graphrag
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
