WorkBuddy
80616cf459
- 数据源:全部文档统一为 bzzoiro 唯一来源,删除 understat/api-football 作为现行数据源的表述(仅保留历史注记);.env.example/docs/06 移除 失效的 API_FOOTBALL_KEY - 多 Agent:injuries 阵容完整性 → standings 联赛排名 (README/01/04 的专家表、数据流图、no_data 示例、agent_weights、 prompt 清单全部对齐 form/stats/home_away/standings/h2h) - 数据库:6 张表 → 12 张表,补 standings/app_settings/schedules 与 4 张治理表说明(标注 raw_events/data_quality_checks/data_lineage 为预留未启用,ingest_failures 已启用),predictions 补 agent_weights 列 - API 文档(03):新增鉴权模型三档表;context/standings/leagues 公开端点 补全;predictions/eval/backtest 标注需管理员;ingest/bzzoiro 补 task/limit/season 参数契约,删除 understat/injuries 端点小节 - 目录树(README/01/07):与真实 src/、frontend/src 结构一致 (core 7 文件、data 7 文件、移除不存在的 retry.py) - 采集命令(02/05):understat 回填 → task=stats/standings; 补管理员凭据提示;docs/08 文首标注历史/过时
139 lines
3.8 KiB
Markdown
139 lines
3.8 KiB
Markdown
# 02 · 快速开始
|
||
|
||
## 前置条件
|
||
|
||
- Python 3.11+
|
||
- Docker Desktop(跑 PostgreSQL)
|
||
- 一个 OpenAI-compatible 的 LLM API Key(OpenAI / Deepseek / Ollama 等任一)
|
||
- bzzoiro 数据源 Key(旧项目 MatchPro 的同一 Key)
|
||
|
||
## 1. 安装
|
||
|
||
```bash
|
||
cd P:\Profeto
|
||
pip install -e ".[dev]"
|
||
```
|
||
|
||
## 2. 配置环境变量
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
|
||
编辑 `.env`,至少填这三项:
|
||
|
||
```ini
|
||
LLM_API_KEY=sk-xxx # 必填
|
||
LLM_BASE_URL=https://api.openai.com/v1 # 换成你的提供商
|
||
LLM_MODEL=gpt-4o-mini # 默认模型
|
||
|
||
# 可选分档(推荐):
|
||
LLM_SPECIALIST_MODEL=gpt-4o-mini # 5 个专家用(便宜快)
|
||
LLM_AGGREGATOR_MODEL=gpt-4o # 终裁用(强)
|
||
|
||
BZZOIRO_KEY=xxx # 数据采集用
|
||
```
|
||
|
||
## 3. 启动数据库 + 建表
|
||
|
||
```bash
|
||
docker compose up -d postgres
|
||
alembic upgrade head
|
||
```
|
||
|
||
## 4. 启动服务
|
||
|
||
```bash
|
||
# 后端
|
||
uvicorn src.api.app:app --reload
|
||
|
||
# 前端(另开终端)
|
||
cd frontend
|
||
npm install
|
||
npm run dev
|
||
```
|
||
|
||
- 前端界面: http://localhost:5173
|
||
- API 文档(Swagger): http://localhost:8000/docs
|
||
|
||
## 5. 首次跑通全流程
|
||
|
||
### 采集历史数据(英超近两个月为例)
|
||
|
||
```bash
|
||
curl -X POST http://localhost:8000/api/v1/ingest/bzzoiro \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"leagues":["E0"],"date_from":"2026-08-01","date_to":"2026-09-08"}'
|
||
```
|
||
|
||
> 注:采集/评估端点需管理员凭据。本地开发环境(未配置鉴权、非 production)默认放行;
|
||
> 生产环境需先 `POST /auth/login` 取 Cookie,或带 `X-API-Key` 头。
|
||
|
||
数据量大时**直接拉整赛季**(约 380 场,含近几个赛季更好,近况/交锋/积分榜都需要历史):
|
||
|
||
```bash
|
||
curl -X POST http://localhost:8000/api/v1/ingest/bzzoiro \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"leagues":["E0"],"date_from":"2025-08-01","date_to":"2026-09-08"}'
|
||
```
|
||
|
||
### 回填积分榜与统计(让攻防/排名专家有数据)
|
||
|
||
```bash
|
||
curl -X POST http://localhost:8000/api/v1/ingest/bzzoiro \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"task":"standings"}'
|
||
|
||
curl -X POST http://localhost:8000/api/v1/ingest/bzzoiro \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"task":"stats","leagues":["E0"],"limit":300}'
|
||
```
|
||
|
||
`task=stats` 只补空字段(xG/射门/控球等),不创建比赛。
|
||
|
||
### 查比赛
|
||
|
||
浏览器打开 http://localhost:5173 ,选"英超 / 未开赛";
|
||
或:
|
||
|
||
```bash
|
||
curl "http://localhost:8000/api/v1/matches?league=E0&status=scheduled"
|
||
```
|
||
|
||
### LLM 预测
|
||
|
||
页面上点"LLM 预测",预测面板会展示最终结论 + 5 个专家 agent 的折叠报告(方向性评分/证据/分析);
|
||
或:
|
||
|
||
```bash
|
||
curl -X POST http://localhost:8000/api/v1/predict \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"match_id": 1}'
|
||
```
|
||
|
||
不传 `mode` 默认走多 agent;`"mode":"single"` 走单次调用旧路径(用于对比)。
|
||
|
||
### 赛后评估
|
||
|
||
比赛结束后,采集最新赛果(同一条 ingest 命令会自动把 scheduled 升级为 finished 并补比分),
|
||
然后回填预测:
|
||
|
||
```bash
|
||
curl -X POST http://localhost:8000/api/v1/eval/settle \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"prediction_id": 1, "home_goals": 2, "away_goals": 1}'
|
||
|
||
# 汇总准确率(按 模型 × prompt 版本,含 multi/single 对比)
|
||
curl http://localhost:8000/api/v1/eval/summary
|
||
```
|
||
|
||
## 常见问题
|
||
|
||
| 问题 | 处理 |
|
||
|---|---|
|
||
| 连不上数据库 | `docker compose ps` 确认 postgres 健康;`.env` 的 `DATABASE_URL` 与 compose 一致 |
|
||
| predict 返回 502 | 看 uvicorn 日志的 LLM error;确认 `LLM_BASE_URL`/`LLM_API_KEY`;`response_format` 不兼容的网关会报错(改用支持 json mode 的模型) |
|
||
| 采集 0 场 | bzzoiro Key 失效或联赛代码写错;先 `GET /api/v1/leagues` 看库里有没有联赛 |
|
||
| 专家报告全是 no_data | 历史数据不够 —— 近况需要每队近 5 场、积分榜需要本赛季已完赛比赛,多拉几周数据 |
|
||
| stats 专家报无 xG/统计 | 先跑 `task=stats` 回填(bzzoiro 统计管线,只补空字段) |
|