baozaotumao2025
127 lines
6.7 KiB
Markdown
127 lines
6.7 KiB
Markdown
# 教程：从零启动平台
|
||
|
||
## 1. 同步依赖
|
||
```bash
|
||
uv sync
|
||
```
|
||
|
||
## 2. 初始化数据库
|
||
```bash
|
||
./scripts/init_db.sh
|
||
```
|
||
|
||
该命令会升级到最新结构，并在不存在时创建管理员 `gly`，初始密码 `maxta2026`。命令可重复执行，不会覆盖已有 `gly` 的密码。
|
||
|
||
## 3. 设置初始 `.env`
|
||
首次启动至少确认：
|
||
- TARGET_BASE_URL
|
||
- TARGET_MODEL
|
||
- TARGET_AUTH_TYPE
|
||
- TARGET_API_KEY
|
||
- JUDGE_BASE_URL
|
||
- JUDGE_MODEL
|
||
- JUDGE_API_KEY
|
||
|
||
这些值是数据库尚无对应角色记录时的回退配置。启动并登录后，可改用 provider CRUD 持久化管理，无需重启。
|
||
|
||
## 4. 启动服务
|
||
```bash
|
||
uv run uvicorn app.main:app --workers 1
|
||
```
|
||
|
||
当前运行调度使用进程内状态，必须保持单进程。仅本地开发需要热重载时使用 `uv run uvicorn app.main:app --reload`；不要配置多个 worker，也不要同时启动多个服务进程。
|
||
|
||
## 5. 创建并登录用户
|
||
|
||
先设置 `AUTH_TOKEN_SECRET`（生产环境必须是随机长密钥），再使用初始化生成的管理员登录：
|
||
|
||
```bash
|
||
curl -X POST http://127.0.0.1:8000/api/v1/auth/login \
|
||
-H 'Content-Type: application/json' \
|
||
-d '{"username":"gly","password":"maxta2026"}'
|
||
```
|
||
|
||
除 `GET /api/v1/health` 和登录接口外，所有 `/api/v1/*` 请求都必须带上登录返回的令牌：
|
||
|
||
```bash
|
||
curl http://127.0.0.1:8000/api/v1/providers/target/models \
|
||
-H 'Authorization: Bearer <access_token>'
|
||
```
|
||
|
||
Swagger 也可直接测试：打开 `/docs` 后，点击右上角 **Authorize**，在 `BearerAuth` 输入框粘贴登录响应里的
|
||
`access_token`（只粘贴令牌本身，不要手动写 `Bearer `），点击 Authorize 和 Close。之后所有带锁的接口会自动
|
||
携带 `Authorization: Bearer <access_token>`；令牌过期或登出后，重新登录并重复该步骤。
|
||
|
||
管理员可管理用户：`POST /api/v1/auth/users` 创建用户，`GET /api/v1/auth/users` 列表，
|
||
`PATCH /api/v1/auth/users/{id}` 启用或禁用用户，`DELETE /api/v1/auth/users/{id}` 永久删除用户。普通用户调用这些接口会得到 403；当前登录管理员不能禁用或删除自己。
|
||
已登录用户可用 `GET /api/v1/auth/me` 查看自己的账号和管理员标志。首次登录后立即调用 `PATCH /api/v1/auth/password`，提交 `{"current_password":"maxta2026","new_password":"至少8位的新密码"}` 修改本人密码。成功返回 204，并使本人所有旧令牌失效，随后用新密码重新登录。管理员仍可用 `PATCH /api/v1/auth/users/{id}/password` 无需旧密码地重置他人密码。
|
||
登出调用 `POST /api/v1/auth/logout`，被撤销的令牌会立即无法再访问 API。
|
||
|
||
管理员还可管理模型提供商配置：`POST /api/v1/providers` 创建，`GET /api/v1/providers` 与
|
||
`GET /api/v1/providers/{provider_id}` 查询，`PATCH /api/v1/providers/{provider_id}` 局部更新，
|
||
`DELETE /api/v1/providers/{provider_id}` 删除。`provider_id` 是 `target` 或 `judge`；API Key
|
||
只在写入时提交，响应仅返回 `api_key_configured`。PATCH 未提供 `api_key` 时保留原密钥。
|
||
`GET /api/v1/providers` 始终返回当前生效的 `target` 与 `judge`：`source=env` 表示来自 `.env`，
|
||
`source=database` 表示数据库记录覆盖了该角色的环境变量。
|
||
|
||
## 6. 打开文档
|
||
- Swagger: `http://127.0.0.1:8000/docs`
|
||
- ReDoc: `http://127.0.0.1:8000/redoc`
|
||
- OpenAPI JSON: `http://127.0.0.1:8000/openapi.json`
|
||
|
||
## 7. 推荐调用顺序
|
||
1. `GET /api/v1/health`
|
||
2. `GET /api/v1/providers`（确认每个角色的 `source` 与密钥配置状态）
|
||
3. `GET /api/v1/providers/judge/models`
|
||
4. `POST /api/v1/providers/target/check`
|
||
5. `POST /api/v1/runs`（新 Run 内部先执行并保存能力探测结果）
|
||
6. `GET /api/v1/runs`
|
||
7. `GET /api/v1/runs/{run_id}`
|
||
8. `GET /api/v1/runs/{run_id}/results`
|
||
9. `GET /api/v1/runs/{run_id}/export`
|
||
10. `GET /api/v1/reports`
|
||
11. `GET /api/v1/reports/{run_id}`
|
||
|
||
创建运行的网络重试应复用同一个 `Idempotency-Key` 请求头；同一键与同一请求只会创建一个运行。
|
||
|
||
若服务中断，确认原进程已停止后调用 `POST /api/v1/runs/{run_id}/resume`；已保存的能力探测结果和题目不会重复执行。
|
||
若终态是 `completed_with_errors`，调用 `POST /api/v1/runs/{run_id}/retry-errors`：成功结果保持不变，仅重跑 `execution_status=error` 的样例。逐条结果的 `verdict=fail` 是仲裁结论，不计入 Run 的 `error_count`，也不会被该接口重试。
|
||
若只需重跑某条已有结果，在 Run 进入 `completed` 或 `completed_with_errors` 后调用 `POST /api/v1/runs/{run_id}/results/{execution_id}/retry`，然后继续轮询该 Run。
|
||
|
||
## 8. 创建并跟踪一次测试
|
||
|
||
`smoke` 最多执行 1 条单轮题；`all` 执行目标模型实际支持的全部题目。`auto_judge=false`
|
||
时仍会保存被测模型原始回复，但不会生成自动裁判结论。
|
||
|
||
```bash
|
||
curl -X POST http://127.0.0.1:8000/api/v1/runs \
|
||
-H 'Content-Type: application/json' \
|
||
-H 'Authorization: Bearer <access_token>' \
|
||
-H 'Idempotency-Key: a-new-unique-key' \
|
||
-d '{"profile":"smoke","auto_judge":true}'
|
||
```
|
||
|
||
新 Run 先探测并持久化基础能力，再按案例所需能力的交集筛选并异步执行；同一 Run 的恢复和重试复用探测结果。含 system 上下文或结构化附件的案例要求 `system_message`。响应中的 `selected_count` 初始为 `0`；使用 `GET /runs/{run_id}` 轮询，
|
||
直到 `terminal=true`，再获取逐条 `results` 和汇总 `reports`。
|
||
|
||
报告不单独保存：`POST /runs` 创建运行后即可查询实时报告，结果变化时报告自动重算，因此没有报告 POST/PATCH。删除终态 run 会同时删除其结果，之后对应报告返回 404。
|
||
|
||
运行结束后可通过 API 将详细结果下载为 Markdown：
|
||
|
||
```bash
|
||
curl -OJ -H 'Authorization: Bearer <access_token>' \
|
||
'http://127.0.0.1:8000/api/v1/runs/42/export?execution_status=completed&verdict=fail'
|
||
```
|
||
|
||
不传查询参数时导出全部样例。`execution_status` 接受 `completed|error`，`verdict` 接受 `pass|fail|needs_human_review|judge_format_error|none`；运行不存在返回 404，尚未结束返回 409，非法过滤值返回 422。
|
||
|
||
服务器命令行也可导出：
|
||
|
||
```bash
|
||
uv run python scripts/export_run.py --run-id 42
|
||
```
|
||
|
||
默认导出全部样例到 `outputs/run_42_results.md`。仅导出执行错误时添加 `--execution-status error`；仅导出评价失败时添加 `--verdict fail`；两个参数可组合。脚本会交互请求用户名和密码，还可用 `--base-url`、`--username` 和 `--output` 指定服务地址、用户名和输出路径。
|
||
|
||
取消运行使用 `PATCH /api/v1/runs/{run_id}` 和 `{"status":"cancelled"}`。取消是协作式的：正在进行的单次模型请求结束后停止后续样例。终态运行可用 `DELETE /api/v1/runs/{run_id}` 删除，运行中删除返回 409。
|