W&B 集成

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

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

​

安装

pip install qitos[wandb]

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

---

​

快速上手

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）组合使用：

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：

from qitos.tracing import set_trace_processors

set_trace_processors([wandb_processor])

---

​

搭配预设设置 config

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

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：

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 清理步骤中）：

processor.shutdown()

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

​

force_flush()

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

processor.force_flush()

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