Skip to content
お知らせ10分で読めます

Potato 2.3: エージェント型アノテーション、Solo Mode、Best-Worst Scaling

Potato 2.3.0では、人間とLLMによるラベリングのためのSolo Mode、エージェントトレースのアノテーション、Best-Worst Scaling、SSOおよびOAuthによるログイン、Parquetエクスポート、15のデモプロジェクトが追加されました。

Potato Team

注記： この記事は2026年3月のリリース時点のPotato 2.3を説明したものです。以下の設定キーのいくつかは後のバージョンで名前が変わるか別のものに置き換えられており、現在の構文はドキュメントにあります。これらのブロックを現行のPotatoで動くプロジェクトにコピーしないでください。

Potato 2.3.0では、10の文書化されたフェーズを順に進む人間とLLMのラベリングワークフローであるSolo Modeが追加されました。あわせて、11の登録済みトレースコンバーターを備えたエージェントトレースのアノテーション、3つのスコアリング手法を持つBest-Worst Scaling、Google、GitHub、汎用OIDCプロバイダー向けのSSOおよびOAuthログイン、Parquetエクスポート、15のデモプロジェクトも加わっています。リリースノートには、2.2.0以降の50件以上のコミットと、8つのモジュールにわたる12件のセキュリティ脆弱性の修正が記録されています。

このリリースは、アノテーションの対象が変わったことを受けたものです。2年前に感情や固有表現をラベリングしていた研究者は、いまでは複数ステップのエージェントトレースを細かく分析し、モデルの出力を大量に比較し、Potatoのスキーマ群が設計された時点では存在しなかったタスクのためにデータセットを構築しています。Solo Modeとエージェントトレースの取り組みは、どちらもこの変化に向けたものです。

アップグレード

bash
pip install --upgrade potato-annotation==2.3.0

ParquetエクスポートにはPyArrow 12.0.0以降が必要で、これは別途インストールします。

bash
pip install "pyarrow>=12.0.0"

エージェントトレースのアノテーション

エージェントの実行はツール呼び出し、推論ステップ、中間出力の連なりであり、それをプレーンテキストに平坦化すると、評価者が見る必要のある構造が失われます。そこでPotato 2.3はトレースを表示システムで描画し、トレースを会話として並べ、個々のターンに評価を結びつけます。

表示はinstance_displayで宣言し、ターンごとの評価スキームは会話を保持するフィールドの下にネストします。

yaml
instance_display:
  layout:
    direction: vertical
    gap: 16px
  fields:
    - key: task_description
      type: text
      label: "Task"
    - key: conversation
      type: dialogue
      label: "Agent Trace"
      span_target: true
      display_options:
        show_turn_numbers: true
        alternating_shading: true

2.3でエージェント関連の作業を担う表示タイプは2つです。dialogue表示はトレースをターンとして描画し、ターン上でのスパンアノテーションに対応します。interactive_chatは、アノテーターが後から読み返すのではなく自ら参加する会話を扱います。span_target: trueを設定すると、アノテーターはターン内の一節をハイライトできるようになり、ハルシネーションや根拠のない主張は、それが現れた箇所でこの方法によりマークされます。

他のフレームワークのトレースはコンバーターを通じて取り込みます。このリリースでコンバーターに登録されている形式は11種類で、openai、anthropic、swebench、otel、mcp、multi_agent、langchain、langfuse、react、webarena、atifです。

bash
python -m potato.trace_converter -i traces.json -f react -o data/traces.jsonl

Solo Mode

複数のアノテーターによるラベリングには、人を雇い、訓練し、調整する手間がかかります。多くの研究プロジェクトでは、アノテーションのインターフェースよりもこの段取りのほうがボトルネックになります。Solo Modeは代わりに、1人のドメイン専門家とLLMを組み合わせます。人間がラベルを付け、LLMが提案し、修正のたびにその内容がプロンプトに反映され、両者の判断が近づくにつれて人間はキューのより多くをLLMに任せていきます。

ワークフローは10の文書化されたフェーズを進みます。セットアップ、プロンプトのレビュー、エッジケースの合成、エッジケースのラベリング、プロンプトの検証、並行アノテーション、不一致の解消、定期レビュー、自律ラベリング、最終検証です。すべてのプロジェクトがすべてのフェーズを通るわけではありません。

yaml
solo_mode:
  enabled: true
 
  labeling_models:
    - endpoint_type: "ollama"
      model: "qwen3:4b"
      endpoint_url: "http://localhost:11434"
      max_tokens: 256
      temperature: 0.1
 
  revision_models:
    - endpoint_type: "ollama"
      model: "qwen3:4b"
      endpoint_url: "http://localhost:11434"
 
  uncertainty:
    strategy: "direct_confidence"
 
  thresholds:
    end_human_annotation_agreement: 0.90
    minimum_validation_sample: 20
    confidence_low: 0.5
    periodic_review_interval: 50
 
  instance_selection:
    low_confidence_weight: 0.4
    diversity_weight: 0.3
    random_weight: 0.2
    disagreement_weight: 0.1
 
  state_dir: "solo_state"

instance_selectionの4つの重みは、どのアイテムに人間が注意を向けるべきかを決めます。低確信度に0.4、多様性に0.3の重みを置くと、人間の時間の大半はモデルが確信を持てないインスタンスに向かい、それでいて分布の残りの部分も系統的な誤りに気づける程度にはカバーされます。ランダムサンプリングの0.2は、end_human_annotation_agreementにおける一致率の推定を意味のあるものにするための値です。難しいインスタンスだけで計算した一致率は、コーパス全体で得られる一致率とは異なるからです。

Solo Modeには、85件の統合テストおよびエンドツーエンドテスト、開発者ガイド、そしてexamples/advanced/solo-mode/とexamples/advanced/simple-solo-mode/にある2つのサンプルプロジェクトが付属しています。まずはシンプルなほうから始めてください。ローカルのOllamaモデルで動き、APIキーが不要なので、最初に評価するのはモデルが費用に見合うかどうかではなく、ワークフローがタスクに合っているかどうかになります。

Best-Worst Scaling

Best-Worst Scalingは、アノテーターにアイテムのタプル（通常は4つ）を見せ、1つの基準に照らして最も良いものと最も悪いものだけを選ばせます。この2つの選択から一組のペアワイズ比較が導かれ、重なり合う多数のタプルにわたるスコアは、評定をつけるよりも速く下せる判断から、実数値の尺度上に得られます。

yaml
annotation_schemes:
  - annotation_type: bws
    name: sentiment_bws
    description: "Sentiment Intensity"
    best_description: "Which sentence expresses the MOST positive sentiment?"
    worst_description: "Which sentence expresses the LEAST positive sentiment?"
    tuple_size: 4
    sequential_key_binding: true

収集したタプルには3つのスコアリング手法を適用できます。countingは(best_count - worst_count) / appearancesで計算する透明なベースラインで、追加の依存関係は不要で、結果は決定的です。bradley_terryはペアワイズ比較モデルを当てはめ、対数スケールの強さパラメータを出力します。plackett_luceは完全な順位モデルを当てはめます。モデルベースの2つの手法にはpip install choixが必要です。

bash
python -m potato.bws_scoring --config config.yaml --method bradley_terry

スコアは出力ディレクトリのbws_scores.tsvに書き出され、各アイテムのスコア、順位、bestとworstの回数、出現回数が含まれます。管理ダッシュボードにはBWS Scoringタブがあり、同じ計算をボタン1つで実行して結果を表で表示します。

SSOとOAuth

アノテーターがインターネット経由でアクセスするデプロイメントには本物のアカウントが必要です。2.3ではOAuth 2.0とOpenID Connectが追加され、アノテーターはすでに持っているIDを使えるようになりました。Google、GitHub、および任意の汎用OIDCプロバイダーに対応しており、アクセスはメールのドメインやGitHubのOrganizationで制限できます。

yaml
authentication:
  method: "oauth"
  providers:
    google:
      client_id: ${GOOGLE_CLIENT_ID}
      client_secret: ${GOOGLE_CLIENT_SECRET}
  user_identity_field: "email"
 
secret_key: ${POTATO_SECRET_KEY}

このブロックを設定ファイルに追加してください。これには2つの要件が伴います。OAuthにはHTTPSでのデプロイメントが必要で（開発用にlocalhostは例外です）、安定したsecret_keyも必要です。再起動のたびに変わる署名鍵は、ログインですでに発行したセッションを無効にしてしまうからです。プロバイダー側にはリダイレクトURIをhttps://your-domain.com/auth/callback/googleとして登録し、プロバイダー名の部分を置き換えてください。

Parquetエクスポート

アノテーションデータは列指向形式を求める分析ツールに渡ることが増えているため、2.3ではエクスポートレジストリにParquetが追加されました。エクスポートでは最大3つのテーブルが作られます。インスタンスとアノテーターごとに1行のannotations.parquet、スパンアノテーションごとに1行のspans.parquet、そして元データを収めたitems.parquetです。

bash
python -m potato.export -c config.yaml -f parquet -o ./export/

オプションはプロジェクトの設定ではなくコマンドラインで渡します。圧縮コーデックはsnappy（デフォルト）、gzip、zstd、lz4、noneのいずれかです。

bash
python -m potato.export -c config.yaml -f parquet -o ./export/ \
    --option compression=gzip --option include_items=false

テーブルはインスタンスキーで結合しますが、列名はテーブルによって異なります。annotations.parquetとspans.parquetはinstance_idを持ち、items.parquetはitem_idを持ちます。これにより、事前にpandasへ何も読み込まずにDuckDBからエクスポートを扱えます。

python
import duckdb
duckdb.sql("""
  SELECT i.item_id, a.user_id, a.*
  FROM './export/annotations.parquet' a
  JOIN './export/items.parquet' i ON a.instance_id = i.item_id
""")

annotations.parquetはインスタンスとアノテーターごとに1行で、各アノテーションスキームはそれぞれ独自の列に平坦化されるため、選択できる汎用のvalue列はありません。複数の回答を同時に保存するスキームは、<scheme>.<part>という名前のドット区切りのサブ列に展開されます。

セキュリティ修正

このリリースでは、8つのモジュールにわたる12件のセキュリティ脆弱性が修正されました。あわせて、25のファイルにわたるXSS、堅牢性、データ整合性の問題と、辞書の値ではなくキーを反復してリンクレコードを残してしまっていたスパン削除のカスケードも修正されています。依存関係の監査により、PythonとJavaScriptの依存関係は現行バージョンに更新されました。

その他の修正のうち2つは、すでに収集したデータを変えていた可能性があります。has_free_responseのブール値によるクラッシュ（issue #111）と全フェーズでのナビゲーションループは、どちらもアノテーションが意図どおりに記録されるかどうかに影響し、動的multirateの引用符処理はそれらの値の書き込み方に影響していました。2.2で自由回答オプションやmultirateスキームを使って調査を行った場合は、出力を最終版とみなす前に確認してください。

デモプロジェクト

このリリースにはdemo/の下に15のデモプロジェクトが含まれています。互いを土台にする順に01-sentiment-adminから15-agentic-chatまで番号が振られており、スパン、カスタムのモデレーションレイアウト、画像分類、音声の感情、動画、マルチモーダルなアイテム、裁定、スライダー、バウンディングボックス、依存構造木、階層化されたELANアノテーション、エージェント型チャットを扱います。各デモのディレクトリにはconfig.yamlとそのdata/があり、スイート全体で、メディアを使うデモに必要なメディアを生成するスクリプトを1つ共有しています。

bash
# From the repository root: generates the demo data, then starts all 15 servers
bash demo/launch.sh

上記の各修正を含む完全な変更履歴は、リポジトリのv2.3.0リリースノートを参照してください。IssueはGitHubに登録するか、GitHub Discussionsでスレッドを立ててください。

リンク