phoenix-harbor

Phoenix for Harbor

使用 Phoenix Harbor 插件，将 Harbor Agent 评估记录为带版本的 Phoenix 数据集、实验、运行、评分和 ATIF 跟踪。

Harbor 运行 Agent 和验证器。Phoenix 记录并比较其结果。请勿将 Phoenix 描述为执行 Harbor 任务或重新计算 Harbor 奖励。

要求

• Python 3.12 或更高版本
• Harbor 0.21.0 或更高版本
• 安装了 harbor 额外组件的 arize-phoenix-client
• Phoenix 服务 15.0 或更高版本

在同一个 Python 环境中安装客户端和 Harbor：

uv pip install "arize-phoenix-client[harbor]"

选择跟踪模式

除非 Agent 没有 ATIF 轨迹，或用户不需要跟踪，否则请使用 atif。atif 是默认模式。它会在最终试验尝试结束后读取轨迹文件，因此沙箱无需 Phoenix 端点、凭据、插桩或出站网络访问。

使用 null 记录数据集、实验、运行和评估，但不记录跟踪：

--plugin-kwarg trace_mode=null

实时 OpenTelemetry Protocol（OTLP）支持将推迟到后续版本。本次发布支持 atif 或 null，不会将实时 OpenTelemetry Agent 跟踪关联到实验运行。

设置 Phoenix 目标地址

为 Phoenix 插件进程设置端点。ATIF Agent 及其沙箱不会连接到 Phoenix。建议使用环境变量，以免凭据进入 shell 历史记录或作业配置：

export PHOENIX_COLLECTOR_ENDPOINT=http://localhost:6006
export PHOENIX_API_KEY=your-api-key

如果 Phoenix 实例不需要身份验证，请省略 PHOENIX_API_KEY。当用户要求按作业设置时，插件 kwargs 中的 endpoint 和 api_key 会覆盖这些值。

添加插件

在用户现有的 harbor run 命令中添加 --plugin arize-phoenix。保留其数据集、Agent、模型、环境、并发、重试和任务选择设置。

harbor run \
  -d terminal-bench/terminal-bench-2 \
  -a terminus-2 \
  -m openai/gpt-5-mini \
  --plugin arize-phoenix \
  --yes

请勿编造或替换与 Phoenix 无关的 Harbor 设置。

预测 Phoenix 记录

说明作业或检查结果时，请使用以下映射：

Harbor	Phoenix
一个任务集合	一个带版本的数据集
一个任务	一个数据集示例
一种不同的 Agent 和模型配置	一个实验
一次计划中的任务尝试	一次重复
一个最终逻辑试验	一个实验运行
Agent 最终的文本轮次	实验运行输出
最终验证器奖励	使用原始键和 CODE 注释器类型的实验评估
步骤验证器奖励	名为 <step_name>.<reward_key> 的评估
试验或步骤异常	运行错误和 infra_ok=0
已保存的 ATIF 轨迹	一个与运行关联的跟踪；多步骤任务中，每个已尝试步骤对应一个步骤跨度

每个单步或多步骤 Harbor 任务都会成为一个 Phoenix 数据集示例。多步骤示例的输入包含按顺序排列的步骤名称和说明。除非任务声明了参考文件，否则 Phoenix 示例的 output 保持为空。

插件只记录逻辑试验的最终物理尝试。Harbor 将重试的尝试不会创建 Phoenix 运行。完成顺序不会决定重复编号。

如果已保存的最终 ATIF 轨迹以面向用户的 Agent 文本轮次结束，插件会以聊天消息格式记录该轮次，以便 Phoenix 实验比较以 Markdown 格式呈现。结构化消息会按顺序纳入其文本部分；媒体部分会被省略。对于缺失或无效的轨迹、以工具调用结束的轮次、仅含媒体的轮次以及仅含状态的任务，输出保持为空。多步骤任务使用最后一次尝试的步骤，继续的轨迹使用最终延续部分。即使 trace_mode=null，仍会提取输出；该设置禁用的是跟踪创建，而非结果显示。

由旧版插件写入的成功运行会保留其旧版 Harbor 元数据输出，因为 Phoenix 运行不可变。恢复操作会识别这种确切的旧版格式并复用该运行。

添加可选的参考输出

任务可以在根目录的 task.toml 中声明一个已纳入版本控制的参考文件：

[metadata.arize-phoenix]
reference_output_path = "tests/expected.json"

插件会在设置期间读取此 UTF-8 JSON 文件。JSON 字符串会转换为 {"messages": [{"role": "assistant", "content": "the reference text"}]}。 JSON 对象会原样存储为示例输出。其他顶层类型必须包装在对象中。未设置时，输出为空，即使存在 expected.json 文件也是如此。

路径相对于 Harbor 主机上下载的任务根目录。绝对路径、.. 组件以及指向该根目录之外的符号链接都会被拒绝。已配置的文件若缺失、不可读或无效，则会在试运行开始前导致设置失败。请将参考文件与验证器资源放在一起，并置于 Agent 工作区之外。

此功能适用于本地数据集、直接任务和已发布任务。多步骤任务只有一个适用于整个任务的参考，通常是预期的最终结果。参考内容变更会创建数据集版本；现有实验会保留原有版本。参考内容不会改变 Harbor 的评分。

命名数据集

对于每种受支持的单一来源任务，插件都会推断 Phoenix 数据集名称。仅当一个任务作业包含多个没有共享集合名称的直接任务，或你想自定义数据集在 Phoenix 中的显示名称时，才提供 dataset=<name>。

推断的名称如下：

Harbor 来源	Phoenix 数据集名称
命名注册表数据集	所选的数据集名称
已发布的软件包	所选的 <organization>/<dataset> 名称
本地数据集路径	解析后的目录名称
仓库数据集	解析后的注册表元数据名称
一个直接任务	harbor-task/<task-name>

若要为多个直接任务命名或覆盖推断出的名称，请将此设置添加到 Harbor 命令中：

--plugin-kwarg dataset=release-candidate-tasks

如果任务作业存在任何不受支持的来源结构，请停止并说明限制：

• 配置了多个数据集；
• 同时配置了数据集和直接任务；
• 存在多个直接任务但未设置 dataset=<name>；
• 任务 ID 重复；或
• 属于重新评分任务作业，或其他根据先前 Harbor 结果生成的任务作业。

任务作业开始时，插件会同步完整的已解析任务集合。集合未发生变化时会复用数据集版本。添加、移除任务或任务内容发生变化时会创建新版本。现有实验会固定使用其创建时的数据集版本。

命名实验

默认模板为：

{job.name} · {agent.name} · {agent.model}

对于一种 Agent 配置，可以使用精确名称：

--plugin-kwarg experiment_name=release-candidate

对于多种 Agent 配置，请使用 experiment_name_template。可用字段如下：

• {job.name}
• {job.id}
• {dataset.name}
• {agent.name}
• {agent.model}
• {agent.short_digest}

Agent 名称不需要唯一。两个 Agent 即使名称相同，只要有效配置不同，也会分别创建实验。如果渲染后的名称冲突，插件会追加 Agent 的短摘要。稳定身份取决于 Harbor 任务作业 ID 和有效 Agent 配置，而非显示名称。

解读分数

请将行为结果与执行健康状况分开。Phoenix 不会运行另一个评估器。插件会将 Harbor 已完成的验证器奖励记录为带有 CODE 标注器类型的命名实验评估。

评估	说明
reward	仅当最终 Harbor 验证器输出字面键 reward 时才会出现。值为 0 表示行为失败，而非基础设施错误。
infra_ok	每次运行都会出现。1 表示 Harbor 记录的试验或步骤均未发生异常。0 表示至少发生了一次异常。
<reward_key>	特定任务的最终验证器分数，保留其原始数值范围。
<step_name>.<reward_key>	特定任务的步骤分数，用于多步骤诊断。

不要根据另一个孤立键推断 reward。在计算跨任务汇总数据前，请检查其覆盖率。

一次运行可能包含奖励，同时 infra_ok=0。Harbor 可能在发生步骤异常之前或同时生成验证器输出。解释结果时，请同时保留这两项事实。

对于多步骤任务，试验级奖励评估会包含 multi_step_reward_strategy 元数据。Harbor 省略的默认值会解析为 mean；如果明确指定了 final，则保留该值。步骤评估和 infra_ok 不包含此字段。

进行比较时：

1. 检查包含 reward 的运行所占比例。
2. 比较行为已完成运行中的 reward。
3. 比较 infra_ok，以发现环境、超时、Agent 进程或验证器可靠性问题。
4. 使用步骤分数和关联的跟踪记录，定位任务中的失败位置。

解读 ATIF 跟踪记录

一个逻辑试验对应一个跟踪记录和一个 Phoenix 会话。跟踪记录以插件拥有的 harbor.trial CHAIN span 开始。多步骤试验会为每个已尝试的步骤添加一个 harbor.step span：

harbor.trial <task>                  CHAIN
  harbor.step 1 <step name>          CHAIN, multi-step trials only
    <agent>                          AGENT
      turn 1                         AGENT, multi-turn trajectories only
        iteration 1                  CHAIN
          <model>                    LLM
          <tool>                     TOOL
            <subagent>               AGENT

单步轨迹直接附加到试验根 span。每个多步骤 harbor.step span 都包含其指令、计时信息、异常状态以及任何验证器奖励。即使轨迹缺失，步骤仍会显示。所有步骤 span 和轨迹都共享试验根 span。

Agent、模型和工具 span 使用其 ATIF 名称。全新的 Agent 操作使用 iteration N；上下文管理操作使用 compaction N；其他操作性系统步骤使用 system event N。多轮轨迹会添加 turn N span。llm_call_count: 0 的步骤会保留其操作和工具 span，但不会创建 LLM span。延续根 span 使用 <agent> (continuation N)。

转换器支持 ATIF v1.0 到 v1.7。它会根据 ATIF 重建 LLM 输入，并将其标记为 metadata.atif.input_source = "reconstructed"。复制的提示词历史会纳入这些输入，但不会创建 span。只有在 source_call_id 匹配时，它才会将观察结果与工具调用配对。多个结果会按顺序保留。未匹配的步骤观察结果会保留在操作 span 上；未分配的反馈会在重建的输入中保持结构化，不会臆造角色或工具关联。结构化文本和图像部分仍会序列化，但不会上传媒体字节。ATIF v1.8 音频字段不受支持。

只有 LLM span 会携带 llm.* 属性。轨迹 final_metrics 会保留在 Agent 根元数据中，以避免重复计算令牌。存在特定生成器的缓存写入和推理令牌计数时，会将其映射到对应的 OpenInference 令牌详细信息属性。

ATIF 时间戳表示时间点事件。零时长的 LLM 或 TOOL span 可能表示无法确定明确的时长。不要将其解读为该操作没有耗时的证据。声明的工具顺序不能证明操作是串行执行的。

ATIF 发现和转换采用尽力而为的方式。如果轨迹缺失或无效，插件会发出警告并记录运行，但不记录跟踪记录。之后的重放无法将跟踪记录附加到不可变的成功运行上。

处理失败并恢复

选择该插件后，Phoenix 记录必须成功。

• 设置失败会在试验运行前停止作业。
• 运行或评估写入失败会停止作业。已记录的试验会保留在 Phoenix 中。
• Harbor 会保留终态结果，供插件在恢复时摄取。
• ATIF 转换或上传失败不会停止作业。运行会被记录，但不包含跟踪信息。

顺序恢复和重放会复用匹配的数据集、实验、成功的运行、评估和跟踪信息。失败的运行可以重试。如果另一个作业创建了共享数据集的较新版本，请恢复原始实验，并固定使用该实验创建时的数据集版本。请勿为同一个 Harbor 作业运行多个摄取器，因为跨进程的实验恢复不是原子操作。

如果 Phoenix 报告冲突，请勿告诉用户忽略冲突。该插件会验证已存储运行的试验输出和跟踪标识。若两者不匹配，则需要创建新的 Harbor 作业，或解决冲突的 Phoenix 记录。

当前限制

该插件不支持：

• Harbor 重新评分作业，以及其他基于先前 Harbor 结果的作业；
• 对已完成的作业进行事后摄取；
• 实时 OTLP 跟踪关联，该功能将留待后续实现；
• 在一个作业中配置多个数据集；
• 混合配置的数据集和直接任务；或
• 并发摄取同一个 Harbor 作业。

公开指南请参阅 Phoenix 的 Harbor 文档。有关 Harbor 命令和任务配置，请参阅 Harbor 文档。