Local Deep Research 基准测试系统：从 SimpleQA 评测到统计置信度解读的完整实践指南

Local Deep Research 基准测试系统：从 SimpleQA 评测到统计置信度解读的完整实践指南

【免费下载链接】local-deep-research~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.项目地址: https://gitcode.com/GitHub_Trending/lo/local-deep-research

导读

本文以 docs/BENCHMARKING.md 为核心骨架，系统讲解 Local Deep Research（LDR）基准测试系统：如何通过 Web 界面、API 与 CLI 三种方式在 SimpleQA 与 BrowseComp 数据集上运行评测，如何配置搜索引引擎与搜索策略，以及如何用 Wilson 置信区间、样本量计算等统计学方法严谨地解读评测结果。读完本文，你将掌握一套从"跑出数字"到"判断数字是否可信、能否对比"的完整基准测试方法论，并能在实际研究场景中据此验证与调优配置。

重要前提：基准测试结果是配置测试的指标，不是你在特定研究主题上性能的预测值。在 SimpleQA 上表现良好的配置，面对你的真实研究问题时可能表现迥异——这是理解本系统所有设计的前提。

一、基准测试系统概览：它评测什么、解决什么问题

LDR 的基准测试系统通过标准化数据集评测三类要素：搜索配置（搜索引擎、迭代次数、每轮问题数）、模型（本地或云端 LLM）与搜索策略（focused_iteration / source_based），从而帮助用户找到可靠的起点配置。

从源码结构看，整套系统由以下模块构成，均位于 src/local_deep_research/benchmarks：

• datasets/：数据集加载器（SimpleQA、BrowseComp、xbench-DeepSearch、自定义数据集模板）；
• evaluators/：自动评测器（simpleqa / browsecomp / composite），默认用 Claude 3.7 Sonnet 打分；
• metrics/：指标计算、统计（含 Wilson 区间与样本量计算，见 statistics.py）、报告生成与可视化；
• cli/：命令行入口 benchmark_commands.py；
• api/：程序化调用入口 benchmark_functions.py；
• web_api/：Web 界面后端服务。

整个框架的顶层说明见 benchmarks/README.md，示例脚本见 examples/benchmarks/README.md。

二、快速开始：三种运行方式

2.1 Web 界面（推荐入门）

1. 在 Web 界面导航到Benchmark页面；
2. 配置你的测试：
   • 选择数据集（推荐SimpleQA）；
   • 设置示例数量（从 20～50 个开始）；
   • 评测会使用你当前的 Settings 配置（搜索引引擎、策略、模型等）；
3. 点击Start Benchmark并监控进度；
4. 在Benchmark Results页面查看结果。

从 community_benchmark_results/README.md 可以看到，v0.6.0+ 的 Web 界面还支持在 Benchmark Results 页面点击 "YAML" 按钮导出结构化结果文件，方便提交社区共享或留存复现记录。

2.2 程序化 API（Python）

benchmark_functions.py 暴露了三个高层评测函数与一个配置对比函数。以 SimpleQA 为例：

from local_deep_research.api.benchmark_functions import evaluate_simpleqa # 运行 20 个示例的 SimpleQA 评测 result = evaluate_simpleqa( num_examples=20, # 示例数量，从 20~50 起步 search_iterations=3, # 每个查询的搜索迭代次数 questions_per_iteration=3,# 每轮迭代生成的问题数 search_tool="searxng", # 搜索引擎，如 searxng / tavily / wikipedia ) # 打印准确率 print(f"Accuracy: {result['metrics']['accuracy']:.3f}")

对应的evaluate_browsecomp()、evaluate_xbench_deepsearch()签名与上述一致，分别针对 BrowseComp 与 xbench-DeepSearch 数据集。所有函数均支持以下关键参数（源码 docstring 中的默认值）：

自定义评测模型示例：

result = evaluate_simpleqa( num_examples=10, evaluation_model="gpt-4o", evaluation_provider="openai", )

使用人工评测（适合小样本抽查）：

result = evaluate_simpleqa(num_examples=5, human_evaluation=True)

compare_configurations()用于在同一数据集上对比多组搜索配置：它会依次运行每组配置的基准测试，并生成一份 Markdown 对比报告（含汇总表与各组配置详情），返回结果中包含report_path与各组results。若不传configurations，源码默认对比三组配置：基线（1 轮迭代 × 3 问题）、更多迭代（3 × 3）、更多问题（1 × 5）。

2.3 命令行接口（CLI）

CLI 入口位于 benchmark_commands.py，子命令为simpleqa、browsecomp、list与compare。基于源码中的 argparse 定义，完整参数如下：

# 运行 SimpleQA 基准测试（默认 100 示例、3 轮迭代、每轮 3 问题、searxng） python -m local_deep_research.benchmarks.cli.benchmark_commands simpleqa \ --examples 20 --iterations 3 --questions 3 --search-tool searxng # 运行 BrowseComp 基准测试（换用 wikipedia 搜索引擎） python -m local_deep_research.benchmarks.cli.benchmark_commands browsecomp \ --examples 10 --search-tool wikipedia # 列出可用数据集 python -m local_deep_research.benchmarks.cli.benchmark_commands list # 对比多组搜索配置 python -m local_deep_research.benchmarks.cli.benchmark_commands compare \ --dataset simpleqa --examples 20

通用参数说明（含默认值）：

CLI 运行结束后会在终端打印准确率、示例总数、正确数与平均处理时间，并给出报告保存路径。另有一套独立脚本位于 examples/benchmarks（如run_simpleqa.py、run_browsecomp.py），适合快速验证，输出包含 JSONL 原始结果、JSONL 评测结果与 Markdown 汇总报告。

三、数据集：选择适合你的评测基准

3.1 SimpleQA（推荐）

• 基于事实的问题，答案明确；
• 最适合测试通用知识检索能力；
• 是比较不同配置的优良基线。

从 datasets/simpleqa.py 的源码实现看，SimpleQA 数据集以problem/answer字段组织，加载器会保证problem、answer、correct_answer字段齐全，问题取自problem字段、标准答案取自answer字段，评测时逐条对比模型回答与标准答案。

3.2 BrowseComp（进阶）

• 复杂的浏览与对比任务，需要跨多个来源综合信息；
• 目前性能受限，测试时最多使用 20 个示例。

3.3 xbench-DeepSearch（进阶）

从get_available_benchmarks()（见 benchmark_functions.py）可知，系统还内置xbench-DeepSearch（深度检索与调研类查询）数据集，三个内置基准均推荐 100 个示例。此外支持通过--custom-dataset/dataset_path加载自定义数据集（模板见 datasets/custom_dataset_template.py），社区也沉淀了结果提交模板 benchmark_template.yaml。

四、配置选项：搜索引擎与策略

4.1 搜索引擎

值得注意的是，不同搜索引擎检索到的内容不同，引擎延迟也会影响单查询时限内实际取回的内容，因此搜索引擎是实验结果对比中的一个独立变量（详见"跨运行比较限制"一节）。

4.2 搜索策略

• Focused Iteration（focused_iteration）：最适合 SimpleQA 这类事实型问题；
• Source-Based（source_based）：更适合需要全面资料的综合研究。

从 benchmark_commands.py 看，--search-strategy还支持standard、rapid、parallel、iterdrag等更多策略选项；同时可搭配--search-model/--search-provider指定执行搜索的模型。策略的差异不仅是速度，而是答题方式的本质区别——focused_iteration 与 source_based 的分数衡量的不是同一件事（见下文"跨运行比较限制"）。

五、解读结果：关键指标与性能预期

5.1 关键指标

5.2 性能预期（社区经验值）

• Focused iteration + SimpleQA：最优设置下潜力约95%；
• Source-based 策略：约70%准确率，但结果更全面。

这些数值是配置调优的方向性参考（社区基线可见 community_benchmark_results/README.md：GPT-4.1-mini + focused-iteration + SearXNG 在 20～100 题样本上约 95%），不是精确测量，也不代表你在自己研究主题上的表现。

六、统计解释：如何判断一个数字是否可信

基准数字是估计值而非精确测量。本节的目的是帮助你判断：某个结果有多大可信度？两次运行的差异何时才有意义？

6.1 单次运行的置信区间（Wilson 分数区间）

报告出的 "91%" 只是点估计，其不确定性取决于测试的示例数量。Wilson score interval给出 95% 置信水平下的真实区间——与简单的正态近似不同，它在 0% 和 100% 附近行为正确（不会产生区间越界）：

center = (p̂ + z²/2n) / (1 + z²/n) half-width = z × sqrt(p̂(1−p̂)/n + z²/4n²) / (1 + z²/n) 其中 p̂ = 观测准确率，n = 运行的示例数，z = 1.96（95% 置信区间）

该公式在仓库中有精确的 Python 实现：benchmarks/metrics/statistics.py 的wilson_score_interval()函数——它返回lower、upper、center、margin_of_error与sample_size，并明确注释：与 Wald（正态）近似不同，Wilson 区间永远不会产生 [0,1] 之外的边界，在 0%/100% 处行为正确，且小样本下有更好的覆盖率。其中正态分位数由 Beasley-Springer-Moro 有理近似实现（精度约 1e-8）。

按样本量划分的 95% 置信区间误差幅度：

核心要点：20 个示例的运行，不确定性窗口达 ±14～21%。报告的 "91%" 实际可能落在 77%～100% 的任何位置。至少用 100 个示例再下结论，对比配置则需要 200+ 个示例。

6.2 对比两组配置：需要多少样本

要判断配置 A 是否优于配置 B，需要足够的示例使观测差异大于噪声。下表给出在 80% 统计功效（α = 0.05，双尾检验）下，可靠检出指定绝对准确率差异时每组配置需要的示例数（两组独立运行，通过同一 seed 使用相同问题集）：

经验法则：如果两次运行观测到的差异小于任一运行自身的误差幅度（见上一节表格），请将结果视为打平。

仓库的 statistics.py 实现了对应的样本量公式sample_size_for_difference()：

n = (z_alpha/2 + z_beta)² × (p1(1−p1) + p2(1−p2)) / (p1 − p2)²

即双样本比例 z 检验的每组所需样本量（向上取整），默认 80% 功效、α = 0.05。

6.3 何时两次运行不可对比

即使样本量很大，只要以下任一因素在两次运行之间发生变化，跨运行对比就不可靠：

• LDR 版本——版本间的搜索逻辑、提示词模板与结果过滤可能已变化；
• 策略——focused_iteration与source_based的设计上以不同方式答题，它们的分数衡量的是不同事物；
• 评测模型（Grader）——更换评测 LLM 会改变"正确"的定义；同一系统回答在不同评测器下可能得到不同评分；
• 随机种子 / 问题样本——SimpleQA 的某些子集天然比其他子集更容易；对比运行必须始终一致使用--seed 42（或任一固定种子）；
• 搜索引擎——Tavily、SearXNG、Brave 检索到的内容不同；引擎延迟也会影响单查询时限内实际取回的内容。

请将 (LDR 版本, 策略, 搜索引擎, 评测模型, 种子) 的每种组合视为一个独立的实验条件，对比只在同一条件下才有效。

6.4 评测 LLM 自身的误差

评测模型（默认：通过 OpenRouter 的 Claude 3.7 Sonnet）并非完美。在 SimpleQA 风格问题上，它大约会错评 1% 的回答——与 SimpleQA 原始论文中同级别评测器的标定结果一致。

这在实际中意味着：

• 100 个示例：约 1 题被评错。1 个百分点差异（如 91% vs 92%）与评测噪声不可区分；
• 500 个示例：约 5 题被评错。1% 的差距仍在评测噪声之内；3～4 pp 的差异开始可解读；
• 评测器偏向保守——会把含糊或部分正确的匹配判为错误——因此报告准确率会略微低估真实准确率。

在 500 个示例以内的运行中，不要为小于 ~2～3 pp 的差异做优化。信号不存在。

6.5 决策检查清单

在对基准结果采取行动之前，逐项核对：

[ ] n ≥ 100 示例（对比两组配置时用 ≥ 200） [ ] 所有对比运行使用相同随机种子 [ ] 相同 LDR 版本、策略、搜索引擎、评测模型 [ ] 观测差异 > 每次运行的误差幅度（见上表） [ ] 观测差异 > ~2 pp（超过评测噪声的最小有意义差异）

七、最佳实践：测试工作流与故障排查

7.1 推荐工作流

1. 先跑 20 个示例验证配置能正常工作；
2. 检查搜索结果是否成功取回（指标中的 Search Results）；
3. 扩展到 50～100 个示例获得可靠指标；
4. 根据结果调整设置，再回到第 1 步迭代。

社区实践还建议（见 community_benchmark_results/README.md）：大模型（70B+）用 32768+ 上下文、focused-iteration 8 轮 × 5 问题或 source-based 5 轮 × 3 问题；小模型（<70B）用 16384+ 上下文、focused-iteration 5 轮 × 3 问题或 source-based 3 轮 × 3 问题。

7.2 故障排查

八、环境要求：需要的 API 密钥

运行基准测试需要以下凭据：

• 评测（Evaluation）：OpenRouter API 密钥——用于自动打分；
• 搜索（Search）：所选搜索引擎的 API 密钥；
• LLM：语言模型提供商的 API 密钥（本地模型如 Ollama / llama.cpp 则无需外部密钥）。

九、负责任地使用

• 先跑小测试验证配置；
• 共享资源场景下使用适中的示例数量；
• 在Metrics 页面监控 API 用量；
• 尊重限流与共享基础设施。

十、重要限制

基准测试测的是标准化问题，未必反映你在以下场景的表现：

• 特定领域或研究主题；
• 复杂、多步骤的研究问题；
• 实时或近期信息类查询；
• 专业细分知识领域。

正确用法：把基准当作配置指导，然后用你的真实研究主题做小规模验证，再最终确定配置。整套系统的价值正在于此——正如原文档所总结的：基准测试系统帮助你找到可靠的起点配置，而非替你回答"我的场景能得多少分"。结合 examples/optimization 提供的多基准对比与 Optuna 优化示例，你可以在固定实验条件内系统化地收敛到最优配置组合。

【免费下载链接】local-deep-research~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.项目地址: https://gitcode.com/GitHub_Trending/lo/local-deep-research