life-echo/api/docs/internal-eval.md

# 内部回归评测平台

与主 API（`app/main.py`）隔离进程部署，避免评测候选链路透出给消费者 App。

## 启动

一键脚本 `internal-eval.sh` 与 `development.sh` **不是重复各启一套主站**：

| | `development.sh` | `internal-eval.sh` |
|---|------------------|---------------------|
| HTTP | 主站 `main:app`（默认 **8000**） | 仅评测 `internal_app`（默认 **8001**） |
| Celery | 会起一个 worker | 默认也会起一个 worker（可与下面「瘦启动」二选一） |

评测分析只需要 **8001 上的 internal API**；若你已经在跑 `development.sh`（DB/Redis/主站/已有 Celery），不必再起第二份基础设施和 worker：

```bash
cd api
chmod +x internal-eval.sh
# 确保 .env.development 或 .env 里有 INTERNAL_EVAL_API_KEY
SKIP_INFRA=1 SKIP_INSTALL=1 SKIP_CELERY=1 ./internal-eval.sh   # 推荐：只多开 8001
```

全新机器、只跑评测栈时可直接 `./internal-eval.sh`（会起 docker、`uv sync`、迁移、8001 + Celery）。**默认会起 `app-eval-web`，并用 Vite `--open` 尝试打开浏览器**（`http://127.0.0.1:5174/`）。不要前端时设 `START_EVAL_WEB=0`；只要前端但不要弹窗时设 `OPEN_EVAL_WEB=0`。

数据库与主服务共用；需配置环境变量后启动专用进程：

```bash
cd api
export INTERNAL_EVAL_API_KEY='your-long-random-secret'
export INTERNAL_EVAL_ENABLE_DOCS=1   # 可选，开 /docs
# GLM 评审（默认复用智谱 key，也可单独配置）
export EVAL_JUDGE_API_KEY='...'        # 可选，默认 ZHIPU_API_KEY
export EVAL_JUDGE_MODEL='glm-4-flash'

uv run uvicorn app.internal_main:internal_app --host 0.0.0.0 --port 8001
```

Celery worker 需已包含 `app.tasks.evaluation_tasks`（仓库 `celery_app.include` 已注册）。跑实验前：

```bash
uv run celery -A app.tasks.celery_app worker -l info
```

## 前端（`app-eval-web`）

```bash
cd app-eval-web
npm install
VITE_EVAL_API_BASE=http://127.0.0.1:8001 VITE_EVAL_API_KEY=与上同 npm run dev
```

或使用仓库根目录 `npm run eval-web`（需本地已 `npm install` 在 `app-eval-web`）。

## SSE / EventSource

浏览器 `EventSource` 无法带自定义 Header，流式端点支持 **query** `?key=`，与 `X-Internal-Eval-Key` 等效。

## 门禁规则（v1）

- 所有 case 的合成均分：候选须 **严格高于** 基线。
- `is_protected=true` 的 case：合成份跌幅不得超过 `EVAL_GATE_PROTECTED_REGRESSION_THRESHOLD`（默认 2 分）。

结果写入 `eval_gate_verdicts`，不影响 `git`；后续可接 pre-commit / CI。