> ## Documentation Index
> Fetch the complete documentation index at: https://qitor.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# GAIA

> 通过 `GaiaAdapter` 与 ReAct 网页研究智能体，在 QitOS 上运行 GAIA 基准测试。

GAIA（通用 AI 助手）是一个真实世界任务基准测试，覆盖多步推理、网页研究、文件检查与算术能力。任务分成三个难度等级，通过与参考答案做精确匹配来评分。

QitOS 提供 `GaiaAdapter` 将 GAIA 数据行转换为标准 `Task`。官方执行入口是 `qit bench run`，而 `examples/benchmarks/gaia_eval.py` 现在只是同一套官方结果契约上的薄封装。

## 准备工作

<Steps>
  <Step title="安装基准测试依赖">
    ```bash theme={null}
    pip install "qitos[benchmarks]"
    ```
  </Step>

  <Step title="认证 HuggingFace">
    GAIA 是受限数据集。先在 [huggingface.co/datasets/gaia-benchmark/GAIA](https://huggingface.co/datasets/gaia-benchmark/GAIA) 申请访问，再设置：

    ```bash theme={null}
    export HF_TOKEN="hf_..."
    ```
  </Step>

  <Step title="设置模型 API key">
    ```bash theme={null}
    export OPENAI_API_KEY="sk-..."
    export OPENAI_BASE_URL="https://api.siliconflow.cn/v1/"
    ```
  </Step>
</Steps>

## 加载任务

```python theme={null}
from qitos.benchmark import GaiaAdapter

adapter = GaiaAdapter()
records = adapter.load_huggingface_records(split="validation")
tasks = adapter.to_tasks(records, split="validation", limit=10)
```

也可以使用一行式加载器：

```python theme={null}
from qitos.benchmark.gaia.adapter import load_gaia_tasks

tasks = load_gaia_tasks(split="validation", limit=20)
```

如果你已经下载了本地快照，也可以从磁盘加载，避免重复请求 HuggingFace。

## 运行评测

优先使用官方命令行：

```bash theme={null}
qit bench run \
  --benchmark gaia \
  --split validation \
  --limit 50 \
  --root data/gaia \
  --output results/gaia_validation.jsonl \
  --model-name "Qwen/Qwen3-8B"
```

然后继续做聚合与检查：

```bash theme={null}
qit bench eval --input results/gaia_validation.jsonl --json
qita board --logdir runs
```

如果你想看基准测试专用的参考封装器，再使用 `examples/benchmarks/gaia_eval.py`。

运行单个任务：

```bash theme={null}
python examples/benchmarks/gaia_eval.py \
  --gaia-split validation \
  --gaia-index 0 \
  --max-steps 16 \
  --model-name "Qwen/Qwen3-8B" \
  --api-key "$OPENAI_API_KEY"
```

运行完整基准测试：

```bash theme={null}
python examples/benchmarks/gaia_eval.py \
  --run-all \
  --gaia-split validation \
  --limit 50 \
  --concurrency 4 \
  --output-jsonl results/gaia_validation.jsonl \
  --trace-logdir runs \
  --model-name "Qwen/Qwen3-8B" \
  --api-key "$OPENAI_API_KEY"
```

## 智能体结构

评测脚本会构造一个 ReAct 风格的网页研究智能体，通常组合：

* 浏览器工具
* 文件读取
* 命令执行
* `ReActTextParser`

由于适配器产出的还是标准 `Task`，你也可以替换成自己的 `AgentModule`。

## 检查结果

GAIA 结果文件通常包含：

* `task_id`
* `question`
* `reference_answer`
* `prediction`
* `stop_reason`
* `steps`
* `latency_seconds`
* `trace_run_dir`

然后直接用 `qita` 检查：

```bash theme={null}
qita board --logdir runs
qita replay --run runs/<run_id>
```