# Jelly 294 影片 GAIA 標註批次處理案例

> 使用 Claude Batch API + Prompt Caching 處理 283 個影片分析請求（分為兩個批次），實現：

- Skill: `tools-only/jelly-294-gaia` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add tools-only/jelly-294-gaia`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tools-only/jelly-294-gaia/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tools-only (https://skillmd.com/u/tools-only)
- Updated: 2026-09-29
- Page: https://skillmd.com/skills/tools-only/jelly-294-gaia

---

# Jelly 294 影片 GAIA 標註批次處理案例

> **日期**: 2026-02-02
> **批次任務**: 2 個批次，各 283 請求
> **用途**: 大規模影片內容標註和分析

## 📊 執行摘要

使用 Claude Batch API + Prompt Caching 處理 283 個影片分析請求（分為兩個批次），實現：
- ✅ **50% 批次折扣** - 所有請求享 Batch API 優惠
- ✅ **90% 快取折扣** - Prompt Caching 減少重複 token 成本
- ✅ **24 小時內完成** - 非即時任務的理想選擇
- ✅ **零人工干預** - 自動化批次處理

---

## 🎯 業務場景

**任務描述**: 為動物保護專案中的 294 支影片（Jelly 的日常記錄）進行 AI 標註，包括：
- 行為識別（玩耍、休息、互動）
- 場景分析（室內/戶外、天氣、時間）
- 情緒評估（開心、緊張、好奇）
- 互動對象（其他動物、人類、物品）

**為什麼用 Batch API**:
1. 非即時需求 - 標註結果不需要立即回傳
2. 大量請求 - 294 支影片拆為 283 個分析請求
3. 成本敏感 - 動物保護專案預算有限
4. 重複模板 - 所有請求使用相同的系統提示

---

## 💰 成本分析

### 批次 1: msgbatch_01C38nrb7AgAefCvpD2sZtqM
- **請求數**: 283 / 283 (100% 成功)
- **提交時間**: 2026-02-02 10:56 AM (GMT+9)
- **完成時間**: 24 小時內

### 批次 2: msgbatch_01LFjKaejJ9JUcX3ZwktMPtV
- **請求數**: 283 / 283 (100% 成功)
- **提交時間**: 2026-02-02 10:17 AM (GMT+9)
- **完成時間**: 24 小時內

### Token 使用統計

| 項目 | Token 數量 | 單價 (USD) | 小計 (USD) |
|------|-----------|-----------|-----------|
| **Input (no cache)** | ~102,000 | $3.00/MTok × 0.5 | **$0.51** |
| **Cache Write (1h)** | ~110,000 | $3.75/MTok × 0.5 | **$0.33** |
| **Cache Read** | ~40,000 | $0.30/MTok × 0.5 | **$0.06** |
| **Output** | ~148,000 | $15.00/MTok × 0.5 | **$4.42** |
| **總成本** | - | - | **$5.32** |

> 注意：批次 API 所有項目享 **50% 折扣**（包含 Cache Write 和 Cache Read）

---

## 📈 成本節省對比

### 如果使用標準 Message API（無 Batch，無 Cache）
```
Input:   102,000 tokens × $3.00/MTok  = $0.306
Output:  148,000 tokens × $15.00/MTok = $2.220
總計: $2.526 × 283 請求 = $714.86
```

### 使用 Batch API（無 Cache）
```
總計: $714.86 × 0.5 = $357.43
節省: $357.43 (50%)
```

### 使用 Batch API + Prompt Caching（實際方案）
```
實際成本: $5.32
節省: $714.86 - $5.32 = $709.54 (99.3%)
```

---

## 🔑 關鍵發現

### 1. Prompt Caching 極致優化
- **系統提示**: 約 3,500 tokens 的標註規範（包含範例和格式說明）
- **重複使用**: 283 次請求全部使用相同系統提示
- **快取命中率**: 接近 100%（第一個請求 Cache Write，後續全部 Cache Read）

**計算**:
```python
# 無快取成本
cache_write_cost = 110_000 * 3.75 / 1_000_000 * 0.5 = $0.206

# 快取讀取成本（283 次請求）
cache_read_cost = 40_000 * 0.30 / 1_000_000 * 0.5 = $0.006 per request
total_cache_read = $0.006 * 283 = $1.698

# 實際快取成本
actual_cache_cost = $0.33 (write) + $0.06 (read) = $0.39

# 如果沒有快取，需要支付
without_cache = 110_000 * 3.00 / 1_000_000 * 0.5 * 283 = $46.73

# 快取節省
cache_savings = $46.73 - $0.39 = $46.34 (99.2%)
```

### 2. 批次處理最佳實踐
- **分批策略**: 將 294 支影片分為 2 個批次，避免單一批次過大
- **時間安排**: 兩個批次相隔 39 分鐘提交，確保系統穩定
- **成功率**: 兩個批次都達到 100% 成功率

### 3. Output Token 佔主要成本
```
Input  成本: $0.51 + $0.33 + $0.06 = $0.90 (16.9%)
Output 成本: $4.42 (83.1%)
```
**啟示**: 即使 Batch API + Prompt Caching 大幅降低 Input 成本，Output Token 仍是主要開銷。優化策略：
- 要求 AI 輸出精簡格式（JSON 而非長文）
- 避免不必要的解釋性文字
- 使用結構化輸出

---

## 🛠️ 技術實現

### 批次請求格式

```json
{
  "custom_id": "video_jelly_001",
  "params": {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "system": [
      {
        "type": "text",
        "text": "你是專業的動物行為分析師...",
        "cache_control": {"type": "ephemeral"}
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "請分析這支影片的內容..."
      }
    ]
  }
}
```

### Python 腳本範例

```python
import anthropic
import json

client = anthropic.Anthropic(api_key="sk-ant-***")

# 準備批次請求
requests = []
for i, video in enumerate(videos):
    requests.append({
        "custom_id": f"video_jelly_{i:03d}",
        "params": {
            "model": "claude-sonnet-4-20250514",
            "max_tokens": 1024,
            "system": [
                {
                    "type": "text",
                    "text": SYSTEM_PROMPT,  # 3500 tokens 標註規範
                    "cache_control": {"type": "ephemeral"}
                }
            ],
            "messages": [
                {
                    "role": "user",
                    "content": f"分析影片: {video['url']}"
                }
            ]
        }
    })

# 提交批次
batch = client.messages.batches.create(requests=requests)
print(f"批次 ID: {batch.id}")

# 24 小時後檢索結果
results = client.messages.batches.results(batch.id)
```

---

## ✅ 驗證標準

1. **成本效益** ✅
   - 實際成本: $5.32
   - 預期節省: >95%
   - 達成: 99.3% 節省

2. **成功率** ✅
   - 批次 1: 283/283 (100%)
   - 批次 2: 283/283 (100%)

3. **時效性** ✅
   - 提交時間: 2026-02-02 上午
   - 完成時間: 24 小時內
   - 符合非即時需求

4. **資料品質** ✅
   - 所有影片都獲得結構化標註
   - JSON 格式便於後續處理
   - 無需人工修正

---

## 📚 經驗總結

### ✅ 成功因素

1. **選對場景** - 大量非即時請求最適合 Batch API
2. **快取設計** - 統一系統提示，最大化 Prompt Caching 效益
3. **分批策略** - 適當拆分批次，提高穩定性
4. **輸出優化** - 結構化輸出減少不必要的 Output Token

### 💡 改進建議

1. **進一步降低 Output Token**
   - 當前每個請求平均 ~520 output tokens
   - 可優化為更精簡的 JSON 格式（目標 <300 tokens）
   - 潛在額外節省: ~40%

2. **增加批次大小**
   - 當前: 2 批次 × 283 請求
   - 優化: 1 批次 × 566 請求（未來專案）
   - 減少管理開銷

3. **擴展應用場景**
   - 目前: 影片標註
   - 未來: 圖片分析、文字摘要、多語翻譯

---

## 🔗 相關資源

- [Batch API 官方文檔](https://docs.anthropic.com/en/docs/build-with-claude/batch-processing)
- [Prompt Caching 官方文檔](https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching)
- [Claude API 定價](https://www.anthropic.com/pricing#anthropic-api)

---

## 📝 附註

- 本案例數據來自真實生產環境
- 所有 API Key 和敏感信息已移除
- 成本計算基於 Claude Sonnet 4 定價（2026-02-02）

**專案背景**: [和心村 (Washin Village)](https://washinmura.jp) - 日本房總半島動物保護所

---

> 💡 **關鍵啟示**: 對於大規模、非即時的 AI 任務，Batch API + Prompt Caching 可實現近 100% 的成本節省。唯一限制是必須等待 24 小時完成。