> ## 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.

# W&B 集成

> 将 QitOS 运行指标流式传输到 Weights & Biases 进行实验追踪与可视化。

`WandbTraceProcessor` 实现了 `TraceProcessor` 抽象基类，可将 QitOS 运行数据流式传输到 Weights & Biases 项目。挂载后，它会在运行过程中自动记录每个 span 的指标，并在 trace 结束时写入最终汇总。

## 安装

```bash theme={null}
pip install qitos[wandb]
```

该命令会将 `wandb` SDK 作为可选依赖安装。若未安装，导入 `WandbTraceProcessor` 会抛出 `ImportError`。

***

## 快速上手

```python theme={null}
from qitos.tracing import add_trace_processor
from qitos.tracing.wandb_processor import WandbTraceProcessor

processor = WandbTraceProcessor(
    project="my-qitos-runs",
    name="gaia-eval-001",
    tags=["benchmark", "gaia"],
    config={"model": "gpt-4o", "max_steps": 15},
)
add_trace_processor(processor)

result = agent.run(task="...", return_state=True)
```

运行开始时，`WandbTraceProcessor` 会使用传入的参数调用 `wandb.init()`。当 trace 结束时（正常结束或出错），它会写入汇总并默认调用 `wandb.finish()`。

***

## 构造参数

| 参数            | 类型                  | 默认值       | 说明                                 |
| ------------- | ------------------- | --------- | ---------------------------------- |
| `project`     | `str`               | `"qitos"` | 传给 `wandb.init` 的 W\&B 项目名         |
| `name`        | `str \| None`       | `None`    | W\&B 运行名称。若未指定则使用 QitOS trace 名称   |
| `config`      | `dict \| None`      | `None`    | 传给 `wandb.init` 的 `config` 字典      |
| `tags`        | `list[str] \| None` | `None`    | W\&B 运行的标签列表                       |
| `entity`      | `str \| None`       | `None`    | W\&B 实体（用户或团队）                     |
| `auto_finish` | `bool`              | `True`    | 是否在 trace 结束时自动调用 `wandb.finish()` |

***

## 记录的指标

### 逐 span 指标

处理器拦截 span 结束事件，在运行过程中增量记录指标。

| Span 类型              | 记录的指标                                                                                                  |
| -------------------- | ------------------------------------------------------------------------------------------------------ |
| `GenerationSpanData` | `generation/prompt_tokens`、`generation/completion_tokens`、`generation/total_tokens`、`generation/model` |
| `StepSpanData`       | `step/number`                                                                                          |
| `CriticSpanData`     | `critic/score`、`critic/name`                                                                           |
| `ToolSpanData`       | `tool/name`                                                                                            |
| `ActSpanData`        | `action/name`                                                                                          |

每次 `wandb.log()` 调用都会递增内部步数计数器，使 W\&B 时序图表与智能体的运行进程对齐。

### 最终汇总

当 trace 结束时，处理器将聚合指标写入 `run.summary`：

| 汇总键                | 说明                                                  |
| ------------------ | --------------------------------------------------- |
| `total_tokens`     | 所有 generation span 的 prompt + completion 累计 token 数 |
| `total_steps`      | 处理的 step span 数量                                    |
| `total_tool_calls` | tool 和 action span 的总数                              |
| `critic/avg_score` | 所有 critic 分数的平均值（仅在有分数时记录）                          |
| `critic/min_score` | 最低 critic 分数                                        |
| `critic/max_score` | 最高 critic 分数                                        |
| `stop_reason`      | 从 trace 元数据中提取的运行停止原因                               |

***

## 与其他处理器组合

`add_trace_processor` 会将处理器追加到全局列表，因此可以将 `WandbTraceProcessor` 与其他 `TraceProcessor`（例如默认写入磁盘的 `LegacyTraceWriterProcessor`）组合使用：

```python theme={null}
from qitos.tracing import add_trace_processor
from qitos.tracing.wandb_processor import WandbTraceProcessor

wandb_processor = WandbTraceProcessor(
    project="my-qitos-runs",
    config={"model": "gpt-4o"},
)
add_trace_processor(wandb_processor)

# 默认的文件 trace 写入器仍然生效
result = agent.run(task="...", return_state=True)
```

若要替换所有处理器（移除默认写入器），请使用 `set_trace_processors`：

```python theme={null}
from qitos.tracing import set_trace_processors

set_trace_processors([wandb_processor])
```

***

## 搭配预设设置 config

家族预设（family preset）提供推荐的模型参数。可利用它们填充 W\&B 的 `config` 字典，让 W\&B 面板反映智能体实际使用的设置：

```python theme={null}
from qitos.harness import resolve_family_preset
from qitos.tracing import add_trace_processor
from qitos.tracing.wandb_processor import WandbTraceProcessor

preset = resolve_family_preset("qwen")

processor = WandbTraceProcessor(
    project="qwen-experiments",
    config={
        "model": preset.model_id,
        "max_steps": preset.recommended_max_steps,
        "max_tokens": preset.recommended_max_tokens,
    },
    tags=[preset.family],
)
add_trace_processor(processor)

result = agent.run(task="...", return_state=True)
```

***

## 生命周期控制

### auto\_finish

默认 `auto_finish=True`，处理器会在 `on_trace_end` 触发时自动调用 `wandb.finish()`。如果需要在 QitOS trace 结束后继续向同一 W\&B 运行写入自定义指标，可设置 `auto_finish=False`：

```python theme={null}
import wandb
from qitos.tracing import add_trace_processor
from qitos.tracing.wandb_processor import WandbTraceProcessor

processor = WandbTraceProcessor(
    project="my-qitos-runs",
    auto_finish=False,
)
add_trace_processor(processor)

result = agent.run(task="...", return_state=True)

# 向同一 W&B 运行写入额外的自定义指标
wandb.log({"custom/accuracy": 0.92})

wandb.finish()
```

### shutdown()

调用 `shutdown()` 可提前关闭 W\&B 运行（例如在 `SIGTERM` 信号处理或 notebook 清理步骤中）：

```python theme={null}
processor.shutdown()
```

如果运行处于活跃状态且 `auto_finish` 为 `True`，它会调用 `wandb.finish()`。该方法可安全地多次调用。

### force\_flush()

调用 `force_flush()` 可确保所有缓冲指标已写入 W\&B 后端：

```python theme={null}
processor.force_flush()
```

该方法会在当前步数计数器处记录一条空记录，触发 W\&B 内部缓冲区的刷新。