尧图网页设计 
GraphRAG 从零到一CLI 快速上手索引与查询非结构化文本的完整实践【免费下载链接】graphragA modular graph-based Retrieval-Augmented Generation (RAG) system项目地址: https://gitcode.com/GitHub_Trending/gr/graphrag本篇基于仓库官方入门文档 docs/get_started.md 展开系统讲解 GraphRAG一个基于图结构的模块化检索增强生成系统的端到端命令行工作流从创建项目、初始化工作区、配置 OpenAI/Azure OpenAI 模型凭据到执行graphrag index构建知识图谱索引最终使用 Global/Local 两种检索方式对文档库进行自然语言问答。读完本文你可以独立完成一套可运行的 GraphRAG 索引与查询环境并理解每个 CLI 命令背后生成的文件与底层调用链路。开始前成本警示与适用前提官方文档与 README.md 都给出了明确提醒GraphRAG 的索引过程可能消耗大量 LLM 资源每个文档切块都要经过实体抽取、描述汇总、社区报告生成等多个 LLM 调用因此官方强烈建议先使用仓库内置的教程数据集跑通流程理解系统运作方式后再投入大规模索引任务先用快速、廉价的模型做实验确认管线可用后再切换到更昂贵的模型执行正式索引另外需要注意README 声明该项目目前处于维护模式maintenance mode以缺陷修复和依赖更新为主不再接受新功能 PR——这对选型评估是一个重要前提。环境要求Python入门文档标注为 Python 3.10–3.12。需要注意的是当前仓库中 packages/graphrag/pyproject.toml 的包元数据声明为requires-python 3.11,3.14即以包元数据为准当前实际支持 3.11–3.13 版本区间。一个 LLM 服务凭据OpenAI API Key或 Azure OpenAI 的部署信息与凭据。从 PyPI 安装的graphrag发行包当前仓库版本为 3.1.1。安装 GraphRAG创建项目空间mkdir graphrag_quickstart cd graphrag_quickstart python -m venv .venv激活虚拟环境Unix/macOSsource .venv/bin/activateWindows.venv\Scripts\activate安装python -m pip install graphrag安装完成后会得到graphrag命令。从源码看该命令入口在 packages/graphrag/pyproject.toml 中通过[project.scripts]注册为graphrag graphrag.cli.main:app即 packages/graphrag/graphrag/cli/main.py 中基于 Typer 构建的app。该文件定义了全部五个子命令init、index、update、prompt-tune、query。初始化工作区graphrag init在项目目录下执行graphrag init执行过程中命令行会提示你填写默认对话模型--model/-m与默认嵌入模型--embedding/-e。当前版本的默认值定义在 packages/graphrag/graphrag/config/defaults.py 中对话模型为gpt-4.1嵌入模型为text-embedding-3-large提供商默认openai。除交互填写外还可以用--root/-r指定项目根目录、--force/-f强制覆盖已有项目。执行成功后当前目录会生成以下内容对照 packages/graphrag/graphrag/cli/initialize.py 中initialize_project_at的实现可以逐一确认产物作用input/目录待处理的文本文件存放位置input_storage.base_dir默认为input.env流水线运行所需的环境变量仅定义GRAPHRAG_API_KEYAPI_KEY一项需替换为你自己的 API Keysettings.yaml流水线完整配置后续所有调优都改这个文件prompts/目录14 个默认提示词文件实体抽取、描述汇总、社区报告、各检索方式的系统提示词等入门文档未提及但源码中确实会创建它们与settings.yaml中各prompt路径一一对应其中settings.yaml的模板由 packages/graphrag/graphrag/config/init_content.py 中的INIT_YAML生成包含几大板块值得先建立整体印象LLM settingscompletion_models与embedding_models两个模型段各自声明model_provider、model、auth_method、api_key引用${GRAPHRAG_API_KEY}以及retry重试策略Document processinginput.type支持 csv、text、json、jsonl与chunking默认 token 切块size: 1200、overlap: 100、encoding_model: o200k_baseStorage settingsinput_storage/output_storage/reporting/cache/vector_store五类存储配置base_dir分别为input、output、log、cache等Workflow settingsextract_graph默认实体类型[organization, person, geo, event]、summarize_descriptions、cluster_graphmax_cluster_size: 10、extract_claims默认enabled: false、community_reports等索引工作流参数Query settingslocal_search、global_search、drift_search、basic_search四种检索方式的模型绑定与提示词路径。完整的配置项说明可参见 docs/config/overview.md初始化细节见 docs/config/init.md。版本升级提示README.md 建议跨小版本升级时始终运行graphrag init --root [path] --force以刷新到最新配置格式跨大版本升级则应运行仓库提供的迁移 Notebook如 docs/examples_notebooks/index_migration_to_v3.ipynb以避免重新索引注意该操作会覆盖现有配置与提示词必要时先备份。配置工作区变量使用 OpenAIOpenAI 模式下只需编辑.env将GRAPHRAG_API_KEYAPI_KEY中的API_KEY替换为你自己的 OpenAI API Key其余无需改动。使用 Azure OpenAIAzure 用户除 API Key 外还需在settings.yaml中配置模型部署信息。在文件中搜索models:根配置可以定位到默认的对话与嵌入两个端点段。以对话模型为例需要补充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 # 可按实际订阅版本自定义嵌入模型段做同样的处理。Azure 托管身份Managed Identity若希望跳过 API Key 改用托管身份认证编辑对应模型段将auth_method改为azure_managed_identity并删除api_key行auth_method: azure_managed_identity # 默认 auth_method 为 api_keyauth_method的可选值由 packages/graphrag/graphrag-llm 中的AuthMethod枚举定义默认值为api_key。启用托管身份后还需要通过 Azure CLI 登录az login并选择你的端点所在订阅。准备样例数据入门文档以狄更斯的《A Christmas Carol》Project Gutenberg作为示例语料curl https://www.gutenberg.org/cache/epub/24022/pg24022.txt -o ./input/book.txt下载后文件落入input/目录即成为索引流水线的输入。如果希望用规模更小、更适合调试的数据集仓库在 docs/data/operation_dulce/ 提供了官方教程数据集 Operation Dulce含 ABOUT.md 与正文文档文档开头的“先用教程数据集熟悉系统”的建议正指向这类数据。构建索引graphrag indexgraphrag index该过程通常运行数分钟完成后会在./output目录生成一系列 Parquet 文件。output/中的产物结构与仓库示例 docs/examples_notebook/inputs/operation dulce/ 中展示的一致包括documents.parquet、text_units.parquet、entities.parquet、relationships.parquet、communities.parquet、community_reports.parquet、covariates.parquet及各嵌入表如embeddings.community_full_content.parquet——它们分别对应文档切块、实体关系图、Leiden 社区划分与社区报告等索引阶段。index 命令的完整参数从 packages/graphrag/graphrag/cli/main.py 中_index_cli的定义可以确认全部选项参数默认值说明--root/-r当前目录项目根目录--method/-mstandard索引方法--verbose/-vFalse以详细日志模式运行索引管线--dry-runFalse只校验配置、不执行任何步骤--cache/--no-cacheTrue是否启用 LLM 缓存缓存命中可显著降低重复运行的 token 消耗--skip-validationFalse跳过预检校验适用于不含 LLM 步骤的运行实现链路上graphrag index先经 packages/graphrag/graphrag/cli/index.py 中的index_cli加载配置load_config解析settings.yaml并做配置名校验再进入_run_index驱动异步管线同一文件还注册了SIGINT/SIGHUP信号处理器确保中断信号到达时取消所有异步任务、干净退出。--dry-run是花真金白银跑全量索引前值得养成的习惯。此外 CLI 还提供了一个文档未强调的graphrag update子命令可对已有索引做增量更新新结果默认写入update_output/目录。查询graphrag query索引完成后即可提问。入门文档给了两个代表性例子。Global Search全局检索——面向整体性、高层面的问题基于社区报告进行 map-reduce 式聚合graphrag query What are the top themes in this story?query子命令默认检索方法就是global见 packages/graphrag/graphrag/cli/main.py 中SearchMethod.GLOBAL的默认值因此上面第一条命令无需--method。Local Search局部检索——面向特定实体/角色的具体问题以实体为中心组织上下文graphrag query \ Who is Scrooge and what are his main relationships? \ --method local--method完整取值由SearchMethod枚举给出local、global、drift、basic四种方法在 packages/graphrag/graphrag/cli/query.py 中分别分发到run_local_search、run_global_search、run_drift_search、run_basic_search。各方法从索引中加载的表也不同例如 global search 会解析entities、communities、community_reports三张 Parquet见该文件中_resolve_output_files的output_list。其余常用参数参数默认值说明--root/-r当前目录项目根目录--data/-d配置中的输出目录指向含 Parquet 的索引输出目录--community-level2加载社区报告的 Leiden 层级数值越大社区粒度越小--response-typeMultiple Paragraphs自由描述期望的回答格式如Single Sentence、List of 3-7 Points--streaming/--no-streamingFalse流式打印回答--dynamic-community-selectionFalseglobal search 启用动态社区选择各检索方法的原理与调参细节请继续阅读 docs/query/overview.md、docs/query/local_search.md 与 docs/query/global_search.md。延伸阅读配置体系全解docs/config/overview.md初始化机制docs/config/init.mdCLI 完整参考docs/cli.md该页基于graphrag.cli.main模块用 mkdocs-typer 自动生成知识图谱的交互式可视化调试docs/visualization_guide.md用真实数据微调提示词以提升抽取质量docs/prompt_tuning/overview.mdgraphrag prompt-tune子命令开发模式源码方式安装与调试DEVELOPING.md按以上流程走完后你就拥有了一个完整的 GraphRAG 工作区input/放语料graphrag index产出output/下的图与社区数据graphrag query用四种检索方法在其上问答后续任何调优都落在settings.yaml与prompts/目录内。【免费下载链接】graphragA modular graph-based Retrieval-Augmented Generation (RAG) system项目地址: https://gitcode.com/GitHub_Trending/gr/graphrag创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 GraphRAG 从零到一：CLI 快速上手，索引与查询非结构化文本的完整实践
GraphRAG 从零到一CLI 快速上手索引与查询非结构化文本的完整实践【免费下载链接】graphragA modular graph-based Retrieval-Augmented Generation (RAG) system项目地址: https://gitcode.com/GitHub_Trending/gr/graphrag本篇基于仓库官方入门文档 docs/get_started.md 展开系统讲解 GraphRAG一个基于图结构的模块化检索增强生成系统的端到端命令行工作流从创建项目、初始化工作区、配置 OpenAI/Azure OpenAI 模型凭据到执行graphrag index构建知识图谱索引最终使用 Global/Local 两种检索方式对文档库进行自然语言问答。读完本文你可以独立完成一套可运行的 GraphRAG 索引与查询环境并理解每个 CLI 命令背后生成的文件与底层调用链路。开始前成本警示与适用前提官方文档与 README.md 都给出了明确提醒GraphRAG 的索引过程可能消耗大量 LLM 资源每个文档切块都要经过实体抽取、描述汇总、社区报告生成等多个 LLM 调用因此官方强烈建议先使用仓库内置的教程数据集跑通流程理解系统运作方式后再投入大规模索引任务先用快速、廉价的模型做实验确认管线可用后再切换到更昂贵的模型执行正式索引另外需要注意README 声明该项目目前处于维护模式maintenance mode以缺陷修复和依赖更新为主不再接受新功能 PR——这对选型评估是一个重要前提。环境要求Python入门文档标注为 Python 3.10–3.12。需要注意的是当前仓库中 packages/graphrag/pyproject.toml 的包元数据声明为requires-python 3.11,3.14即以包元数据为准当前实际支持 3.11–3.13 版本区间。一个 LLM 服务凭据OpenAI API Key或 Azure OpenAI 的部署信息与凭据。从 PyPI 安装的graphrag发行包当前仓库版本为 3.1.1。安装 GraphRAG创建项目空间mkdir graphrag_quickstart cd graphrag_quickstart python -m venv .venv激活虚拟环境Unix/macOSsource .venv/bin/activateWindows.venv\Scripts\activate安装python -m pip install graphrag安装完成后会得到graphrag命令。从源码看该命令入口在 packages/graphrag/pyproject.toml 中通过[project.scripts]注册为graphrag graphrag.cli.main:app即 packages/graphrag/graphrag/cli/main.py 中基于 Typer 构建的app。该文件定义了全部五个子命令init、index、update、prompt-tune、query。初始化工作区graphrag init在项目目录下执行graphrag init执行过程中命令行会提示你填写默认对话模型--model/-m与默认嵌入模型--embedding/-e。当前版本的默认值定义在 packages/graphrag/graphrag/config/defaults.py 中对话模型为gpt-4.1嵌入模型为text-embedding-3-large提供商默认openai。除交互填写外还可以用--root/-r指定项目根目录、--force/-f强制覆盖已有项目。执行成功后当前目录会生成以下内容对照 packages/graphrag/graphrag/cli/initialize.py 中initialize_project_at的实现可以逐一确认产物作用input/目录待处理的文本文件存放位置input_storage.base_dir默认为input.env流水线运行所需的环境变量仅定义GRAPHRAG_API_KEYAPI_KEY一项需替换为你自己的 API Keysettings.yaml流水线完整配置后续所有调优都改这个文件prompts/目录14 个默认提示词文件实体抽取、描述汇总、社区报告、各检索方式的系统提示词等入门文档未提及但源码中确实会创建它们与settings.yaml中各prompt路径一一对应其中settings.yaml的模板由 packages/graphrag/graphrag/config/init_content.py 中的INIT_YAML生成包含几大板块值得先建立整体印象LLM settingscompletion_models与embedding_models两个模型段各自声明model_provider、model、auth_method、api_key引用${GRAPHRAG_API_KEY}以及retry重试策略Document processinginput.type支持 csv、text、json、jsonl与chunking默认 token 切块size: 1200、overlap: 100、encoding_model: o200k_baseStorage settingsinput_storage/output_storage/reporting/cache/vector_store五类存储配置base_dir分别为input、output、log、cache等Workflow settingsextract_graph默认实体类型[organization, person, geo, event]、summarize_descriptions、cluster_graphmax_cluster_size: 10、extract_claims默认enabled: false、community_reports等索引工作流参数Query settingslocal_search、global_search、drift_search、basic_search四种检索方式的模型绑定与提示词路径。完整的配置项说明可参见 docs/config/overview.md初始化细节见 docs/config/init.md。版本升级提示README.md 建议跨小版本升级时始终运行graphrag init --root [path] --force以刷新到最新配置格式跨大版本升级则应运行仓库提供的迁移 Notebook如 docs/examples_notebooks/index_migration_to_v3.ipynb以避免重新索引注意该操作会覆盖现有配置与提示词必要时先备份。配置工作区变量使用 OpenAIOpenAI 模式下只需编辑.env将GRAPHRAG_API_KEYAPI_KEY中的API_KEY替换为你自己的 OpenAI API Key其余无需改动。使用 Azure OpenAIAzure 用户除 API Key 外还需在settings.yaml中配置模型部署信息。在文件中搜索models:根配置可以定位到默认的对话与嵌入两个端点段。以对话模型为例需要补充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 # 可按实际订阅版本自定义嵌入模型段做同样的处理。Azure 托管身份Managed Identity若希望跳过 API Key 改用托管身份认证编辑对应模型段将auth_method改为azure_managed_identity并删除api_key行auth_method: azure_managed_identity # 默认 auth_method 为 api_keyauth_method的可选值由 packages/graphrag/graphrag-llm 中的AuthMethod枚举定义默认值为api_key。启用托管身份后还需要通过 Azure CLI 登录az login并选择你的端点所在订阅。准备样例数据入门文档以狄更斯的《A Christmas Carol》Project Gutenberg作为示例语料curl https://www.gutenberg.org/cache/epub/24022/pg24022.txt -o ./input/book.txt下载后文件落入input/目录即成为索引流水线的输入。如果希望用规模更小、更适合调试的数据集仓库在 docs/data/operation_dulce/ 提供了官方教程数据集 Operation Dulce含 ABOUT.md 与正文文档文档开头的“先用教程数据集熟悉系统”的建议正指向这类数据。构建索引graphrag indexgraphrag index该过程通常运行数分钟完成后会在./output目录生成一系列 Parquet 文件。output/中的产物结构与仓库示例 docs/examples_notebook/inputs/operation dulce/ 中展示的一致包括documents.parquet、text_units.parquet、entities.parquet、relationships.parquet、communities.parquet、community_reports.parquet、covariates.parquet及各嵌入表如embeddings.community_full_content.parquet——它们分别对应文档切块、实体关系图、Leiden 社区划分与社区报告等索引阶段。index 命令的完整参数从 packages/graphrag/graphrag/cli/main.py 中_index_cli的定义可以确认全部选项参数默认值说明--root/-r当前目录项目根目录--method/-mstandard索引方法--verbose/-vFalse以详细日志模式运行索引管线--dry-runFalse只校验配置、不执行任何步骤--cache/--no-cacheTrue是否启用 LLM 缓存缓存命中可显著降低重复运行的 token 消耗--skip-validationFalse跳过预检校验适用于不含 LLM 步骤的运行实现链路上graphrag index先经 packages/graphrag/graphrag/cli/index.py 中的index_cli加载配置load_config解析settings.yaml并做配置名校验再进入_run_index驱动异步管线同一文件还注册了SIGINT/SIGHUP信号处理器确保中断信号到达时取消所有异步任务、干净退出。--dry-run是花真金白银跑全量索引前值得养成的习惯。此外 CLI 还提供了一个文档未强调的graphrag update子命令可对已有索引做增量更新新结果默认写入update_output/目录。查询graphrag query索引完成后即可提问。入门文档给了两个代表性例子。Global Search全局检索——面向整体性、高层面的问题基于社区报告进行 map-reduce 式聚合graphrag query What are the top themes in this story?query子命令默认检索方法就是global见 packages/graphrag/graphrag/cli/main.py 中SearchMethod.GLOBAL的默认值因此上面第一条命令无需--method。Local Search局部检索——面向特定实体/角色的具体问题以实体为中心组织上下文graphrag query \ Who is Scrooge and what are his main relationships? \ --method local--method完整取值由SearchMethod枚举给出local、global、drift、basic四种方法在 packages/graphrag/graphrag/cli/query.py 中分别分发到run_local_search、run_global_search、run_drift_search、run_basic_search。各方法从索引中加载的表也不同例如 global search 会解析entities、communities、community_reports三张 Parquet见该文件中_resolve_output_files的output_list。其余常用参数参数默认值说明--root/-r当前目录项目根目录--data/-d配置中的输出目录指向含 Parquet 的索引输出目录--community-level2加载社区报告的 Leiden 层级数值越大社区粒度越小--response-typeMultiple Paragraphs自由描述期望的回答格式如Single Sentence、List of 3-7 Points--streaming/--no-streamingFalse流式打印回答--dynamic-community-selectionFalseglobal search 启用动态社区选择各检索方法的原理与调参细节请继续阅读 docs/query/overview.md、docs/query/local_search.md 与 docs/query/global_search.md。延伸阅读配置体系全解docs/config/overview.md初始化机制docs/config/init.mdCLI 完整参考docs/cli.md该页基于graphrag.cli.main模块用 mkdocs-typer 自动生成知识图谱的交互式可视化调试docs/visualization_guide.md用真实数据微调提示词以提升抽取质量docs/prompt_tuning/overview.mdgraphrag prompt-tune子命令开发模式源码方式安装与调试DEVELOPING.md按以上流程走完后你就拥有了一个完整的 GraphRAG 工作区input/放语料graphrag index产出output/下的图与社区数据graphrag query用四种检索方法在其上问答后续任何调优都落在settings.yaml与prompts/目录内。【免费下载链接】graphragA modular graph-based Retrieval-Augmented Generation (RAG) system项目地址: https://gitcode.com/GitHub_Trending/gr/graphrag创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考