phoenix-harbor

Harbor 向け Phoenix

Phoenix Harbor プラグインを使用すると、Harbor エージェントの評価を、バージョン管理された Phoenix データセット、実験、実行、スコア、ATIF トレースとして記録できます。

Harbor はエージェントと検証器を実行します。Phoenix はその結果を記録して比較します。Phoenix が Harbor のタスクを実行したり、Harbor の報酬を再計算したりすると説明しないでください。

要件

• Python 3.12 以降
• Harbor 0.21.0 以降
• harbor extras を指定してインストールした arize-phoenix-client
• Phoenix サーバー 15.0 以降

クライアントと Harbor は同じ Python 環境にインストールしてください。

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

トレースモードを選択する

エージェントに ATIF の軌跡がない場合、またはユーザーがトレースを希望しない場合を除き、atif を使用してください。デフォルトは ATIF です。最終試行後に軌跡ファイルを読み取るため、サンドボックスに Phoenix エンドポイント、認証情報、計装、外部へのネットワークアクセスは必要ありません。

トレースなしでデータセット、実験、実行、評価を記録するには、null を使用してください。

--plugin-kwarg trace_mode=null

ライブの OpenTelemetry Protocol（OTLP）サポートは、後続リリースに延期されています。このリリースで使用できるのは atif または null であり、ライブの OpenTelemetry エージェントトレースを実験の実行に関連付けることはできません。

Phoenix の接続先を設定する

Phoenix プラグインプロセスのエンドポイントを設定してください。ATIF エージェントとそのサンドボックスは Phoenix に接続しません。認証情報がシェル履歴やジョブ設定に残らないよう、環境変数を使用してください。

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 を追加してください。データセット、エージェント、モデル、環境、並列実行数、再試行、タスクの選択はそのまま維持します。

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
1 つのタスクコレクション	1 つのバージョン管理されたデータセット
1 つのタスク	1 つのデータセット例
1 つの異なるエージェントとモデルの設定	1 つの実験
1 回の計画されたタスク試行	1 回の反復
1 つの最終的な論理試行	1 つの実験実行
エージェントの最終的なテキスト応答	実験実行の出力
最終的な検証器の報酬	元のキーと CODE annotator kind を含む実験評価
ステップ検証器の報酬	<step_name>.<reward_key> という名前の評価
試行またはステップの例外	実行エラーと infra_ok=0
保存された ATIF 軌跡	実行に関連付けられた 1 つのトレース。複数ステップのタスクでは、試行された各ステップに 1 つのステップスパンを記録

Harbor の各単一ステップまたは複数ステップのタスクは、Phoenix のデータセット例 1 件になります。複数ステップの例の入力には、順序付けられたステップ名と指示が含まれます。タスクで参照ファイルが指定されていない限り、Phoenix の例では output は空のままです。

このプラグインは、論理試行の物理試行のうち、最終試行のみを記録します。Harbor が再試行する試行は、Phoenix の実行を作成しません。完了順によって反復番号が決まることはありません。

保存された最終 ATIF 軌跡が、ユーザー向けのテキスト形式のエージェント応答で終わる場合、プラグインはチャットメッセージ形式で記録します。これにより、Phoenix の実験比較で Markdown として表示されます。構造化メッセージでは、メディア部分を除き、テキスト部分が順番どおりに使用されます。軌跡がない場合や無効な場合、最後がツール呼び出しの場合、ターンがメディアのみの場合、状態のみのタスクの場合は、出力は空のままです。複数ステップのタスクでは最後に試行されたステップが使用され、継続された軌跡では最終の継続部分が使用されます。trace_mode=null の場合も出力の抽出は行われます。この設定で無効になるのはトレースの作成であり、結果の表示ではありません。

以前のプラグインバージョンで書き込まれた成功した実行には、Phoenix の実行が不変であるため、従来の Harbor メタデータ出力がそのまま保持されます。再開時には、この従来の形式が正確に認識され、既存の実行が再利用されます。

省略可能な参照出力を追加する

タスクでは、ルートの 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 ホスト上でダウンロードされたタスクルートからの相対パスです。絶対パス、.. コンポーネント、およびそのルートの外に出るシンボリックリンクは拒否されます。設定されたファイルが存在しない、読み取れない、または無効な場合、試行の実行前にセットアップが失敗します。参照ファイルは検証用アセットと同じ場所に置き、エージェントのワークスペースの外に保管してください。

これはローカルデータセット、直接指定したタスク、公開済みタスクで利用できます。複数ステップのタスクでは、タスク全体に対する参照が 1 つ設定されます。通常は最終結果の期待値です。参照内容を変更するとデータセットのバージョンが作成されます。既存の実験は元のバージョンを維持します。参照を追加しても Harbor の採点には影響しません。

データセットに名前を付ける

プラグインは、サポートされている単一ソースの各ジョブについて、Phoenix のデータセット名を推測します。複数の直接指定タスクを含むジョブ（共通のコレクション名がない場合）、または Phoenix でのデータセットの表示名をカスタマイズする場合にのみ、dataset=<name> を指定してください。

推測される名前は次のとおりです。

Harbor のソース	Phoenix のデータセット名
名前付きレジストリデータセット	選択したデータセット名
公開済みパッケージ	選択した <organization>/<dataset> 名
ローカルデータセットのパス	解決されたディレクトリ名
リポジトリデータセット	解決されたレジストリメタデータ名
直接指定したタスクが 1 つ	harbor-task/<task-name>

複数の直接指定タスクに名前を付ける場合、または推測された名前を上書きする場合は、Harbor コマンドに次の設定を追加してください。

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

ジョブに次のいずれかの未対応のソース形態がある場合は、処理を中止して制約を説明してください。

• 設定されたデータセットが複数ある；
• 設定されたデータセットと直接指定したタスクの両方がある；
• dataset=<name> を指定せずに、複数の直接指定タスクを含めている；
• タスク ID が重複している；または
• 再採点ジョブ、もしくは以前の Harbor 結果から派生した別のジョブである。

プラグインはジョブの開始時に、解決されたタスクセット全体を同期します。変更がなければ、同じデータセットバージョンが再利用されます。タスクの追加、削除、または内容の変更があると、新しいバージョンが作成されます。既存の実験は、作成時のバージョンに固定されたままになります。

実験に名前を付ける

デフォルトのテンプレートは次のとおりです。

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

エージェント設定が 1 つの場合は、正確な名前を指定できます。

--plugin-kwarg experiment_name=release-candidate

エージェント設定が複数ある場合は、experiment_name_template を使用してください。利用可能なフィールドは次のとおりです。

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

エージェント名は一意である必要はありません。名前が同じでも実効設定が異なるエージェントには、それぞれ実験が割り当てられます。レンダリングされた名前が重複する場合、プラグインはエージェントの短縮ダイジェストを追加します。安定した識別情報は表示名ではなく、Harbor ジョブ ID と実効エージェント設定に基づきます。

スコアの解釈

実行結果と実行環境の健全性は分けて扱ってください。Phoenix は別の評価器を実行しません。プラグインは、Harbor が完了した検証報酬を、CODE アノテーター種別の名前付き実験評価として記録します。

評価	解釈
reward	Harbor の最終検証器が文字どおりの reward キーを出力した場合にのみ存在します。値が 0 の場合は実行環境のエラーではなく、動作上の失敗です。
infra_ok	すべての実行に存在します。1 は Harbor が試行またはステップの例外を記録しなかったことを意味します。0 は少なくとも 1 件の例外が発生したことを意味します。
<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 を比較します。
4. ステップスコアとリンクされたトレースを使用して、タスク内の失敗箇所を特定します。

ATIF トレースの解釈

1 つの論理的な試行は、1 つのトレースと 1 つの Phoenix セッションに対応します。トレースは、プラグインが所有する harbor.trial CHAIN スパンから始まります。複数ステップの試行では、試行されたステップごとに 1 つの harbor.step スパンが追加されます。

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

単一ステップの軌跡は試行ルートに直接紐づきます。複数ステップの harbor.step スパンには、指示、タイミング、例外の状態、および検証器の報酬があればそれらが含まれます。軌跡が欠落している場合でも、ステップは表示されます。すべてのステップスパンと軌跡は試行ルートを共有します。

エージェント、モデル、ツールの各スパンには、それぞれの ATIF 名が使用されます。新しいエージェント操作には iteration N、コンテキスト管理操作には compaction N、その他の運用上のシステムステップには system event N が使用されます。複数ターンの軌跡には turn N スパンが追加されます。llm_call_count: 0 のステップでは、操作スパンとツールスパンは保持されますが、LLM スパンは作成されません。継続のルートには <agent> (continuation N) が使用されます。

コンバーターは ATIF v1.0 から v1.7 までをサポートします。ATIF から LLM の入力を再構成し、metadata.atif.input_source = "reconstructed" として記録します。コピーされたプロンプト履歴はこれらの入力に含まれますが、スパンは作成されません。観測とツール呼び出しは、source_call_id が一致する場合にのみ対応付けられます。複数の結果は順序を保持してください。対応付けられないステップの観測は操作スパンに残り、割り当てられていないフィードバックは、役割やツールとの関連付けを捏造せずに、再構成された入力内で構造化された状態を保ちます。構造化テキストと画像パーツはシリアライズされた状態を保ちますが、メディアのバイト列はアップロードされません。ATIF v1.8 の音声フィールドはサポートされていません。

llm.* 属性を持つのは LLM スパンのみです。トークンの二重計上を避けるため、軌跡の final_metrics はエージェントルートのメタデータに保持されます。プロデューサー固有のキャッシュ書き込みトークン数と推論トークン数がある場合は、対応する OpenInference のトークン詳細属性にマッピングされます。

ATIF のタイムスタンプは時点イベントを表します。期間を一意に特定できない場合、LLM スパンまたは TOOL スパンの継続時間がゼロになることがあります。これを、その操作に時間がかからなかった証拠と解釈しないでください。宣言されたツールの順序は、直列実行の証明にはなりません。

ATIF の検出と変換はベストエフォートで行われます。軌跡が欠落しているか無効な場合、プラグインは警告を出し、トレースなしで実行を記録します。後から再生しても、変更不可能な成功済み実行にトレースを紐づけることはできません。

失敗への対応と再開

プラグインを選択すると、Phoenix への記録が必須になります。

• セットアップに失敗すると、試行の実行前にジョブが停止します。
• 実行結果または評価結果の書き込みに失敗すると、ジョブが停止します。すでに記録された試行は Phoenix に残ります。
• Harbor は、再開時にプラグインが取り込める終了済みの結果を保持します。
• ATIF の変換またはアップロードに失敗しても、ジョブは停止しません。トレースなしで実行結果が記録されます。

順次の再開とリプレイでは、一致するデータセット、実験、成功した実行、評価、トレースが再利用されます。失敗した実行は再試行できます。別のジョブが共有データセットの新しいバージョンを作成した場合は、元の実験を復元し、作成時のバージョンに固定したままにしてください。実験の復元はプロセス間でアトミックではないため、同じ Harbor ジョブに対して複数の取り込み処理を実行しないでください。

Phoenix で競合が報告された場合、無視するようユーザーに伝えないでください。プラグインは、保存済みの実行における試行出力とトレースの識別情報を検証します。一致しない場合は、新しい Harbor ジョブを作成するか、競合している Phoenix のレコードを解決する必要があります。

現在の制限事項

プラグインは以下をサポートしていません。

• Harbor の再採点ジョブ、および以前の Harbor の結果から派生したその他のジョブ
• 完了済みジョブの事後取り込み
• ライブ OTLP トレースの関連付け（後続の対応に延期されています）
• 1 つのジョブで複数の設定済みデータセットを使用すること
• 設定済みデータセットと直接タスクを混在させること
• 1 つの Harbor ジョブの同時取り込み

公開ガイドには、Phoenix の Harbor ドキュメントを使用してください。Harbor のコマンドとタスクの設定については、Harbor のドキュメントを使用してください。