企业官网建设流程全解析

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）、三档 LLM（FAST/SMART/STRATEGIC）、Embedding、Token 上限、报告格式等全部核心配置项的取值与底层实现原理，能够按自己的 LLM 提供商、检索服务与报告需求定制一次研究任务。

GPT Researcher 是一个面向任意数据源的自主研究 Agent，其最大的灵活性来源就是配置层：通过一个 JSON 文件或几行环境变量，就能切换搜索引擎、LLM 提供商、报告格式、研究深度与输出语言，而不需要改动任何业务代码。本指南以官方配置文档 config.md 为主线，逐项拆解所有配置参数，并结合仓库源码说明它们是如何被解析、校验与生效的。

配置体系总览：三种配置来源与优先级

配置入口位于仓库 gpt_researcher/config/ 目录：

• config.py：Config类，负责加载、合并、类型转换与校验所有配置；
• variables/default.py：DEFAULT_CONFIG字典，内置全部键的默认值；
• variables/base.py：BaseConfig（TypedDict），声明每个键的类型约束（bool、int、float、str、dict、list等）；
• variables/test_local.json：内置的可选 JSON 配置示例。

配置的来源有三个层级，从 load_config 的实现可以清晰看到合并逻辑：

1. 内置默认值：未做任何配置时，直接使用DEFAULT_CONFIG；
2. 外部 JSON 文件：通过config_path参数（或在CONFIG_PATH环境变量）指定，load_config会先拷贝DEFAULT_CONFIG，再用自定义 JSON 逐键覆盖——因此你不必写全所有键，缺失的键自动回落为默认值；
3. 环境变量：在_set_attributes（config.py）中，任何环境变量只要键名匹配（如RETRIEVER、SMART_LLM），就会覆盖 JSON 与默认值，优先级最高。

对应到源码，这套优先级正是"环境变量 > 自定义 config.json > 内置默认值"。需要注意：默认值字典本身也在持续演进，例如本文写作时 default.py 中三档 Token 上限已是FAST_TOKEN_LIMIT=6000、SMART_TOKEN_LIMIT=12000、STRATEGIC_TOKEN_LIMIT=8000，与部分旧文档记录的 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 用于启动后端服务（uvicorn），CLI 方式生成报告使用 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.json

load_config对路径做了容错：文件不存在时打印警告并回落默认配置；如果传入的路径没有.json后缀，还会提示是否遗漏了扩展名。

核心配置项详解

以下逐项说明官方文档列出的配置参数，并补充当前仓库 default.py 中的实际默认值。

检索与数据源

Retriever 多值组合：RETRIEVER支持用逗号组合多个检索器，例如学术文献综述场景推荐：

export RETRIEVER=tavily,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 与生成参数

关于三档 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 最大输出）校准的。对于输出能力更强的模型，需要按比例上调，否则报告可能被截断：

FAST_TOKEN_LIMIT与STRATEGIC_TOKEN_LIMIT可按比例同步调整。硬性上限为200k，作为防误写的合理性护栏。当前默认的 GPT-5 系列（gpt-5.4/gpt-5.4-mini）本身就属于大输出模型，因此 default.py 已把默认值上调为 6000/12000/8000，且注释说明这些值映射到max_completion_tokens，需同时覆盖推理 Token。

温度与推理力度

TEMPERATURE=0.4是通用默认值。但需要注意：部分推理模型（如deepseek/deepseek-reasoner、OpenAI o 系列、GPT-5 家族、Claude 4.x 家族）不支持自定义温度，见 base.py 的NO_SUPPORT_TEMPERATURE_MODELS列表——对这类模型温度参数会被忽略。

REASONING_EFFORT是战略模型的推理力度开关，枚举定义于 ReasoningEfforts：high/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适合大多数环境。

针对不同场景的调参建议（官方文档给出的实践结论）：

• 学术或高度专业化研究：建议同时提高广度与深度，例如BREADTH=4, DEPTH=3；
• 快速探索式研究：降低取值可更快出结果但细节较少，例如BREADTH=2, DEPTH=1。

这三个参数与MAX_ITERATIONS、MAX_SUBTOPICS一起构成了研究过程的"工程量"控制面，直接影响最终报告的详尽程度与调用成本。对应实现可在 skills/deep_research.py 中看到，深度研究技能在构造时会沿用researcher.cfg.config_path，确保子任务继承同一份配置。

环境变量方式：.env 与 export

不写 JSON 文件也能完成全部配置：配置键名即环境变量名，在项目目录的.env文件中逐行写入，或在当前 shell 中export：

# 手动切换搜索引擎与报告格式 export RETRIEVER=bing export REPORT_FORMAT=IEEE # 学术文献综述：组合网页与学术检索器 export RETRIEVER=tavily,openalex,semantic_scholar

config.py 的convert_env_value会依据BaseConfig的类型注解把环境变量字符串转换为正确类型：布尔值接受true/1/yes/on（false/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）的执行流程：

1. load_config合并默认值与自定义 JSON（自定义键覆盖默认键）；
2. _set_attributes逐键setattr，并对每个键优先读取同名环境变量，完成最高优先级覆盖；
3. _set_embedding_attributes/_set_llm_attributes把provider:model字符串拆分为(provider, model)元组（如self.fast_llm_provider/self.fast_llm_model），并解析REASONING_EFFORT；
4. _handle_deprecated_attributes对历史遗留变量做兼容与告警；
5. 当REPORT_SOURCE != 'web'时，校验并创建DOC_PATH目录（validate_doc_path 使用os.makedirs(..., exist_ok=True)）。

检索器校验

parse_retrievers（config.py）会把逗号分隔的字符串切分为列表，并与get_all_retriever_names()返回的合法名称比对；任何非法名称都会抛ValueError，随后被_set_attributes捕获并回退到tavily，同时在控制台打印告警。

兼容性与类型护栏

BaseConfig（variables/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_KEY）：IMAGE_GENERATION_MODEL（默认models/gemini-2.5-flash-image）、IMAGE_GENERATION_MAX_IMAGES（每份报告最多生成图片数，默认3）、IMAGE_GENERATION_ENABLED（总开关，默认False）、IMAGE_GENERATION_STYLE（dark/light/auto）、IMAGE_GENERATION_PROVIDER（google或modelslab）。

这两组配置均可通过同样的 JSON 或环境变量方式注入。

配置实践建议与常见问题

1. 只覆盖你需要的键：config.json无需写全，load_config会用DEFAULT_CONFIG.copy()兜底合并，写全反而容易与后续升级的默认值脱节。
2. Token 上限先匹配模型再匹配任务：先对照上文的模型输出能力表确定SMART_TOKEN_LIMIT，再按比例设置另外两档；大输出模型（GPT-5、Claude 4.x）建议直接采用 16000~32000 档位，否则长报告会被截断。
3. 推理模型注意温度与推理力度：GPT-5 家族与 Claude 4.x 不支持自定义温度；需要更快响应时把REASONING_EFFORT调为low，需要更深规划时调为high。
4. 切换检索器先看 Key：组合检索器会并行调用多个搜索服务，务必先为每个服务配置好 API Key，否则控制台会给出缺失提示（test_your_retriever 可用于本地验证检索器可用性）。
5. 本地文档研究：将REPORT_SOURCE设为doc并指向DOC_PATH目录，源码会自动创建目录并校验存在性；更多文档化用法可参考 本地文档说明。
6. 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