Skip to content

Web 智慧體標註

在 Potato 中審查網頁瀏覽智慧體的 trace：膠片條導航、SVG 疊加層（點選、邊界框、滑鼠軌跡）以及逐步標註控制元件。

v2.4.0 新增

評估瀏覽網頁的 AI 智慧體，需要看到智慧體當時看到的畫面、它點了哪裡，以及每一步是否合理。Potato 提供專門的 Web 智慧體 trace 檢視器，支援兩種模式：審查已錄製的 trace，以及在真實網站上瀏覽來錄製新的 trace。

概覽

模式適用場景
審查模式你已經有來自 WebArena、Mind2Web、Anthropic Computer Use 或 Potato 自帶錄製器的 trace
錄製模式你希望標註者瀏覽網站，錄下新的互動 trace

審查模式

標註者逐幀檢視智慧體瀏覽會話的截圖。SVG 疊加層會在每張截圖上畫出點選標記、邊界框、滑鼠軌跡和滾動指示。

配置

yaml
instance_display:
  fields:
    - key: steps
      type: web_agent_trace
      label: "Agent Browsing Trace"
      display_options:
        show_overlays: true
        show_filmstrip: true
        show_thought: true
        show_observation: true
        show_element_info: true
        screenshot_max_width: 800
        screenshot_max_height: 600
        filmstrip_size: 80

資料格式

每條資料需要一個 steps 陣列，其中包含每一步的資訊：

json
{
  "id": "trace_001",
  "task_description": "Find and add a blue wool sweater to cart",
  "site": "amazon.com",
  "steps": [
    {
      "step_index": 0,
      "screenshot_url": "screenshots/step_000.png",
      "action_type": "click",
      "element": {
        "tag": "input",
        "text": "Search",
        "bbox": [340, 45, 680, 75]
      },
      "coordinates": {"x": 510, "y": 60},
      "mouse_path": [[200, 300], [350, 200], [510, 60]],
      "thought": "I need to search for blue wool sweaters",
      "observation": "Search box is focused",
      "timestamp": 1.2,
      "viewport": {"width": 1280, "height": 720}
    }
  ]
}

支援的動作類型

動作疊加層
click帶十字準星和脈衝動畫的紅色圓圈
type目標元素上的黃色高亮
scroll綠色方向箭頭
hover紫色圓圈
select藍色邊界框
navigate無疊加層
wait無疊加層
done無疊加層

鍵盤快捷鍵

按鍵操作
← / →上一步 / 下一步
1切換點選標記疊加層
2切換邊界框疊加層
3切換滑鼠軌跡疊加層
4切換滾動指示
A顯示全部疊加層
N隱藏全部疊加層

逐步標註

給任意標註方案加上 per_step: true，就會在每一步旁邊生成對應的標註控制元件：

yaml
annotation_schemes:
  - annotation_type: radio
    name: step_correctness
    labels:
      - name: correct
      - name: incorrect
      - name: unnecessary
  - annotation_type: text
    name: step_notes

逐步標註以 {scheme_name}_step_{index} 的形式儲存（例如 step_correctness_step_0）。

錄製模式

標註者在 Potato 介面內瀏覽真實網站，互動過程會自動錄製成可直接標註的 trace。

配置

yaml
instance_display:
  fields:
    - key: browsing_session
      type: web_agent_trace
      display_options:
        show_overlays: true
        show_filmstrip: true
        show_observation: true
        show_thought: true

代理模式

模式說明
auto（預設）檢測目標站點是否允許 iframe 嵌入，自動選擇最合適的模式
iframe強制使用 iframe 代理 —— 約 90% 的站點可用，額外開銷低於 100 毫秒
playwright強制使用服務端 Playwright —— 所有站點都可用，需要安裝 playwright 包

啟用 Playwright 模式：

bash
pip install playwright
playwright install chromium

轉換已有 trace

用 trace 轉換 CLI 把其他框架的 trace 歸一化成 Potato 的格式：

bash
# Convert from a specific format
python -m potato.trace_converter -i traces.json -f web_agent -o output.jsonl
 
# Auto-detect format
python -m potato.trace_converter -i traces.json --auto-detect -o output.jsonl

支援的輸入格式：WebArena、VisualWebArena、Mind2Web、Anthropic Computer Use，以及 Potato 自己錄製的原始資料。

完整示例

yaml
task_name: "Web Agent Evaluation"
task_dir: "."
 
data_files:
  - "traces.jsonl"
 
instance_display:
  fields:
    - key: task_description
      type: text
      label: "Task"
    - key: steps
      type: web_agent_trace
      label: "Agent Trace"
      display_options:
        show_overlays: true
        show_filmstrip: true
        show_thought: true
 
annotation_schemes:
  - annotation_type: radio
    name: task_success
    description: "Did the agent complete the task successfully?"
    labels:
      - name: "Yes"
      - name: "Partially"
      - name: "No"
  - annotation_type: radio
    name: step_correctness
    description: "Was this step correct?"
    labels:
      - name: correct
      - name: incorrect
      - name: unnecessary
  - annotation_type: text
    name: error_description
    description: "Describe any errors in the agent's behavior"
 
output_annotation_dir: "output/"
output_annotation_format: "jsonl"

執行示例項目

bash
# Review Mode
python potato/flask_server.py start examples/agent-traces/web-agent-review/config.yaml -p 8000
 
# Creation Mode
python potato/flask_server.py start examples/agent-traces/web-agent-creation/config.yaml -p 8000

API 參考

使用錄製模式時，可以呼叫以下 REST 介面：

介面方法說明
/api/web_agent/start_sessionPOST開始一次錄製會話
/api/web_agent/save_stepPOST儲存一步錄製到的互動
/api/web_agent/save_screenshotPOST上傳某一步的截圖
/api/web_agent/end_sessionPOST結束會話並寫入 trace
/api/web_agent/proxy/{url}GET通過伺服器代理訪問外部 URL
/api/web_agent/check_frameableGET檢測某個 URL 是否允許 iframe 嵌入

延伸閱讀

有關實現詳情，請參閱源文件。