GraphRAG Unified Search 实战用 Streamlit 横向对比 Basic / Local / Global / Drift 四种检索【免费下载链接】graphragA modular graph-based Retrieval-Augmented Generation (RAG) system项目地址: https://gitcode.com/GitHub_Trending/gr/graphragGraphRAG 仓库中的unified-search-app是一个基于 Streamlit 的演示应用它把 GraphRAG 的四种检索方案Basic RAG、Local Search、Global Search、Drift Search放进同一个界面并行执行让你对同一问题直接对比不同检索的回答与引用来源从而直观理解「基于知识图谱的 RAG」相对朴素向量检索的差异。读完本文你将掌握该应用的数据目录规范、listing.json注册方式、本地与 Azure Blob 两种数据承载方案、uv一键启动流程以及左右面板各交互控件的用法。⚠️ 注意该应用官方定位为 demo/experimental 用途不属于受支持的正式产品对 GraphRAG 主仓库提的 issue 可能不会被处理。应用概览为什么要做一个「Unified Search」GraphRAG 的查询能力分布在多种检索算法上对应 packages/graphrag/graphrag/api/query.py 暴露的basic_search、local_search、global_search、drift_search不同算法的「答案上下文」来源差异很大Basic RAG仅检索固定数量的原始文档文本块纯向量检索基线Local Search查询图谱索引得到的实体/关系/社区报告再补充相关文本块Global Search基于覆盖全部输入文档的 AI 生成的社区报告作答Drift Search结合社区信息进行发散式检索。Unified Search 的目标就是把「同一个问题、不同检索、多个答案」并排呈现在一个 Web 页面上。从 app/home_page.py 的main()可以看到选中的检索结果会按列st.columns(count)并排渲染每一列标题下方都带一行说明该列答案上下文来源的 caption四个开关的默认值定义在 app/state/session_variables.pyGlobal 与 Local 默认开启Basic RAG 与 Drift Search 默认关闭且至少要开启一个检索否则页面会提示 Please select at least one search option from the sidebar.。环境准备与依赖安装该示例应用没有发布到 PyPI因此必须先把 GraphRAG 仓库克隆到本地然后在该子目录内运行。版本前提README 明确要求两个运行时前提Python 3.11应用使用较新的类型注解语法requires-python约束为3.11,3.14UVPython 包与虚拟环境管理工具当前仓库推荐使用。强烈建议始终使用虚拟环境uv venv --python 3.11 source .venv/bin/activate依赖清单依赖声明在 unified-search-app/pyproject.toml依赖版本用途streamlit1.43.0Web 应用框架graphrag2.5.0调用四种检索 API 与配置解析azure-search-documents~11.4Azure AI Search向量检索azure-storage-blob~12.20Azure Blob 读取数据集azure-identity~1.16Azure 身份认证altair~5.3图表渲染streamlit-agraph~0.0.45图谱可视化st-tabs~0.1TabBar 标签页组件spacy~3.8NLP 处理开发依赖optionaldev包含 poethepoet任务运行器版本 ~0.26、ipykernel、pyright、ruff。安装全部依赖只需在 unified-search-app 目录下执行uv sync前置条件先用 GraphRAG 建立索引Unified Search 本身不负责索引它读取的是 GraphRAG indexing 管线产出的图谱数据。因此在跑本应用前必须先对目标文档集执行 GraphRAG 索引得到至少包含下列内容的索引目录settings.yaml该数据集使用的 GraphRAG 配置.env可选若环境变量在别处声明可省略output/索引输出目录Unified Search 通过 app/data_config.py 中的常量读取其中 6 张表output/communities、output/community_reports、output/entities、output/relationships、output/covariates、output/text_unitsprompts/该数据集使用到的提示词模板。从 app/knowledge_loader/model.py 的KnowledgeModel数据类可看到这 6 类索引产物entities、relationships、community_reports、communities、text_units、covariates会被整体加载为 DataFrame作为api.*_search编排函数的输入。若尚未了解索引流程建议先参照仓库docs目录下的入门指引完成一次最小索引例如 docs/index/inputs.md 描述的支持输入格式与 docs/config/overview.md 描述的整体配置结构。多数据集注册listing.json 规范Unified Search 的核心设计是同时挂载多个 GraphRAG 索引数据集而入口就是一个「目录清单文件」listing.json。把该文件放在存放所有数据集的根目录中本地目录或 Blob 存储均可每个数据集对应一条记录[{ key: key_to_identify_dataset_1, path: path_to_dataset_1, name: name_to_identify_dataset_1, description: description_for_dataset_1, community_level: integer for community level you want to filter },{ key: key_to_identify_dataset_2, path: path_to_dataset_2, name: name_to_identify_dataset_2, description: description_for_dataset_2, community_level: integer for community level you want to filter }]README 给出的实际示例是在名为projects的目录中存放按入门指引建立的索引则projects/listing.json可写成[{ key: christmas-demo, path: christmas, name: A Christmas Carol, description: Getting Started index of the novel A Christmas Carol, community_level: 2 }]各字段含义可由 app/knowledge_loader/data_sources/typing.py 的DatasetConfigdataclass 确认如下字段类型说明keystr数据集的唯一标识用于侧边栏下拉框与 URL?dataset参数匹配pathstr数据集在数据根目录下的子目录或 Blob 中的相对路径namestr展示给用户的可读名称descriptionstr数据集描述展示在右侧面板顶部community_levelint检索时使用的社区层级过滤整数会被透传给底层api.*_search调用的community_level参数在 app/app_logic.py 的load_dataset()中应用会从当前选中条目的path构造数据源、读取其settings.yaml再据此装载 6 类知识模型数据。数据集目录结构约定projects根目录的期望布局如下projects_folder ├── listing.json ├── dataset_1 │ ├── settings.yaml │ ├── .env # 可选若环境变量在其他地方声明可省略 │ ├── output │ └── prompts ├── dataset_2 │ ├── settings.yaml │ ├── .env # 可选 │ ├── output │ └── prompts └── ...两点约定需要特别注意每个数据集目录内的其他任何文件夹都会被忽略不会影响应用运行只有listing.json中显式声明的数据集才会被 Unified Search 使用。也就是说listing.json相当于一份「白名单」即便数据根目录下放了很多索引也只在清单内切换。数据承载方式本地目录与 Azure Blob 二选一1. 本地数据目录把数据与配置按上述结构放到本地文件夹后用绝对路径通过环境变量告知应用DATA_ROOT data_folder_absolute_pathapp/knowledge_loader/data_sources/default.py 显示该变量通过os.getenv(DATA_ROOT)读取作为本地数据源的根路径。2. Azure Blob Storage如果希望数据集托管在云端创建 Blob 存储账户建一个data容器把所有数据与配置按上述结构上传执行az login并选择一个对该存储拥有读权限的账户应用通过azure-identity完成认证通过环境变量告知应用存储账户名BLOB_ACCOUNT_NAME blob_storage_name4.可选容器名默认是data若想换其他容器则设置BLOB_CONTAINER_NAME blob_container_with_projects关键机制default.py中blob_container_name取BLOB_CONTAINER_NAME缺省回退到默认容器名data。数据源工厂 app/knowledge_loader/data_sources/loader.py 的create_datasource()会根据BLOB_ACCOUNT_NAME是否被设置来决定使用BlobDatasource还是LocalDatasource而default.py会在两个环境变量都未设置时直接抛出ValueErrorEither DATA_ROOT or BLOB_ACCOUNT_NAME environment variable must be set.—— 也就是说本地与 Blob 两条路径必须选其一无法两者都不配。启动应用在 unified-search-app 目录下依次执行uv sync uv run poe startpoe任务是定义在 unified-search-app/pyproject.toml 中[tool.poe.tasks]段的快捷命令任务等价命令用途startstreamlit run app/home_page.py本地默认启动localhoststart_prodstreamlit run app/home_page.py --server.port8501 --server.address0.0.0.0监听所有网卡、对外可访问如需容器化部署仓库已附带 unified-search-app/Dockerfile基于 Python 3.11 镜像安装 uv执行uv sync --no-install-project暴露 8501 端口并以uv run poe start_prod作为入口命令。启动时应用会通过initialize()读取listing.json见 app/app_logic.py并优先用 URL 中的?datasetkey查询参数选择数据集可通过 URL 直接定位某个数据集否则回退到清单中的第一条。界面使用指南运行应用后会看到两大主面板。左侧Configuration 配置面板配置面板提供若干可折叠选项Datasets数据集下拉框列出listing.json中声明的全部数据集切换时会清空缓存并重新加载新数据集的知识模型见update_dataset()Number of suggested questions建议问题数量控制每次生成多少条建议问题。对应的默认值定义在 unified-search-app/app/data_config.py 的default_suggested_questions 5侧边栏控件app/ui/sidebar.py将其限制在 1 到 100 之间的整数Search options检索选项以开关形式勾选要参与对比的检索至少要开启一个。Basic RAG 与 Drift Search 默认关闭Local 与 Global 默认开启。右侧Searches 检索面板右侧面板提供以下功能区域顶部展示当前数据集的通用信息名称与描述即listing.json中的name与description数据集信息下方是Suggest some questions建议一些问题按钮它用 Global Search 对数据集进行分析并生成左侧配置面板设定数量的问题。点击后生成的每条问题左侧有复选框勾选即选中该问题作为检索输入见questions_listUI文本输入框Ask a question to compare the results输入要发往各检索算法的问题页面主体是两个标签页Search与Community ExplorerSearch并排展示所有开启的检索结果及其引用来源citationsCommunity Explorer分为上下/左右两个区域——Community Reports List社区报告列表与 Selected Report选中报告的详情。生成问题与并发检索的实际调用链可在 unified-search-app/app/app_logic.py 中看到run_generate_questions()调用api.global_search并显式开启dynamic_community_selectionTrue、response_typeSingle paragraph同时在 query 中拼入top N most important questions的指令之后由前端把返回的编号列表解析成可勾选问题run_all_searches()把开启的检索封装为异步任务用asyncio.gather并发执行之后把每种检索的响应与上下文统一放进st.session_state[response_lengths]由display_citations()在各自列下渲染引用。各检索背后的 GraphRAG API 与差异四种检索在源码中分别对应四个异步包装函数它们都调用 packages/graphrag/graphrag/api 暴露的编排 API并以community_level来自listing.json作为共同的社区层级参数检索底层 API传入的主要知识模型回答上下文来源Basic RAGapi.basic_search仅text_units固定数量的原始文档文本块Local Searchapi.local_searchcommunities、entities、community_reports、text_units、relationships、covariates图谱索引查询结果 相关文本块Global Searchapi.global_searchentities、communities、community_reports覆盖全部输入文档的 AI 生成社区报告Drift Searchapi.drift_searchentities、communities、community_reports、text_units、relationships社区信息引导的多轮发散检索以 Local Search 为例run_local_search()它同时把实体、关系、社区、社区报告、文本单元甚至协变量如存在传给api.local_search返回的(response, context_data)会一并存入SearchResult其类型定义见 app/rag/typing.pysearch_typeresponsecontextresponse 渲染到答案列context 用于渲染引用。Global Search 同样会返回context_data字典页面据此展示支撑该答案的社区/实体证据。从代码可推断该演示的核心目的不是让四种算法「比赛」而是展示不同算法在上下文来源、回答口径与引用对象上的本质差异因此前端刻意在每列标题下标注了各自的上下文构成说明。知识模型装载与缓存机制索引产物以 parquet 表的形式存放在output/下读取流程分两层均有 7 天 TTL 的 Streamlit 缓存default_ttl 60 * 60 * 24 * 7见 app/data_config.pyapp/knowledge_loader/data_prep.py用datasource.read()读取各张表并打印记录数app/knowledge_loader/model.py封装为load_entities、load_entity_relationships、load_covariates、load_community_reports、load_communities、load_text_units六个带缓存的加载函数统一装进KnowledgeModel。load_knowledge_model()会把上述对象一次性写入 Streamlit 会话变量sv.entities、sv.relationships等。当用户在侧边栏切换数据集或点击 Reset 时会调用st.cache_data.clear()清空 7 天缓存以加载新数据点击 Reset 还会重置已生成问题、已选问题并恢复文本输入框见 app/home_page.py 的on_click_reset。经验提示由于装载过程会按表读取并缓存若数据集较大首次切换数据集时会有可感知的加载延迟属正常现象重复访问同数据集时会被 7 天 TTL 的缓存命中而明显加速。常见问题与使用要点环境变量缺失即无法启动DATA_ROOT本地与BLOB_ACCOUNT_NAMEBlob必须至少设置一个否则应用在导入数据源模块时直接抛错问题建议依赖 Global Search 背后的 LLM 调用Suggest some questions本质是一次全局检索式的生成任务会消耗模型额度并受settings.yaml中模型与community_level配置影响至少开启一种检索若关闭全部四个开关Search 页只会提示选择检索选项而不会返回任何内容数据集数量较大时注意 token 限制data_config.py中注释建议按所用 LLM 的上下文窗口调整default_suggested_questions默认 5例如面向 gpt-4-turbo 一类大窗口模型可酌情增大该应用仅供演示与实验README 明确其为非受支持维护状态若用于生产环境请自行评估稳定性与安全边界。通过以上步骤你即可用一套数据集同时观察 GraphRAG 四种检索策略对同一问题的回答差异并把应用接入本地目录或 Azure Blob 上的多套索引作为评估 GraphRAG 查询效果的对照实验台。【免费下载链接】graphragA modular graph-based Retrieval-Augmented Generation (RAG) system项目地址: https://gitcode.com/GitHub_Trending/gr/graphrag创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考