GPT Researcher 本地文档研究指南基于 DOC_PATH 的 Local 与 Hybrid 检索模式实战【免费下载链接】gpt-researcherAn autonomous agent that conducts deep research on any data using any LLM providers项目地址: https://gitcode.com/GitHub_Trending/gp/gpt-researcher本篇技术指南聚焦 gpt-researcher 的「本地文档研究」能力如何让自主研究 Agent 以本地文件夹中的 PDF、Word、Excel、Markdown 等文档为数据源执行研究任务并通过report_source在 Local仅本地与 Hybrid本地 Web模式之间切换。读完本文你将掌握DOC_PATH配置、前端 My Documents 选项、Python 包级调用方式以及本地文档在源码层的加载、向量化与检索链路可直接落地到私有知识库与联网研究相结合的实战场景。一、本地文档研究概览gpt-researcher 默认以 Web 为研究来源但通过设置DOC_PATH并切换数据源可以让 Agent 完全基于你的本地文档执行研究任务。官方文档local-docs.md明确列出了当前支持的文档格式PDF纯文本txtCSVExcelxls / xlsxMarkdownmdPowerPointpptxWorddoc / docx在源码层这些格式的解析统一由 DocumentLoader 完成。它基于 LangChain 社区加载器通过扩展名分发到对应的解析器文件扩展名加载器说明pdfPyMuPDFLoader基于 PyMuPDF 的 PDF 解析txtTextLoader纯文本csvUnstructuredCSVLoadermodeelements结构化行级加载xls/xlsxUnstructuredExcelLoadermodeelementsExcel 工作表mdUnstructuredMarkdownLoaderMarkdownpptxUnstructuredPowerPointLoaderPowerPointdoc/docxUnstructuredWordDocumentLoaderWord 文档html/htmBSHTMLLoader额外支持的网页文件DocumentLoader.load()会递归遍历DOC_PATH指向的目录os.walk对每个文件按扩展名选择加载器最后把非空的page_content组装成{raw_content: ..., url: 文件名}结构的文档列表document.py#L32-L62。若目录中没有任何可解析内容会抛出 Failed to load any documents!异常提示。二、快速上手仅本地文档研究Local 模式原文档给出两步操作法下面结合仓库现状给出完整可运行版本。Step 1设置 DOC_PATH 环境变量DOC_PATH指向存放文档的文件夹是本地模式的唯一必配项。配置文件与默认值定义在config/variables/default.py默认值为./my-docsconfig/variables/base.py声明DOC_PATH: str字段config/config.py#L148-L155_set_doc_path()读取环境变量并在validate_doc_path()校验失败时回退到默认值export DOC_PATH./my-docs校验失败的场景包括路径不存在等情况此时会在终端打印Warning: Error validating doc_path ... Using default doc_path.并回退到./my-docs。因此建议在运行前确认目录真实存在且包含受支持格式的文件。测试配置 config/variables/test_local.json 中给出的示例值为DOC_PATH: tests/docs可作为参照。Step 2a前端方式localhost:8000如果你运行的是内置前端应用后端默认localhost:8000在界面中找到Report Source下拉框选择My Documents即可。该选项在前端组件 ResearchForm.tsx#L135-L145 中实现其 HTML 结构为option valuelocalMy Documents/option选中的值会以report_source字段随研究请求发送给后端见 app/page.tsx#L486最终传入GPTResearcher实例。Step 2bPython 包方式pip / 源码调用使用 Python 调用时实例化GPTResearcher类并传入report_sourcelocal。构造函数的完整签名与参数说明见 agent.py#L53-L137from gpt_researcher import GPTResearcher from gpt_researcher.utils.enum import ReportSource query 根据我的产品文档总结 VLX500 的关键规格 researcher GPTResearcher( queryquery, report_sourceReportSource.Local.value, # 等价于 local ) await researcher.conduct_research() report await researcher.write_report()report_source的取值由 utils/enum.py#L30-L51 的ReportSource枚举统一定义web、local、azure、langchain_documents、langchain_vectorstore、static、hybrid。若实例化时未传report_source则会回退到配置中的report_sourceagent.py#L143。仓库测试 tests/vector-store.py#L209 中即有report_sourcelocal的调用示例可参考其组合vector_store的写法。三、本地模式的源码执行链路了解界面与参数后再看本地模式在后端如何被真正执行。研究流程由 ResearchConductor.conduct_research() 编排其中report_source ReportSource.Local.value的分支实现为researcher.py#L164-L171elif self.researcher.report_source ReportSource.Local.value: self.logger.info(Using local search) document_data await DocumentLoader(self.researcher.cfg.doc_path).load() self.logger.info(fLoaded {len(document_data)} documents) if self.researcher.vector_store: self.researcher.vector_store.load(document_data) research_data await self._get_context_by_web_search( self.researcher.query, document_data, self.researcher.query_domains )整个链路可以拆解为三个阶段加载DocumentLoader(cfg.doc_path).load()递归读取目录并解析全部文档。可选向量化若传入了vector_store文档会被包装为 LangChain Document再按chunk_size1000、chunk_overlap200切块后写入向量库见 vector_store/vector_store.py#L17-L57供后续相似度检索复用。上下文构建_get_context_by_web_search()先基于原始问题规划子查询plan_research再对每个子查询调用_process_sub_query—— 此时传入的scraped_data即本地文档内容Agent 不再执行联网搜索而是直接在这批文档上做相关性检索与压缩researcher.py#L596-L602。值得注意的是在 Local 模式下Agent 规划子查询阶段仍然可能调用检索器进行初步搜索以辅助规划plan_research使用self.researcher.retrievers[0]但最终研究上下文完全来自本地文档。若配置了curate_sources收集到的上下文还会经过 source curator 去重整理researcher.py#L211-L227。四、Local WebHybrid 混合研究模式在仅本地文档之外gpt-researcher 还支持将本地文档与 Web 研究结合形成 Hybrid 混合模式即report_sourcehybrid。它同样从DOC_PATH加载本地文档但会同时执行本地文档检索与 Web 搜索最后把两路上下文合并交给 LLM 生成报告。对应源码分支见 researcher.py#L172-L186elif self.researcher.report_source ReportSource.Hybrid.value: if self.researcher.document_urls: document_data await OnlineDocumentLoader(self.researcher.document_urls).load() else: document_data await DocumentLoader(self.researcher.cfg.doc_path).load() if self.researcher.vector_store: self.researcher.vector_store.load(document_data) # 本地文档通道与 Web 通道相互独立并发执行 # visited_urls 仍在两路之间做去重。 docs_context, web_context await asyncio.gather( self._get_context_by_web_search(self.researcher.query, document_data, self.researcher.query_domains), self._get_context_by_web_search(self.researcher.query, [], self.researcher.query_domains), ) research_data self.researcher.prompt_family.join_local_web_documents(docs_context, web_context)从实现细节可以总结出 Hybrid 模式的几个关键点数据源二选一优先使用document_urls在线文档未提供时回退到DOC_PATH本地文档。因此即使文档全部在本地也无需额外配置。并发执行本地文档通道与 Web 搜索通道通过asyncio.gather并发运行互不阻塞同时visited_urls集合会在两路之间共享去重避免对同一 URL 重复抓取。上下文合并两路结果由prompt_family.join_local_web_documents()合并。默认 prompt 家族PromptFamily.Default负责组织合并后的上下文顺序而不同模型家族的提示模板可能对合并方式有不同实现枚举定义见 utils/enum.py#L94-L103。Hybrid 模式适合以私有文档为主、以公开网络资料为辅的场景例如企业内部知识库 行业公开报告的交叉验证。关于混合研究的设计思路仓库内的官方博客文章《Hybrid Research》有更深入的背景说明见 docs/blog/2024-09-7-hybrid-research/index.md。五、参数速查与注意事项参数取值说明DOC_PATH本地目录路径如./my-docs文档根目录默认./my-docs校验失败时回退默认值report_sourceweb/local/hybrid/azure等数据来源ReportSource枚举定义于 utils/enum.pyvector_storeLangChain VectorStore 实例可选传入后文档会切块1000/200并写入向量库前端选项My Documents对应report_sourcelocal见 ResearchForm.tsx实践中有几点需要留意目录递归DocumentLoader使用os.walk递归遍历子目录中的文档也会被加载适合按主题组织文件夹。格式依赖CSV/Excel/Word/PPT 依赖unstructured相关加载器首次使用前请确认已按 requirements.txt 安装完整依赖。空目录防护目录内没有任何可解析文档时加载阶段会直接抛出异常终止任务务必先自检DOC_PATH内容。文件引用名加载后的每条文档以basename文件名作为来源标识报告中会以此作为本地来源的引用标注document.py#L54-L57。六、小结通过本文你已掌握 gpt-researcher 本地文档研究的完整路径设置DOC_PATH→ 选择report_sourcelocal前端选 My Documents即可让 Agent 基于私有文档生成报告切换为hybrid则叠加 Web 检索实现本地为主、网络为辅的混合研究。更进一步从 DocumentLoader 的格式分发、ResearchConductor 的分支编排到asyncio.gather的并发合并你可以清楚地看到本地文档是如何被解析、向量化、检索并最终汇入上下文的——这为二次开发如接入新的文档格式或自定义合并策略提供了明确的切入点。【免费下载链接】gpt-researcherAn autonomous agent that conducts deep research on any data using any LLM providers项目地址: https://gitcode.com/GitHub_Trending/gp/gpt-researcher创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
GPT Researcher 本地文档研究指南：基于 DOC_PATH 的 Local 与 Hybrid 检索模式实战
GPT Researcher 本地文档研究指南基于 DOC_PATH 的 Local 与 Hybrid 检索模式实战【免费下载链接】gpt-researcherAn autonomous agent that conducts deep research on any data using any LLM providers项目地址: https://gitcode.com/GitHub_Trending/gp/gpt-researcher本篇技术指南聚焦 gpt-researcher 的「本地文档研究」能力如何让自主研究 Agent 以本地文件夹中的 PDF、Word、Excel、Markdown 等文档为数据源执行研究任务并通过report_source在 Local仅本地与 Hybrid本地 Web模式之间切换。读完本文你将掌握DOC_PATH配置、前端 My Documents 选项、Python 包级调用方式以及本地文档在源码层的加载、向量化与检索链路可直接落地到私有知识库与联网研究相结合的实战场景。一、本地文档研究概览gpt-researcher 默认以 Web 为研究来源但通过设置DOC_PATH并切换数据源可以让 Agent 完全基于你的本地文档执行研究任务。官方文档local-docs.md明确列出了当前支持的文档格式PDF纯文本txtCSVExcelxls / xlsxMarkdownmdPowerPointpptxWorddoc / docx在源码层这些格式的解析统一由 DocumentLoader 完成。它基于 LangChain 社区加载器通过扩展名分发到对应的解析器文件扩展名加载器说明pdfPyMuPDFLoader基于 PyMuPDF 的 PDF 解析txtTextLoader纯文本csvUnstructuredCSVLoadermodeelements结构化行级加载xls/xlsxUnstructuredExcelLoadermodeelementsExcel 工作表mdUnstructuredMarkdownLoaderMarkdownpptxUnstructuredPowerPointLoaderPowerPointdoc/docxUnstructuredWordDocumentLoaderWord 文档html/htmBSHTMLLoader额外支持的网页文件DocumentLoader.load()会递归遍历DOC_PATH指向的目录os.walk对每个文件按扩展名选择加载器最后把非空的page_content组装成{raw_content: ..., url: 文件名}结构的文档列表document.py#L32-L62。若目录中没有任何可解析内容会抛出 Failed to load any documents!异常提示。二、快速上手仅本地文档研究Local 模式原文档给出两步操作法下面结合仓库现状给出完整可运行版本。Step 1设置 DOC_PATH 环境变量DOC_PATH指向存放文档的文件夹是本地模式的唯一必配项。配置文件与默认值定义在config/variables/default.py默认值为./my-docsconfig/variables/base.py声明DOC_PATH: str字段config/config.py#L148-L155_set_doc_path()读取环境变量并在validate_doc_path()校验失败时回退到默认值export DOC_PATH./my-docs校验失败的场景包括路径不存在等情况此时会在终端打印Warning: Error validating doc_path ... Using default doc_path.并回退到./my-docs。因此建议在运行前确认目录真实存在且包含受支持格式的文件。测试配置 config/variables/test_local.json 中给出的示例值为DOC_PATH: tests/docs可作为参照。Step 2a前端方式localhost:8000如果你运行的是内置前端应用后端默认localhost:8000在界面中找到Report Source下拉框选择My Documents即可。该选项在前端组件 ResearchForm.tsx#L135-L145 中实现其 HTML 结构为option valuelocalMy Documents/option选中的值会以report_source字段随研究请求发送给后端见 app/page.tsx#L486最终传入GPTResearcher实例。Step 2bPython 包方式pip / 源码调用使用 Python 调用时实例化GPTResearcher类并传入report_sourcelocal。构造函数的完整签名与参数说明见 agent.py#L53-L137from gpt_researcher import GPTResearcher from gpt_researcher.utils.enum import ReportSource query 根据我的产品文档总结 VLX500 的关键规格 researcher GPTResearcher( queryquery, report_sourceReportSource.Local.value, # 等价于 local ) await researcher.conduct_research() report await researcher.write_report()report_source的取值由 utils/enum.py#L30-L51 的ReportSource枚举统一定义web、local、azure、langchain_documents、langchain_vectorstore、static、hybrid。若实例化时未传report_source则会回退到配置中的report_sourceagent.py#L143。仓库测试 tests/vector-store.py#L209 中即有report_sourcelocal的调用示例可参考其组合vector_store的写法。三、本地模式的源码执行链路了解界面与参数后再看本地模式在后端如何被真正执行。研究流程由 ResearchConductor.conduct_research() 编排其中report_source ReportSource.Local.value的分支实现为researcher.py#L164-L171elif self.researcher.report_source ReportSource.Local.value: self.logger.info(Using local search) document_data await DocumentLoader(self.researcher.cfg.doc_path).load() self.logger.info(fLoaded {len(document_data)} documents) if self.researcher.vector_store: self.researcher.vector_store.load(document_data) research_data await self._get_context_by_web_search( self.researcher.query, document_data, self.researcher.query_domains )整个链路可以拆解为三个阶段加载DocumentLoader(cfg.doc_path).load()递归读取目录并解析全部文档。可选向量化若传入了vector_store文档会被包装为 LangChain Document再按chunk_size1000、chunk_overlap200切块后写入向量库见 vector_store/vector_store.py#L17-L57供后续相似度检索复用。上下文构建_get_context_by_web_search()先基于原始问题规划子查询plan_research再对每个子查询调用_process_sub_query—— 此时传入的scraped_data即本地文档内容Agent 不再执行联网搜索而是直接在这批文档上做相关性检索与压缩researcher.py#L596-L602。值得注意的是在 Local 模式下Agent 规划子查询阶段仍然可能调用检索器进行初步搜索以辅助规划plan_research使用self.researcher.retrievers[0]但最终研究上下文完全来自本地文档。若配置了curate_sources收集到的上下文还会经过 source curator 去重整理researcher.py#L211-L227。四、Local WebHybrid 混合研究模式在仅本地文档之外gpt-researcher 还支持将本地文档与 Web 研究结合形成 Hybrid 混合模式即report_sourcehybrid。它同样从DOC_PATH加载本地文档但会同时执行本地文档检索与 Web 搜索最后把两路上下文合并交给 LLM 生成报告。对应源码分支见 researcher.py#L172-L186elif self.researcher.report_source ReportSource.Hybrid.value: if self.researcher.document_urls: document_data await OnlineDocumentLoader(self.researcher.document_urls).load() else: document_data await DocumentLoader(self.researcher.cfg.doc_path).load() if self.researcher.vector_store: self.researcher.vector_store.load(document_data) # 本地文档通道与 Web 通道相互独立并发执行 # visited_urls 仍在两路之间做去重。 docs_context, web_context await asyncio.gather( self._get_context_by_web_search(self.researcher.query, document_data, self.researcher.query_domains), self._get_context_by_web_search(self.researcher.query, [], self.researcher.query_domains), ) research_data self.researcher.prompt_family.join_local_web_documents(docs_context, web_context)从实现细节可以总结出 Hybrid 模式的几个关键点数据源二选一优先使用document_urls在线文档未提供时回退到DOC_PATH本地文档。因此即使文档全部在本地也无需额外配置。并发执行本地文档通道与 Web 搜索通道通过asyncio.gather并发运行互不阻塞同时visited_urls集合会在两路之间共享去重避免对同一 URL 重复抓取。上下文合并两路结果由prompt_family.join_local_web_documents()合并。默认 prompt 家族PromptFamily.Default负责组织合并后的上下文顺序而不同模型家族的提示模板可能对合并方式有不同实现枚举定义见 utils/enum.py#L94-L103。Hybrid 模式适合以私有文档为主、以公开网络资料为辅的场景例如企业内部知识库 行业公开报告的交叉验证。关于混合研究的设计思路仓库内的官方博客文章《Hybrid Research》有更深入的背景说明见 docs/blog/2024-09-7-hybrid-research/index.md。五、参数速查与注意事项参数取值说明DOC_PATH本地目录路径如./my-docs文档根目录默认./my-docs校验失败时回退默认值report_sourceweb/local/hybrid/azure等数据来源ReportSource枚举定义于 utils/enum.pyvector_storeLangChain VectorStore 实例可选传入后文档会切块1000/200并写入向量库前端选项My Documents对应report_sourcelocal见 ResearchForm.tsx实践中有几点需要留意目录递归DocumentLoader使用os.walk递归遍历子目录中的文档也会被加载适合按主题组织文件夹。格式依赖CSV/Excel/Word/PPT 依赖unstructured相关加载器首次使用前请确认已按 requirements.txt 安装完整依赖。空目录防护目录内没有任何可解析文档时加载阶段会直接抛出异常终止任务务必先自检DOC_PATH内容。文件引用名加载后的每条文档以basename文件名作为来源标识报告中会以此作为本地来源的引用标注document.py#L54-L57。六、小结通过本文你已掌握 gpt-researcher 本地文档研究的完整路径设置DOC_PATH→ 选择report_sourcelocal前端选 My Documents即可让 Agent 基于私有文档生成报告切换为hybrid则叠加 Web 检索实现本地为主、网络为辅的混合研究。更进一步从 DocumentLoader 的格式分发、ResearchConductor 的分支编排到asyncio.gather的并发合并你可以清楚地看到本地文档是如何被解析、向量化、检索并最终汇入上下文的——这为二次开发如接入新的文档格式或自定义合并策略提供了明确的切入点。【免费下载链接】gpt-researcherAn autonomous agent that conducts deep research on any data using any LLM providers项目地址: https://gitcode.com/GitHub_Trending/gp/gpt-researcher创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
