Black-Box for Boxing LLM Behaviors — 評估、量化、比較 AI Agent 的行為表現。
- 多 Agent 支援：OpenAI / Anthropic / 自建 API，可擴充的 Adapter 架構
- 通用指標（Universal）：12 項內建指標（語義相似度、事實準確性、幻覺偵測、安全性等）
- 客製指標（Custom）：依 Agent 類型動態提供（工具使用、Schema 驗證、精確匹配等）
- Plugin 架構：新增 Agent / 指標無需修改核心程式碼
- 非同步引擎：所有評測指標平行執行
- 報告匯出：JSON / PDF 格式下載
- 現代化 UI：Vue 3 儀表板，含雷達圖與分數明細
- Docker Desktop（必要）
- Docker Compose v2+（隨 Docker Desktop 內建）
⚠️ 本專案僅支援容器化開發，不需在本機安裝 Python 或 Node.js，避免汙染本地環境。
cp backend/.env.example backend/.env編輯 backend/.env，填入你的 API Key：
OPENAI_API_KEY=sk-your-key-here
OPENAI_MODEL=gpt-4.1-minidocker compose up --build等待建構完成後：
docker compose down後端使用 FastAPI（Python 3.12），程式碼掛載為 volume，修改後需重新建構：
# 重新建構後端容器
docker compose up --build backend
# 查看後端日誌
docker compose logs -f backend
# 進入後端容器除錯
docker compose exec backend bash
# 在容器內執行測試
docker compose exec backend pytest tests/ -v後端目錄結構：
backend/app/
├── main.py # FastAPI 進入點
├── config.py # 環境設定
├── agents/ # Agent 抽象層
│ ├── base.py # BaseAgent 抽象類別
│ ├── openai_agent.py # OpenAI Adapter
│ ├── anthropic_agent.py
│ ├── custom_api_agent.py
│ └── registry.py # Agent 註冊中心
├── metrics/ # 評測指標
│ ├── base.py # MetricPlugin 抽象
│ ├── registry.py # Metric 註冊中心
│ ├── universal/ # 12 項通用指標
│ └── custom/ # 5 項客製指標
├── schemas/ # Pydantic 資料模型
├── services/ # 核心業務邏輯
│ ├── evaluation_engine.py # 評測引擎
│ └── report_generator.py # 報告產生器
└── api/ # REST API 路由
前端使用 Vue 3 + Pinia + Chart.js：
# 重新建構前端容器
docker compose up --build frontend
# 查看前端日誌
docker compose logs -f frontend
# 進入前端容器除錯
docker compose exec frontend sh前端元件架構：
frontend/src/
├── api/index.js # Axios API 客戶端
├── stores/evaluation.js # Pinia 狀態管理
├── views/Dashboard.vue # 主頁面
└── components/
├── AgentSelector.vue # Agent 下拉選擇
├── PromptInput.vue # Prompt 輸入區
├── CustomMetricsSelector.vue # 客製指標勾選
├── EvaluateButton.vue # 評測按鈕
├── ReportPanel.vue # 報告面板
├── UniversalMetrics.vue # 通用指標（雷達圖 + 分數列表）
├── CustomMetrics.vue # 客製指標顯示
├── RadarChart.vue # Chart.js 雷達圖
└── DownloadButtons.vue # JSON / PDF 下載
| 方法 | 路徑 | 說明 |
|---|---|---|
GET |
/api/v1/agents |
取得所有可用 Agent |
GET |
/api/v1/agents/{name}/metrics |
取得 Agent 的客製指標 |
POST |
/api/v1/evaluate |
執行評測 |
POST |
/api/v1/evaluate/report/json |
下載 JSON 報告 |
POST |
/api/v1/evaluate/report/pdf |
下載 PDF 報告 |
curl -X POST http://localhost:9527/api/v1/evaluate \
-H "Content-Type: application/json" \
-d '{
"agent": "openai",
"prompt": "用簡單的方式解釋量子計算",
"custom_metrics": ["tool_usage_score"]
}'- 在
backend/app/agents/新增檔案，繼承BaseAgent - 實作
async def run(self, prompt, config) -> AgentResult - 在
registry.py註冊
- 在
metrics/universal/或metrics/custom/新增檔案 - 繼承
MetricPlugin，實作async def evaluate(...) - 在
metrics/registry.py註冊
見 LICENSE。