GPT Researcher 配置完全指南config.py、config.json 与环境变量的三级配置体系【免费下载链接】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 的配置体系从 config.py 与 default.py 中的默认配置、外部config.json的完整字段解析到.env/ 环境变量的覆盖机制与 Deep Research 深度参数调优。读完本文你将掌握检索器Retriever、三档 LLMFAST/SMART/STRATEGIC、Embedding、Token 上限、报告格式等全部核心配置项的取值与底层实现原理能够按自己的 LLM 提供商、检索服务与报告需求定制一次研究任务。GPT Researcher 是一个面向任意数据源的自主研究 Agent其最大的灵活性来源就是配置层通过一个 JSON 文件或几行环境变量就能切换搜索引擎、LLM 提供商、报告格式、研究深度与输出语言而不需要改动任何业务代码。本指南以官方配置文档 config.md 为主线逐项拆解所有配置参数并结合仓库源码说明它们是如何被解析、校验与生效的。配置体系总览三种配置来源与优先级配置入口位于仓库 gpt_researcher/config/ 目录config.pyConfig类负责加载、合并、类型转换与校验所有配置variables/default.pyDEFAULT_CONFIG字典内置全部键的默认值variables/base.pyBaseConfigTypedDict声明每个键的类型约束bool、int、float、str、dict、list等variables/test_local.json内置的可选 JSON 配置示例。配置的来源有三个层级从 load_config 的实现可以清晰看到合并逻辑内置默认值未做任何配置时直接使用DEFAULT_CONFIG外部 JSON 文件通过config_path参数或在CONFIG_PATH环境变量指定load_config会先拷贝DEFAULT_CONFIG再用自定义 JSON 逐键覆盖——因此你不必写全所有键缺失的键自动回落为默认值环境变量在_set_attributesconfig.py中任何环境变量只要键名匹配如RETRIEVER、SMART_LLM就会覆盖 JSON 与默认值优先级最高。对应到源码这套优先级正是环境变量 自定义 config.json 内置默认值。需要注意默认值字典本身也在持续演进例如本文写作时 default.py 中三档 Token 上限已是FAST_TOKEN_LIMIT6000、SMART_TOKEN_LIMIT12000、STRATEGIC_TOKEN_LIMIT8000与部分旧文档记录的 3000/6000/4000 不同——务必以当前仓库的实际默认值为准。快速上手用 config.json 定制一次研究官方文档推荐的方式是编写一个外部config.json通过config_path参数注入。仓库中提供了一份完整的字段范本核心内容如下以下为官方示例格式其中 Token 上限可按你的模型输出能力调整{ RETRIEVER: tavily, EMBEDDING: openai:text-embedding-3-small, SIMILARITY_THRESHOLD: 0.42, FAST_LLM: openai:gpt-5.4-mini, SMART_LLM: openai:gpt-5.4, STRATEGIC_LLM: openai:gpt-5.4, LANGUAGE: english, CURATE_SOURCES: false, FAST_TOKEN_LIMIT: 3000, SMART_TOKEN_LIMIT: 6000, STRATEGIC_TOKEN_LIMIT: 4000, BROWSE_CHUNK_MAX_LENGTH: 8192, SUMMARY_TOKEN_LIMIT: 700, TEMPERATURE: 0.4, DOC_PATH: ./my-docs, REPORT_SOURCE: web }该 JSON 的键必须与默认配置的键一一对应大小写敏感。官方文档给出的启动方式为python gpt_researcher/main.py --config_path my_config.json关于当前仓库的实际入口随着项目演进主入口已迁移。当前仓库根目录的 main.py 用于启动后端服务uvicornCLI 方式生成报告使用 cli.py如python cli.py query --report_type detailed_report。无论哪种入口config_path最终都会在 gpt_researcher/agent.py 处通过self.cfg Config(config_path)构造配置对象。若你的自定义 JSON 不在当前目录也可改用环境变量注入路径export CONFIG_PATH/path/to/my_config.jsonload_config对路径做了容错文件不存在时打印警告并回落默认配置如果传入的路径没有.json后缀还会提示是否遗漏了扩展名。核心配置项详解以下逐项说明官方文档列出的配置参数并补充当前仓库 default.py 中的实际默认值。检索与数据源配置项默认值说明RETRIEVERtavily研究检索器支持多值组合见下文EMBEDDINGopenai:text-embedding-3-small嵌入模型格式为provider:modelSIMILARITY_THRESHOLD0.42文档处理时的相似度阈值REPORT_SOURCEweb报告数据来源web联网研究或doc本地文档研究DOC_PATH./my-docsREPORT_SOURCEdoc时本地文档所在目录BROWSE_CHUNK_MAX_LENGTH8192抓取网页内容时单块文本的最大长度MAX_SEARCH_RESULTS_PER_QUERY5每次查询返回的最大搜索结果数CURATE_SOURCESFalse是否对来源做二次精选开启会额外消耗一次 LLM 调用增加耗时与成本但可提升来源质量MAX_SUBTOPICS3生成子主题的最大数量SCRAPERbs网页抓取器默认 BeautifulSoup也可用newspaperMAX_SCRAPER_WORKERS15单次研究的并发抓取工作线程数SCRAPER_RATE_LIMIT_DELAY0.0抓取请求的最小间隔秒数0表示不限速可用于规避 API 限流Retriever 多值组合RETRIEVER支持用逗号组合多个检索器例如学术文献综述场景推荐export RETRIEVERtavily,openalex,semantic_scholar从 retrievers/utils.py 的VALID_RETRIEVERS列表看当前仓库支持的检索器包括tavily、duckduckgo、bing、brave、google、searchapi、serper、serpapi、searx、arxiv、openalex、semantic_scholar、pubmed_central、exa、crw、groundroute、bocha、getxapi、xquik、custom、mcp、mock等具体实现位于 gpt_researcher/retrievers/ 目录每个子目录对应一个检索器如 tavily_search.py、bing.py。组合检索器时需要为每个检索服务配置对应的 API Key 等环境变量缺少时会看到控制台日志提示。注意切换非默认检索器非 Tavily时文档明确提醒需要额外导出对应 API Key 等环境变量并留意控制台日志的引导信息。LLM 与生成参数配置项默认值说明FAST_LLMopenai:gpt-5.4-mini快速 LLM用于摘要等轻量操作SMART_LLMopenai:gpt-5.4智能 LLM用于研究报告生成与推理STRATEGIC_LLMopenai:gpt-5.4战略 LLM用于研究计划与策略生成FAST_TOKEN_LIMIT6000快速 LLM 响应的 Token 上限SMART_TOKEN_LIMIT12000智能 LLM 响应的 Token 上限STRATEGIC_TOKEN_LIMIT8000战略 LLM 响应的 Token 上限SUMMARY_TOKEN_LIMIT700摘要生成的 Token 上限TEMPERATURE0.4采样温度范围通常 0~1越高越随机有创造性越低越聚焦确定REASONING_EFFORTmedium战略模型的推理力度可选high/medium/lowTOTAL_WORDS1200文档生成的总字数目标REPORT_FORMATAPA报告引用格式可换MLA、CMS、Harvard style、IEEE等MAX_ITERATIONS3查询扩展或搜索精化的最大迭代次数AGENT_ROLENone研究 Agent 角色设置后启用针对特定领域的角色化提示词与技术LANGUAGEenglish最终报告使用的语言USER_AGENT浏览器 UA 字符串网页爬取与请求使用的自定义 User-AgentMEMORY_BACKENDlocal记忆后端用于临时数据的本地存储PROMPT_FAMILYdefault提示词家族见 enum.py 中的PromptFamilyLLM_KWARGS{}传给 LLM Provider 的附加关键字参数JSON 格式常用于 Ollama 的num_ctx等参数EMBEDDING_KWARGS{}传给 Embedding Provider 的附加关键字参数JSON 格式VERBOSEFalse是否输出详细日志关于三档 LLM 的分工FAST_LLM处理摘要等高频低开销任务SMART_LLM承担报告正文生成与推理STRATEGIC_LLM负责研究计划与策略制定。它们的格式统一为provider:model由 parse_llm 解析为(llm_provider, llm_model)元组provider 必须在 llm_provider/generic/base.py 的_SUPPORTED_PROVIDERS中——当前支持openai、anthropic、azure_openai、cohere、google_vertexai、google_genai、fireworks、ollama、together、mistralai、huggingface、groq、bedrock、dashscope、xai、deepseek、litellm、gigachat、openrouter、vllm_openai、aimlapi、netmind、forge、avian、minimax、atlascloud、nebius等。若写错格式缺少冒号会抛出提示信息要求按openai:gpt-4o-mini这类格式设置。现代长输出模型的 Token 上限推荐官方文档特别指出默认 Token 上限是按 GPT-4o 级别模型16k 最大输出校准的。对于输出能力更强的模型需要按比例上调否则报告可能被截断模型家族最大输出推荐的 SMART_TOKEN_LIMITGPT-4o / GPT-4.116k8000Claude Haiku 4.564k16000Claude Sonnet 4.664k16000Claude Opus 4.7128k32000GPT-5 家族128k32000FAST_TOKEN_LIMIT与STRATEGIC_TOKEN_LIMIT可按比例同步调整。硬性上限为200k作为防误写的合理性护栏。当前默认的 GPT-5 系列gpt-5.4/gpt-5.4-mini本身就属于大输出模型因此 default.py 已把默认值上调为 6000/12000/8000且注释说明这些值映射到max_completion_tokens需同时覆盖推理 Token。温度与推理力度TEMPERATURE0.4是通用默认值。但需要注意部分推理模型如deepseek/deepseek-reasoner、OpenAI o 系列、GPT-5 家族、Claude 4.x 家族不支持自定义温度见 base.py 的NO_SUPPORT_TEMPERATURE_MODELS列表——对这类模型温度参数会被忽略。REASONING_EFFORT是战略模型的推理力度开关枚举定义于 ReasoningEffortshigh/medium/low默认medium。它只对支持推理力度的模型o3-mini、o4-mini、gpt-5.4系列等见SUPPORT_REASONING_EFFORT_MODELS生效非法取值会在 parse_reasoning_effort 处直接抛错。Deep Research 深度配置GPT Researcher 的深度研究Deep Research由三个参数协同控制探索的广度 × 深度 × 并发DEEP_RESEARCH_BREADTH默认3控制每一层并行探索的研究路径数量。值越高如5会同时调研更多样化的子主题覆盖面更广但可能削弱对核心主题的聚焦默认3是广度与深度之间的平衡点。DEEP_RESEARCH_DEPTH默认2控制每条研究路径上连续执行的搜索迭代轮数。值越高如3~4可以沿引用线索深挖专业信息但研究耗时显著增加默认2在保证深度的同时维持可接受的完成时间。DEEP_RESEARCH_CONCURRENCY默认4控制深度研究中的并发操作数。在性能好的系统上提高该值可加快研究进度但可能触发 API 限流或推高资源消耗默认4适合大多数环境。针对不同场景的调参建议官方文档给出的实践结论学术或高度专业化研究建议同时提高广度与深度例如BREADTH4, DEPTH3快速探索式研究降低取值可更快出结果但细节较少例如BREADTH2, DEPTH1。这三个参数与MAX_ITERATIONS、MAX_SUBTOPICS一起构成了研究过程的工程量控制面直接影响最终报告的详尽程度与调用成本。对应实现可在 skills/deep_research.py 中看到深度研究技能在构造时会沿用researcher.cfg.config_path确保子任务继承同一份配置。环境变量方式.env 与 export不写 JSON 文件也能完成全部配置配置键名即环境变量名在项目目录的.env文件中逐行写入或在当前 shell 中export# 手动切换搜索引擎与报告格式 export RETRIEVERbing export REPORT_FORMATIEEE # 学术文献综述组合网页与学术检索器 export RETRIEVERtavily,openalex,semantic_scholarconfig.py 的convert_env_value会依据BaseConfig的类型注解把环境变量字符串转换为正确类型布尔值接受true/1/yes/onfalse/0/no/off为否整数、浮点直接转换list与dict类型则通过json_repair做宽松解析容忍手写时的尾逗号、单引号等解析失败会抛出明确的类型转换错误。由于这些逻辑同样作用于LLM_KWARGS/EMBEDDING_KWARGS这类 JSON 格式配置你可以放心地在环境变量中传入结构化参数。注意一个细节REASONING_EFFORT在源码中是直接读取环境变量os.getenv(REASONING_EFFORT)解析的因此它不支持写入 config.json 的方式必须通过环境变量或.env配置。源码级实现原理配置如何被解析与生效加载与合并Config.__init__config.py的执行流程load_config合并默认值与自定义 JSON自定义键覆盖默认键_set_attributes逐键setattr并对每个键优先读取同名环境变量完成最高优先级覆盖_set_embedding_attributes/_set_llm_attributes把provider:model字符串拆分为(provider, model)元组如self.fast_llm_provider/self.fast_llm_model并解析REASONING_EFFORT_handle_deprecated_attributes对历史遗留变量做兼容与告警当REPORT_SOURCE ! web时校验并创建DOC_PATH目录validate_doc_path 使用os.makedirs(..., exist_okTrue)。检索器校验parse_retrieversconfig.py会把逗号分隔的字符串切分为列表并与get_all_retriever_names()返回的合法名称比对任何非法名称都会抛ValueError随后被_set_attributes捕获并回退到tavily同时在控制台打印告警。兼容性与类型护栏BaseConfigvariables/base.py作为TypedDict提供了完整的类型声明convert_env_value中的 Union 处理如Optional[str]会优先识别none/null/哨兵值返回None避免字符串转换遮蔽空值分支。对于EMBEDDING_PROVIDER、LLM_PROVIDER、FAST_LLM_MODEL、SMART_LLM_MODEL等旧变量源码会发出FutureWarning提示改用新键EMBEDDING、FAST_LLM、SMART_LLM。扩展MCP 与图像生成配置除官方文档列出的参数外当前仓库的默认配置还包含两类可选扩展配置MCP 相关config.py 中有专门处理MCP_SERVERS预定义 MCP 服务器列表、MCP_AUTO_TOOL_SELECTION是否自动为查询选择最优工具默认True、MCP_ALLOWED_ROOT_PATHS本地文件访问白名单、MCP_STRATEGY执行策略fast/deep/disabled图像生成需GOOGLE_API_KEYIMAGE_GENERATION_MODEL默认models/gemini-2.5-flash-image、IMAGE_GENERATION_MAX_IMAGES每份报告最多生成图片数默认3、IMAGE_GENERATION_ENABLED总开关默认False、IMAGE_GENERATION_STYLEdark/light/auto、IMAGE_GENERATION_PROVIDERgoogle或modelslab。这两组配置均可通过同样的 JSON 或环境变量方式注入。配置实践建议与常见问题只覆盖你需要的键config.json无需写全load_config会用DEFAULT_CONFIG.copy()兜底合并写全反而容易与后续升级的默认值脱节。Token 上限先匹配模型再匹配任务先对照上文的模型输出能力表确定SMART_TOKEN_LIMIT再按比例设置另外两档大输出模型GPT-5、Claude 4.x建议直接采用 16000~32000 档位否则长报告会被截断。推理模型注意温度与推理力度GPT-5 家族与 Claude 4.x 不支持自定义温度需要更快响应时把REASONING_EFFORT调为low需要更深规划时调为high。切换检索器先看 Key组合检索器会并行调用多个搜索服务务必先为每个服务配置好 API Key否则控制台会给出缺失提示test_your_retriever 可用于本地验证检索器可用性。本地文档研究将REPORT_SOURCE设为doc并指向DOC_PATH目录源码会自动创建目录并校验存在性更多文档化用法可参考 本地文档说明。LLM 提供商的更多支持非 OpenAI 提供商的完整接入说明见 supported-llms 与 llms 总览各检索器的实现细节可在 gpt_researcher/retrievers/ 中按目录查阅。无论你是想换一个更便宜的 LLM、接入本地文档语料还是让深度研究报告更有学术深度配置层都是第一个需要掌握的入口。以 config.md 为索引、以 default.py 为对照表再结合本文的源码级说明你就能在不改一行业务代码的情况下把 GPT Researcher 调成完全适合自己场景的研究工具。【免费下载链接】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），仅供参考
