> ## Documentation Index
> Fetch the complete documentation index at: https://opencompass-docs-preview-pr-335-0.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# DeepResearch Bench

DeepResearch Bench（[arXiv](https://arxiv.org/abs/2506.11763)）用于评测深度研究 agent 撰写研究报告的能力：给定一个需要联网检索、多步取证的开放式研究查询，agent 产出一份完整的 Markdown 研究报告，再由 **RACE** 与 **FACT** 两套框架分别评定报告质量与引用事实性。数据集共 **100 条任务**（中文、英文各 50 条），由领域专家撰写，覆盖 22 个主题。

## 工作原理

DeepResearch Bench 一次运行分为推理与打分两个阶段。打分阶段包含 RACE 与 FACT 两套彼此独立的框架，通过 `metrics` 选择运行其中一套或两套。

### 推理与打分

* **推理**：被测 model 作为研究 agent，在 Harness（默认 [`naive_search_agent`](/zh/user_guide/modules/harnesses/naive_search_agent)）驱动下逐题完成搜索 / 网页访问等多轮工具循环，最终产出一份 Markdown 研究报告作为该任务的作答。
* **打分**：RACE 由评委 model（`judge_model`）将被测报告与一份参考报告逐条比对，评定报告质量；FACT 由 `fact_judge_model` 配合 Jina Reader 抓取被引网页，核查报告中的引用是否支持其论断。评委与被测 model 是两个独立端点，须显式指定 `judge_model`。

官方仅发布评测器，不规定推理侧的任何约束（工具、轮数、篇幅均不限），其排行榜成绩来自各家深度研究产品的真实输出。因此本 Benchmark 的成绩仅在 **Harness、Harness 配置、评委 model 三者一致** 的运行之间具有横向可比性，引用成绩时应一并记录这三项。

<a id="引用格式要求" />

### 附加的引用格式要求

FACT 只能核查报告中确实写出的引用，而 agent 仅收到一个查询时，产出的报告往往通篇不含 URL——此类报告的 FACT 成绩为零，并不反映其真实的引用能力。因此在 `require_citations` 为默认值 `true` 时，查询之后会追加一段引用格式要求（中英文各一版，按任务语言选用）：

```text theme={"system"}
请交付一份完整的 Markdown 研究报告。
- 每一处非显然的论断都要在其所在句子之后内联标注引用，格式为 [来源标题](https://来源链接)，
  链接必须是你实际检索到的真实 URL。
- 报告末尾附上所引用来源的编号列表。
```

该要求仅追加在发往被测 model 的提示词上，**RACE 评委读到的始终是原始查询**，因此 `instruction_following` 评定的是任务本身的要求，而非此处附加的要求。`[标题](url)` 也是官方抽取器原生支持的四种引用写法之一，并非本集成新增的格式。置 `require_citations: false` 即退回官方行为，仅发送原始查询。

### RACE：基于参考报告的相对评分

RACE 不给绝对分。每条任务随数据集提供一份由强力深度研究产品撰写的参考报告，以及一棵带权重的评分标准树。打分分两步：

* **清洗**：先移除被测报告中的引用标记、参考文献列表与脚注，使评委比对正文而非参考书目。篇幅超出单次调用的报告按段落边界切块并发清洗。参考报告随数据集提供已清洗版本，无需重复处理。置 `skip_cleaning: true` 可跳过此步，直接评定原始报告。
* **判题**：单次调用内，评委依据每一条评分标准分别为两篇报告打 0-10 分。逐条分数先按评分标准权重折算为四个维度分，再按维度权重合成任务总分。

最终上报的是比值 `target / (target + reference)`：`0.5` 表示与参考报告打平，大于 `0.5` 表示优于参考报告，小于 `0.5` 表示不及参考报告。四个维度——完整性（覆盖面）、洞察力（洞察深度）、instruction\_following（指令遵循）、可读性——按同一比值分别上报。必需 Judge 请求或评分协议失败报告 FATAL，并使用共享评测重试预算。最终 FATAL 使整题失效且不发布 run 的正式分数；有效题可贡献明确标注的参考分。

### FACT：引用事实性核查

FACT 核查报告中每一处引用是否真的支持其所在的论断，四个阶段均在保留引用标记的原始报告上进行：

* **抽取**：从正文提取 `(fact, ref_idx, url)` 三元组，`[标题](url)`、`[15]`、`正文 15`、`[15†L10]` 四种引用写法均可识别。
* **去重**：按 URL 分组，组内表述几乎一致的陈述合并为一条。
* **抓取**：每个唯一 URL 由 Jina Reader 抓取。抓取结果缓存于 AgentCompass 数据根目录下，可跨运行复用（`scrape_cache`）。
* **校验**：逐条判定陈述相对该网页为 `supported`、`unsupported` 或 `unknown`。

两条剔除规则与官方一致：判为 `unknown` 的陈述（链接失效、付费墙、页面不存在）从分子与分母中同时剔除；完全抽不出引用的报告整篇排除在 FACT 均值之外，而非记 0 分。

## 参数

通过 `--benchmark-params '{...}'` 传入一段 JSON；也可写进 `--config` 指定 YAML 的 `benchmark.params` 块，同名项以命令行为准。合并与优先级见 [Benchmark 概览](/zh/user_guide/modules/benchmarks/overview)。

<a id="参数总览" />

### 参数总览

<div style={{overflowX:'auto'}}>
  <table style={{minWidth:'1040px', width:'100%'}}>
    <colgroup>
      <col width="18%" />

      <col width="16%" />

      <col width="15%" />

      <col width="20%" />

      <col width="31%" />
    </colgroup>

    <thead>
      <tr><th style={{whiteSpace:'nowrap'}}>参数</th><th style={{whiteSpace:'nowrap'}}>类型</th><th style={{whiteSpace:'nowrap'}}>默认值</th><th>可选值 / 取值</th><th>说明</th></tr>
    </thead>

    <tbody>
      <tr><td style={{whiteSpace:'nowrap'}}><code>judge\_model</code></td><td style={{whiteSpace:'nowrap'}}>字典</td><td style={{whiteSpace:'nowrap'}}><code>null</code></td><td><code>id</code>, <code>base\_url</code>, <code>api\_key</code>, <code>api\_protocol</code>, <code>params</code></td><td>评委 model 配置，<strong>必填</strong>（见 <a href="#评委 model-spec">评委 model 配置</a>）。RACE 判分由它裁定，非命令行的 <code>--model-\*</code>；同时作为清洗与 FACT 阶段的默认 model。</td></tr>
      <tr><td style={{whiteSpace:'nowrap'}}><code>metrics</code></td><td style={{whiteSpace:'nowrap'}}>列表</td><td style={{whiteSpace:'nowrap'}}><code>\["race", "fact"]</code></td><td><code>race</code>、<code>fact</code> 或二者</td><td>运行哪几套打分框架。默认两套均运行，与官方 <code>run\_benchmark.sh</code> 一致；仅评定报告质量时置为 <code>\["race"]</code>。</td></tr>
      <tr><td style={{whiteSpace:'nowrap'}}><code>jina\_api\_key</code></td><td style={{whiteSpace:'nowrap'}}>字符串</td><td style={{whiteSpace:'nowrap'}}><code>\$JINA\_API\_KEY</code></td><td>Jina Reader 密钥</td><td>供 FACT 抓取被引网页。除 <code>metrics</code> 为 <code>\["race"]</code> 外<strong>必填</strong>，缺失时在构建配置阶段即报错。</td></tr>
      <tr><td style={{whiteSpace:'nowrap'}}><code>fact\_judge\_model</code></td><td style={{whiteSpace:'nowrap'}}>字典</td><td style={{whiteSpace:'nowrap'}}><code>null</code></td><td>同 <code>judge\_model</code></td><td>FACT 各阶段的评委；不填则回落到 <code>judge\_model</code>。</td></tr>
      <tr><td style={{whiteSpace:'nowrap'}}><code>cleaning\_model</code></td><td style={{whiteSpace:'nowrap'}}>字典</td><td style={{whiteSpace:'nowrap'}}><code>null</code></td><td>同 <code>judge\_model</code></td><td>判题前执行清洗的 model；不填则回落到 <code>judge\_model</code>。</td></tr>
      <tr><td style={{whiteSpace:'nowrap'}}><code>language</code></td><td style={{whiteSpace:'nowrap'}}>字符串</td><td style={{whiteSpace:'nowrap'}}><code>"all"</code></td><td><code>all</code> / <code>zh</code> / <code>en</code></td><td>按查询语言筛选任务；<code>all</code> = 不过滤。中英各 50 条。</td></tr>
      <tr><td style={{whiteSpace:'nowrap'}}><code>category</code></td><td style={{whiteSpace:'nowrap'}}>字符串 / 列表</td><td style={{whiteSpace:'nowrap'}}><code>"all"</code></td><td><code>"all"</code>、单个主题名、或主题名列表（22 个见下方）</td><td>按主题筛选任务；<code>"all"</code> = 不过滤。传入列表时取并集。</td></tr>
      <tr><td style={{whiteSpace:'nowrap'}}><code>require\_citations</code></td><td style={{whiteSpace:'nowrap'}}>布尔值</td><td style={{whiteSpace:'nowrap'}}><code>true</code></td><td><code>true</code> / <code>false</code></td><td>是否在查询后追加引用格式要求（见 <a href="#引用格式要求">附加的引用格式要求</a>）。置 <code>false</code> 时仅发送原始查询，FACT 通常无内容可核查。</td></tr>
      <tr><td style={{whiteSpace:'nowrap'}}><code>skip\_cleaning</code></td><td style={{whiteSpace:'nowrap'}}>布尔值</td><td style={{whiteSpace:'nowrap'}}><code>false</code></td><td><code>true</code> / <code>false</code></td><td>跳过清洗，直接评定原始报告。每条任务少一次 LLM 调用，但成绩会随之偏移。</td></tr>
      <tr><td style={{whiteSpace:'nowrap'}}><code>pass\_threshold</code></td><td style={{whiteSpace:'nowrap'}}>浮点数</td><td style={{whiteSpace:'nowrap'}}><code>0.5</code></td><td><code>0.0</code>-<code>1.0</code></td><td>任务记为 <code>passed=true</code> 所需的最低当前主分数。启用 RACE 时，默认值表示「打平或优于参考报告」；仅启用 FACT 时，则表示引用准确率至少为 50%。</td></tr>
      <tr><td style={{whiteSpace:'nowrap'}}><code>max\_retries</code></td><td style={{whiteSpace:'nowrap'}}>整数</td><td style={{whiteSpace:'nowrap'}}><code>10</code></td><td><code>≥ 1</code></td><td>单次 RACE 判题的重试预算，覆盖 JSON 不可解析与维度缺失两类失败。</td></tr>
      <tr><td style={{whiteSpace:'nowrap'}}><code>scrape\_cache</code></td><td style={{whiteSpace:'nowrap'}}>布尔值</td><td style={{whiteSpace:'nowrap'}}><code>true</code></td><td><code>true</code> / <code>false</code></td><td>是否将抓取到的网页缓存于数据根目录下并跨运行复用。</td></tr>
      <tr><td style={{whiteSpace:'nowrap'}}><code>max\_urls</code></td><td style={{whiteSpace:'nowrap'}}>整数</td><td style={{whiteSpace:'nowrap'}}><code>0</code></td><td><code>0</code> = 不限</td><td>单条任务最多核查的唯一 URL 数。非零值可控制成本，但会丢弃部分引用，丢弃量写入日志。</td></tr>
      <tr><td style={{whiteSpace:'nowrap'}}><code>max\_url\_content\_chars</code></td><td style={{whiteSpace:'nowrap'}}>整数</td><td style={{whiteSpace:'nowrap'}}><code>0</code></td><td><code>0</code> = 不截断</td><td>校验前将每个网页截断至该长度。</td></tr>
      <tr><td style={{whiteSpace:'nowrap'}}><code>clean\_concurrency</code></td><td style={{whiteSpace:'nowrap'}}>整数</td><td style={{whiteSpace:'nowrap'}}><code>4</code></td><td><code>≥ 1</code></td><td>单条任务内的清洗并发数，仅在长报告被切块时生效。跨任务并发由 <code>--task-concurrency</code> 控制。</td></tr>
      <tr><td style={{whiteSpace:'nowrap'}}><code>scrape\_concurrency</code></td><td style={{whiteSpace:'nowrap'}}>整数</td><td style={{whiteSpace:'nowrap'}}><code>4</code></td><td><code>≥ 1</code></td><td>单条任务内的 Jina Reader 并发抓取数。</td></tr>
      <tr><td style={{whiteSpace:'nowrap'}}><code>fact\_llm\_concurrency</code></td><td style={{whiteSpace:'nowrap'}}>整数</td><td style={{whiteSpace:'nowrap'}}><code>4</code></td><td><code>≥ 1</code></td><td>单条任务内的 FACT 判题并发数，覆盖抽取、去重、校验三个阶段。</td></tr>
    </tbody>
  </table>
</div>

`sample_ids` 等共享 Benchmark 字段遵循 [Benchmark 参数](/zh/user_guide/modules/benchmarks/overview) 的约定。DeepResearchBench 声明标量主指标 `score`、二元辅助指标 `passed`，并将 RACE 各维度和引用统计作为辅助标量观测。`k>1` 时应使用 `avg` 执行策略；标量主指标选择 `pass` 会在预检时报错，详见[指标与聚合](/zh/user_guide/other_features/results/metrics_aggregation)。

<Accordion title="category 全部 22 个可取值（点击展开）">
  `Science & Technology`（16）、`Finance & Business`（14）、`Software Development`（10）、`Education & Jobs`（8）、`Health`（8）、`Literature`（4）、`History`（4）、`Hardware`（4）、`Industrial`（4）、`Art & Design`（4）、`Games`（2）、`Crime & Law`（2）、`Entertainment`（2）、`Sports & Fitness`（2）、`Software`（2）、`Transportation`（2）、`Religion`（2）、`Home & Hobbies`（2）、`Travel`（2）、`Food & Dining`（2）、`Fashion & Beauty`（2）、`Social Life`（2）。括号内为该主题的任务数（合计 100，中英各半）。大小写与空格需精确匹配。
</Accordion>

<a id="评委 model-spec" />

### 评委 model 配置

`judge_model` 以字典形式传入，包含 `id`、`base_url`、`api_key`、`api_protocol` 和 `params`，指向评委 model 的独立端点，model 推理参数放在 `params` 下。

建议 **固定使用同一个评委** 评测所有被测 model。RACE 判分是影响成绩最大的单一因素，更换评委后成绩即失去横向可比性；同时不应让被测 model 充当自身的评委，否则既不公正也失去对照意义。与 DeepSearchQA 等判据相对客观的 Benchmark 不同，RACE 评委还需具备 **足够大的上下文窗口**：单次判题须同时装入两篇完整研究报告与全部评分标准，通常超过 100k 词元；评委若直接拒绝该请求，将耗尽整个重试预算，该任务最终记为错误。

AgentCompass 推荐 `GLM-5.2`，RACE 与 FACT 共用。官方排行榜使用的是 RACE `gpt-5.5`、FACT `gpt-5.4-mini`，因此改用其他评委所得成绩可在内部横向对比，但不能直接与该排行榜对齐。

## 运行示例

`agentcompass run` 的三个位置参数依次为 Benchmark、Harness 和 Model；以下使用 `deepresearch_bench`、[`naive_search_agent`](/zh/user_guide/modules/harnesses/naive_search_agent) 和 `$MODEL_NAME`，运行环境为 [`host_process`](/zh/user_guide/modules/environments/providers/host_process)。

运行前，在当前终端设置以下环境变量：

* 被测 Model：`MODEL_NAME`、`MODEL_BASE_URL`、`MODEL_API_KEY`，设置方法见 [Model 接入配置](/zh/user_guide/modules/models/overview#配置连接信息)。
* 评委 Model：`JUDGE_MODEL_NAME`、`JUDGE_MODEL_BASE_URL`、`JUDGE_MODEL_API_KEY`，使用独立且固定的评委配置。
* 检索工具：`SERPER_API_KEY` 和 `JINA_API_KEY`，分别供 `search` 和 `visit` 使用。

配置归属与命令行覆盖规则见 [run 命令](/zh/user_guide/using_agentcompass/cli/run)。

`jina_api_key` 在两段配置中用途不同：Harness 用它支持 `visit` 工具，Benchmark 用它为 FACT 抓取被引网页。示例共用 `JINA_API_KEY`；只运行 RACE 时，agent 的网页阅读仍需要该密钥。

<Tabs>
  <Tab title="冒烟测试（单条跑通）">
    通过 `sample_ids` 仅评测一条任务，用于验证推理、RACE、FACT 的端到端流程是否正常，其余参数使用默认值。

    ```bash wrap theme={"system"}
    agentcompass run \
      deepresearch_bench \
      naive_search_agent \
      "$MODEL_NAME" \
      --env host_process \
      --benchmark-params '{
        "judge_model": {
          "id": "'"$JUDGE_MODEL_NAME"'",
          "base_url": "'"$JUDGE_MODEL_BASE_URL"'",
          "api_key": "'"$JUDGE_MODEL_API_KEY"'"
        },
        "jina_api_key": "${JINA_API_KEY}",
        "sample_ids": ["1"]
      }' \
      --harness-params '{
        "serper_api_key": "${SERPER_API_KEY}",
        "jina_api_key": "${JINA_API_KEY}"
      }' \
      --model-base-url "$MODEL_BASE_URL" \
      --model-api-key "$MODEL_API_KEY" \
      --model-api-protocol openai-chat
    ```
  </Tab>

  <Tab title="自定义参数">
    仅评测中文任务并跳过 FACT，便于聚焦报告质量；`metrics` 置为 `["race"]` 后无需为 FACT 配置 Jina；Harness 的 `visit` 工具仍使用 `JINA_API_KEY`。

    ```bash wrap theme={"system"}
    agentcompass run \
      deepresearch_bench \
      naive_search_agent \
      "$MODEL_NAME" \
      --env host_process \
      --benchmark-params '{
        "metrics": ["race"],
        "judge_model": {
          "id": "'"$JUDGE_MODEL_NAME"'",
          "base_url": "'"$JUDGE_MODEL_BASE_URL"'",
          "api_key": "'"$JUDGE_MODEL_API_KEY"'"
        },
        "language": "zh"
      }' \
      --harness-params '{
        "serper_api_key": "${SERPER_API_KEY}",
        "jina_api_key": "${JINA_API_KEY}"
      }' \
      --model-base-url "$MODEL_BASE_URL" \
      --model-api-key "$MODEL_API_KEY" \
      --model-api-protocol openai-chat \
      --task-concurrency 8
    ```
  </Tab>

  <Tab title="AgentCompass 推荐配置">
    评测全部中英文任务，同时运行 RACE 和 FACT。报告类任务的检索面比 QA 类宽，`max_iterations` 从默认的 50 放宽到 80，`max_tool_response_length` 提到 16384 以免 `visit` 工具摘要中的来源 URL 被截断；整份报告须在一次生成内写完，其长度上限由 `--model-params` 的 `max_tokens` 控制。RACE 和 FACT 默认共用 `judge_model`。

    ```bash wrap theme={"system"}
    agentcompass run \
      deepresearch_bench \
      naive_search_agent \
      "$MODEL_NAME" \
      --env host_process \
      --benchmark-params '{
        "judge_model": {
          "id": "'"$JUDGE_MODEL_NAME"'",
          "base_url": "'"$JUDGE_MODEL_BASE_URL"'",
          "api_key": "'"$JUDGE_MODEL_API_KEY"'"
        },
        "jina_api_key": "${JINA_API_KEY}"
      }' \
      --harness-params '{
        "serper_api_key": "${SERPER_API_KEY}",
        "jina_api_key": "${JINA_API_KEY}",
        "max_iterations": 80,
        "max_tool_response_length": 16384
      }' \
      --model-params '{
        "max_tokens": 32768
      }' \
      --model-base-url "$MODEL_BASE_URL" \
      --model-api-key "$MODEL_API_KEY" \
      --model-api-protocol openai-chat \
      --task-concurrency 8
    ```
  </Tab>
</Tabs>

<a id="输出" />

<a id="指标契约与聚合序列" />

<a id="单任务详情details" />

<a id="单任务详情" />

## 评测结果

通用结果说明见[运行目录](/zh/user_guide/other_features/results/overview#目录布局)、[汇总成绩](/zh/user_guide/other_features/results/summary_analysis)和[单题文件与公共字段](/zh/user_guide/other_features/results/task_results)。

### 评分指标

DeepResearchBench 的主指标是标量 `score`，取值为 0–1，越高越好。启用 RACE 时，它采用前文[相对评分](#race基于参考报告的相对评分)的 `overall_score`；仅启用 FACT 时，它采用引用准确率。切换评分模式后，主分数的含义也随之改变。

| 指标 | 类型与含义 |
| - | - |
| `score` | 标量主指标：当前评分模式的主分数。 |
| `passed` | 二元辅助指标：答案非空，且可用的主分数达到 `pass_threshold`。 |
| `overall_score` | RACE 标量总分；评分标准和维度权重在相对归一化前应用，不能用四个展示维度的平均值反推。 |
| `comprehensiveness` / `insight` / `instruction_following` / `readability` | RACE 的四项标量相对分，含义见前文 RACE 说明。 |
| `citation_accuracy` | FACT 引用准确率：受支持引用数 / 已核查引用数。 |
| `citations_checked` / `citations_supported` / `citations_total` | 标量计数：已核查、受支持和最初抽取的引用数。 |
| `fact_scored` | 0/1 标量标记：FACT 是否完成计分；FACT 报错时不产生该观测。 |

FACT 的整体 `citation_accuracy` 按引用数加权：先分别合计受支持和已核查引用数，再相除；仅启用 FACT 时，整体 `score` 也使用该公式。派生指标 `avg_citations` 和 `avg_effective_citations` 分别为已核查、受支持引用总数除以计分 FACT 任务数。

RACE 与 FACT 可能覆盖不同任务，不能假设它们共享分母。未抽取到引用（`no_citations_found`）的任务不参与 FACT 均值；抽取到引用但所有判定均为 `unknown` 的任务仍计入计分任务数，已核查引用数为 `0`。主指标为标量，因此不支持 `pass` 执行策略；辅助指标 `passed` 仅用于报告通过情况。

多次尝试、分类聚合和计分异常的通用处理见[指标与聚合](/zh/user_guide/other_features/results/metrics_aggregation)。

### 单题结果与评分依据

每次尝试的 `meta.benchmark` 下，`scoring` 保存 RACE 与 FACT 证据，以及实际使用的 `pass_threshold` 和可用时的 `passed` 判定。下表字段均相对于 `scoring`：

| 字段 | 含义 |
| - | - |
| `race.overall_score` 及四个维度 | 该任务的相对分 |
| `race.raw` | 归一化前两篇报告的加权和，以及经模糊匹配才对上的评分标准 |
| `race.cleaning` | `applied` 或 `skipped` |
| `race.article_chars` / `race.cleaned_article_chars` | 清洗前后的报告长度，可用于检查清洗是否异常缩短报告 |
| `race.judge_attempts` | 该任务实际消耗的判题调用次数 |
| `race.error` | RACE 评分失败的原因，例如 `cleaning_failed`、`judge_failed` 或 `scoring_failed` |
| `race.reason` / `fact.reason` | 空答案记录为 `empty_answer`，相应评分器不会调用评委 |
| `fact.n_citations` / `fact.unique_urls` | 抽出的引用三元组数与去重后纳入核查的 URL 数；`max_urls` 大于 `0` 时限制后者 |
| `fact.citations_checked` / `citations_supported` | 取得判定的陈述数，及其中受支持的数量 |
| `fact.scrape_failures` / `validate_failures` | 抓取失败的网页数，及始终未返回可用 JSON 的校验调用数 |
| `fact.citations` | 按 URL 组织的陈述、判定与错误，用于将成绩追溯至具体网页 |
| `fact.error` | 未取得有效 FACT 结果的原因，例如 `no_citations_found`、`extraction_failed` 或网页抓取、引用校验错误 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.