GPT Researcher 配置体系详解环境变量、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 仓库中的配置参考文档.claude/references/config-reference.md编写系统梳理项目的全量配置项LLM 选择、检索器Retriever接入、报告格式、图片生成、Deep Research 与 MCP 等功能开关并结合 Config 类源码 与 默认值定义 说明每个参数的解析方式、默认值与优先级规则。读完本文你可以独立完成一个从零到可运行的.env配置并理解“为什么某些配置不生效”这类常见问题的根源。配置加载机制三层优先级在逐一介绍配置项之前先讲清楚配置的加载顺序这是理解整套配置体系的前提。GPT Researcher 的配置按以下优先级从高到低生效环境变量 (Environment Variables最高优先级) ↓ JSON 配置文件 (如通过 config_path 或 CONFIG_PATH 提供) ↓ 默认值 (DEFAULT_CONFIG最低优先级)这一机制在 Config._set_attributes 中有明确实现遍历配置字典中的每个键时先调用os.getenv(key)检查同名环境变量若存在则用convert_env_value按BaseConfig中声明的类型完成转换后覆盖配置值for key, value in config.items(): env_value os.getenv(key) if env_value is not None: value self.convert_env_value(key, env_value, BaseConfig.__annotations__[key]) setattr(self, key.lower(), value)三个值得注意的实现细节键会被小写化存储。文档中特别强调“Config keys are lowercased when accessed”。例如默认配置里写的是SMART_LLM访问时却是self.cfg.smart_llm。这一行为由上述代码中的setattr(self, key.lower(), value)直接产生排查“属性找不到”类问题时务必记住这一点。JSON 配置会与默认值合并。load_config使用DEFAULT_CONFIG.copy()再update(custom_config)即 JSON 文件只需写要覆盖的键缺失的键自动补齐默认值config.py#L172-L178。找不到配置文件时只打印警告并回退默认配置不会抛异常。环境变量会按类型自动转换。convert_env_valueconfig.py#L257-L306依据 base.py 中BaseConfig(TypedDict)的类型注解做转换布尔值接受true/1/yes/onint/float直接转型list/dict类型如LLM_KWARGS、MCP_SERVERS用json_repair容错解析Optional[str]会把none/null/空串归一为None。相关行为有专门测试覆盖见 test_convert_env_value_json_repair.py 与 test_convert_env_value_optional.py。必需变量最小可运行配置只需要两个变量一个 LLM 提供商密钥和一个检索器密钥二选一即可取决于你选用的提供商OPENAI_API_KEYsk-... # 或任一其它 LLM 提供商密钥 TAVILY_API_KEYtvly-... # 或任一其它检索器密钥若不指定RETRIEVER默认检索器为tavily见 default.py 中RETRIEVER: tavily因此 Tavily 密钥是默认路径下的硬性要求。LLM 配置三级模型分工GPT Researcher 将 LLM 按任务类型拆成三个角色每个角色独立配置FAST_LLMopenai:gpt-4o-mini # 快速任务摘要等 SMART_LLMopenai:gpt-4o # 复杂推理报告撰写 STRATEGIC_LLMopenai:o3-mini # 规划agent 选择等 TEMPERATURE0.4 # 0.0-1.0 MAX_TOKENS4000 REASONING_EFFORTmedium # 推理系列模型low, medium, highprovider:model格式与校验FAST_LLM、SMART_LLM、STRATEGIC_LLM统一采用provider:model格式。Config.parse_llm 会按第一个冒号拆分并校验 provider 是否在受支持列表中llm_provider, llm_model llm_str.split(:, 1) assert llm_provider in _SUPPORTED_PROVIDERS若格式不合法会抛出带示例的指引信息Set SMART_LLM or FAST_LLM llm_provider:llm_model Eg openai:gpt-4o-mini。当前仓库 llm_provider/generic/base.py 中_SUPPORTED_PROVIDERS包含openai、anthropic、azure_openai、google_genai、google_vertexai、groq、together、mistralai、ollama、huggingface、bedrock、deepseek、dashscope、xai、openrouter、vllm_openai、nebius等 28 个提供商完整列表以源码为准该集合会随版本扩充。需要注意默认值中三个 LLM 均已带上openai:前缀如openai:gpt-5.4-mini且默认FAST_TOKEN_LIMIT6000、SMART_TOKEN_LIMIT12000、STRATEGIC_TOKEN_LIMIT8000。源码注释解释了对推理模型的 token 上限策略对 gpt-5.x 这类推理模型这些限额映射到max_completion_tokens会连同推理 token 一起计入因此上限留了较大余量。已弃用的配置项LLM_PROVIDER、FAST_LLM_MODEL、SMART_LLM_MODEL三个旧变量已被弃用。_handle_deprecated_attributes 检测到它们时仍会生效但会触发FutureWarning提示改用FAST_LLM/SMART_LLM的组合格式。旧项目迁移时建议直接替换避免后续版本移除后失效。REASONING_EFFORTREASONING_EFFORT只对支持推理控制的模型有效取值low、medium、high默认medium。parse_reasoning_effort 对非法取值会直接抛出ValueError并列出合法选项未设置时回落到ReasoningEfforts.Medium。另外源码中维护了一份NO_SUPPORT_TEMPERATURE_MODELS名单o1/o3/o4 系列及 GPT-5 家族等这些模型会忽略TEMPERATURE设置配置TEMPERATURE时应注意所选模型是否在该名单内base.py#L43 起。LLM 提供商 API Key不同提供商所需的密钥与端点配置如下# OpenAI OPENAI_API_KEYsk-... OPENAI_BASE_URLhttps://api.openai.com/v1 # Anthropic ANTHROPIC_API_KEYsk-ant-... # Google GOOGLE_API_KEYAIza... # Groq GROQ_API_KEYgsk_... # Azure OpenAI AZURE_OPENAI_API_KEY... AZURE_OPENAI_ENDPOINThttps://your-resource.openai.azure.com/使用 Azure 时对应的 LLM 变量应写azure_openai:deployment-name形式即 provider 取azure_openai本地 Ollama 则用ollama:model无需 API Key。检索器Retriever配置RETRIEVERtavily # 单个或逗号分隔tavily,google,mcp MAX_SEARCH_RESULTS_PER_QUERY5 SIMILARITY_THRESHOLD0.42多检索器解析RETRIEVER支持逗号分隔的多个检索器。Config.parse_retrievers 将其拆分为列表并用 get_all_retriever_names 动态校验该方法直接扫描 gpt_researcher/retrievers/ 目录下的子目录名得出合法值因此仓库中实际存在的检索器tavily、google、bing、brave、serper、serpapi、exa、duckduckgo、searx、arxiv、openalex、semantic_scholar、pubmed_central、searchapi、mcp、xquik等都是可配置值。若检测到非法名称会抛出ValueError并列出全部合法选项而在_set_attributes中该异常被捕获后降级为警告并回退到tavily单检索器。MAX_SEARCH_RESULTS_PER_QUERY默认值为 5default.py#L21SIMILARITY_THRESHOLD默认 0.42用于向量检索时过滤低相关度内容调高该阈值可更严格地过滤噪音但可能漏掉相关来源。检索器 API Key各检索器的密钥变量TAVILY_API_KEYtvly-... GOOGLE_API_KEYAIza... GOOGLE_CX_KEY... BING_API_KEY... SERPER_API_KEY... SERPAPI_API_KEY... EXA_API_KEY...多数搜索类检索器Tavily、Google、Bing、Serper、SerpApi、Exa需要相应 KeyDuckDuckGo、SearX、arXiv、OpenAlex、Semantic Scholar 等公开检索器则通常无需密钥。报告配置REPORT_FORMATapa # apa, mla, chicago, harvard, ieee TOTAL_WORDS1000 LANGUAGEenglish CURATE_SOURCEStrue对应默认值在 default.py 中为REPORT_FORMATAPA、TOTAL_WORDS1200、LANGUAGEenglish、CURATE_SOURCESFalse。也就是说REPORT_FORMAT控制引用格式APA、MLA、Chicago、Harvard、IEEE 任选其一TOTAL_WORDS控制报告目标篇幅代码默认 1200 词可按需调小如 1000以降低成本LANGUAGE指定报告输出语言CURATE_SOURCES是否启用来源筛选curate默认关闭。启用后会由模型对检索到的来源做二次筛选可能减少噪音引用但会增加一次 LLM 调用开销。功能开关图片生成IMAGE_GENERATION_ENABLEDtrue GOOGLE_API_KEYAIza... IMAGE_GENERATION_MODELmodels/gemini-2.5-flash-image IMAGE_GENERATION_MAX_IMAGES3 IMAGE_GENERATION_STYLEdark # dark, light, autodefault.py 中图片生成的默认值为IMAGE_GENERATION_ENABLEDFalse默认关闭需手动开启、IMAGE_GENERATION_MODELmodels/gemini-2.5-flash-image、IMAGE_GENERATION_MAX_IMAGES3、IMAGE_GENERATION_STYLEdark并额外提供IMAGE_GENERATION_PROVIDERgoogle或modelslab用于选择图像提供商。源码注释标明gemini-2.5-flash-image属于免费层模型imagen-4.0-generate-001等为付费层模型选型时可据此权衡成本。Deep Research深度研究DEEP_RESEARCH_BREADTH4 # 每层分支子主题数 DEEP_RESEARCH_DEPTH2 # 递归层级 DEEP_RESEARCH_CONCURRENCY2 # 并行任务数控制研究任务的“广度 × 深度 × 并发”BREADTH决定每个层级展开多少个并行子主题DEPTH控制递归研究的层数CONCURRENCY限制同时执行的并行任务数。注意当前代码默认值为DEEP_RESEARCH_BREADTH3、DEEP_RESEARCH_DEPTH2、DEEP_RESEARCH_CONCURRENCY4default.py#L39-L41可按机器负载与 API 限速自行调优——调高并发可缩短总耗时但更容易触发提供商的速率限制。MCP 策略MCP_STRATEGYfast # fast, deep, disabledMCP_STRATEGY控制 MCPModel Context Protocol检索执行策略取值fast、deep或disabled默认fast。相关配套项还有MCP_AUTO_TOOL_SELECTION默认True由 LLM 自动为查询挑选最合适的 MCP 工具、MCP_SERVERS预定义的 MCP 服务器配置列表JSON 数组格式、MCP_ALLOWED_ROOT_PATHS本地文件访问的允许根路径白名单。本地文档DOC_PATH./my-docs # 支持格式: PDF, DOCX, TXT, CSV, XLSX, PPTX, MDDOC_PATH默认值为./my-docs。配合REPORT_SOURCE默认web使用当REPORT_SOURCE非web例如本地文档模式时_set_doc_path 会对该路径做校验os.makedirs(..., exist_okTrue)校验失败时打印警告并回退到默认路径不会中断启动。服务器HOST0.0.0.0 PORT8000 VERBOSEtrue后端服务由 backend/run_server.py 通过uvicorn.run启动默认监听 8000 端口VERBOSE对应配置项VERBOSE默认False用于在日志中输出更详细的执行过程对应Config.set_verbose。使用 JSON 配置文件除环境变量外GPT Researcher 也支持通过 JSON 配置文件初始化。Config构造函数接受config_path参数或在环境中设置CONFIG_PATHload_configfrom gpt_researcher import Config config Config(config_path./my_config.json) # 或设置环境变量 CONFIG_PATH./my_config.json仓库内置了一个示例 test_local.json且Config.list_available_configs()可以列出variables目录下所有可用配置名。示例 JSON 只需覆盖差异项即可{ FAST_LLM: google_genai:gemini-2.0-flash, SMART_LLM: anthropic:claude-3-5-sonnet-20241022, RETRIEVER: brave,duckduckgo, TOTAL_WORDS: 800, IMAGE_GENERATION_ENABLED: false }由于加载时与DEFAULT_CONFIG合并未写出的键自动沿用默认值而任何同名环境变量仍会优先于 JSON 中的值生效。完整示例 .env# 必需项 OPENAI_API_KEYsk-your-key TAVILY_API_KEYtvly-your-key # LLM FAST_LLMopenai:gpt-4o-mini SMART_LLMopenai:gpt-4o # 报告 TOTAL_WORDS1000 LANGUAGEenglish # 可选图片生成 IMAGE_GENERATION_ENABLEDtrue GOOGLE_API_KEYAIza-your-key IMAGE_GENERATION_STYLEdark小结GPT Researcher 的配置体系可以概括为三条规则优先级环境变量 JSON 配置文件 DEFAULT_CONFIG默认值同名键高优先级者覆盖低优先级者命名环境变量与配置键使用大写下划线风格如SMART_LLM但在Config实例上访问时一律小写smart_llm格式约定LLM/Embedding 值遵循provider:model组合格式RETRIEVER支持逗号分隔多值布尔与列表类型的环境变量会被自动容错转换。掌握这三条规则后本文覆盖的所有配置项都可以按同样的模式推导其行为。若需要确认某个键的当前默认值最权威的来源始终是 gpt_researcher/config/variables/default.py本文中的参考值来自仓库文档个别数值如TOTAL_WORDS、DEEP_RESEARCH_BREADTH在文档示例与代码默认值之间存在差异时以代码默认值为准。【免费下载链接】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），仅供参考