nba-fan-hub/README.md

# 🏀 NBA球迷大全

面向球迷的 NBA 信息问答系统：对话即可查询比赛、球员、球队、新闻、人物、百科等准确信息。
基于 **大模型（DeepSeek）+ 结构化查询（SQLite）+ RAG 向量检索（Chroma + bge-large-zh）** 混合架构，
数据全部来自内置数据库，回答准确可溯源。

## ✨ 功能

- 💬 **智能对话**：自然语言提问，自动路由到数据库/向量库，返回带来源的准确回答
  - 例：「2026年总决赛谁赢了」「库里本赛季场均数据」「约基奇和字母哥谁得分多」「雷霆为什么能夺冠」
- 🏟️ **数据浏览**：球队 / 球员 / 比赛（含技术统计）/ 新闻 / 人物 / 排名 六大浏览页面
- 🧠 **RAG 检索**：新闻与百科向量化存储，语义检索 + Rerank 精排
- 🔧 **Function Calling**：8 个查询工具（球队/球员/比赛/单场详情/排名/新闻/人物/百科），多轮工具调用 + 实体覆盖补全
- 🧵 **多轮对话**：支持上下文指代（「他拿过几个MVP？」→ 上一话题对象）
- 🎛️ **管理后台**（`/admin`，默认密码 admin123）：球队/球员/比赛/技术统计/排名/新闻百科/人物/运动/联赛 全量 CRUD + 站点配置（开场白、快捷问题、站点名、页脚、密码）
- 📰 **参考资讯折叠块**：回答用到新闻/百科时，回答上方默认折叠展示资讯链接，点击直达详情
- ✨ **实体识别标记**：回答中的球队/球员/人物/比赛自动高亮（含简称：雷霆/湖人/库里/字母哥…），点击弹出详情；回答下方生成快速查看卡片
- 📝 **Markdown 回答**：大模型回答以 Markdown 渲染（标题/列表/表格/代码块/引用），本地 marked 库无外部依赖
- 🔗 **独立详情页**：`/team/1` `/player/1` `/game/1` `/news/1` `/person/1`，弹窗与列表中均有「查看完整详情」链接跳转；详情页内含交叉链接（球队→球员/比赛，比赛→球员/球队）
- 🏆 **季后赛对阵图**：排名页展示完整 bracket（首轮/半决/分区决赛/总决赛），胜者高亮、点击看比赛，支持多赛季切换（2024-25 / 2025-26）

## 🏗️ 系统架构

```
用户提问
  │
  ▼
┌─────────────┐   工具调用(8个)   ┌──────────────────┐
│  DeepSeek    │ ───────────────► │  tools.py 查询层   │
│  deepseek-   │ ◄─────────────── │  · SQLite 结构化   │
│  v4-flash    │   工具结果回填    │  · Chroma 向量检索  │
└─────────────┘                  └──────────────────┘
      │ 最终答案（数据准确 + 来源标注）
      ▼
  前端（对话 + 数据浏览）
```

| 模块 | 技术 | 说明 |
|------|------|------|
| 对话大脑 | DeepSeek `deepseek-v4-flash`（函数调用） | 意图理解、工具选择、答案生成 |
| 结构化数据 | SQLite（本地） | 球队/球员/比赛/统计/排名/新闻/人物，多赛季（2024-25/2025-26） |
| 向量检索 | Chroma（16010，REST） | 新闻/百科语义检索（cosine） |
| Embedding | bge-large-zh-v1.5（16011，1024维） | 中文语义向量 |
| Rerank | bge-reranker-v2-m3（16011） | 检索精排（可选） |
| 前端 | 原生 HTML/JS（无构建） | 对话 + 六大浏览页 + 独立详情页 + 管理后台 + 对阵图 |

## 📁 目录结构

```
nba-fan-hub/
├── api.py            # Flask 服务（REST API + 静态页 + 详情页路由 + 管理后台）
├── chat.py           # 对话管线（工具路由 + 兜底 + 覆盖补全）
├── tools.py          # 8 个查询工具（SQL + 向量），含绰号别名/模糊匹配
├── llm.py            # DeepSeek 调用（思考模式 reasoning_content 回传）
├── entity_linker.py  # 实体识别程序（回答中球队/球员/人物/比赛标记 + 卡片）
├── playoffs.py       # 季后赛对阵图生成器（多赛季 bracket）
├── admin.py          # 管理后台 API（登录认证 + 通用 CRUD + 站点配置）
├── vector_store.py   # Embedding + Chroma + Rerank（纯 REST，零额外依赖）
├── db.py             # SQLite 连接与建表（含 site_config 配置表）
├── seed.py           # 种子数据入口（幂等，可 --rebuild-vector）
├── seed_seasons.py   # 赛季补充数据（2024-25 排名/季后赛 + 2025-26 首轮补齐）
├── seed_*.py         # 模拟数据（30队/154球员/54比赛/46新闻百科/38人物）
├── static/           # 前端（index.html 前台 / admin.html 后台 / detail.html 详情页 + lib/marked.min.js）
├── data/             # nba_fan.db（自动生成）
└── start.sh          # 启停脚本（start/stop/restart/status/seed）
```

## 🚀 快速开始

```bash
# 1. 灌数据（首次或数据更新后）
./start.sh seed              # 或 python3 seed.py --rebuild-vector

# 2. 启动
./start.sh start             # http://<IP>:16090
./start.sh status            # 查看状态
```

依赖：`flask`、`requests`（openclaw conda 环境已具备）。外部依赖服务：
- 大模型：DeepSeek API（key 配置于 `config.py`）
- 向量库：Chroma @ `121.40.164.32:16010`
- Embedding/Rerank：@ `121.40.164.32:16011`

## 🔌 REST API

| 接口 | 说明 |
|------|------|
| `POST /api/chat` | 对话 `{message, history}` → `{reply, sources, used_tools, news_refs, entities, cards}` |
| `GET /api/boot` | 对话启动信息（开场白 + 快捷问题，后台可配置） |
| `GET /api/teams[?q=]` `GET /api/teams/<id>` | 球队列表/详情（含阵容+近期比赛） |
| `GET /api/players[?q=]` `GET /api/players/<id>` | 球员列表/详情 |
| `GET /api/games[?q=&status=]` `GET /api/games/<id>` | 比赛列表/详情（含技术统计） |
| `GET /api/standings?conf=西部/东部&season=2025-26` | 排名（多赛季） |
| `GET /api/seasons` | 可用赛季列表 |
| `GET /api/playoffs?season=2025-26` | 季后赛对阵图（首轮/半决/分区决赛/总决赛） |
| `GET /team/<id>` `/player/<id>` `/game/<id>` `/news/<id>` `/person/<id>` | 独立详情页 |
| `GET /api/news[?q=&kind=]` `GET /api/news/<id>` | 新闻/百科 |
| `GET /api/persons[?q=&role=]` | 人物（coach/commentator/host/agent/gm/legend） |
| `GET /api/health` | 健康检查 + 数据统计 |
| `POST /api/admin/login` | 管理后台登录（默认密码 admin123） |
| `GET/POST/PUT/DELETE /api/admin/<table>[/<id>]` | 通用数据 CRUD（表白名单防注入） |
| `GET/PUT /api/admin/config` | 站点配置读写（开场白/快捷问题/密码等） |

## 🧩 扩展设计（重点）

数据库采用「运动-联赛-球队-球员」分层，新增球类/联赛/人物角色无需改代码：

| 扩展需求 | 怎么做 |
|----------|--------|
| **新增 CBA** | `sports` 已含 basketball；`leagues` 表加一行 `CBA`，灌入 CBA 球队/球员/比赛即可，全部工具自动生效 |
| **新增足球** | `sports` 表加 `football`；`leagues` 加英超/西甲等；球员/球队表字段通用（位置、数据字段可增列） |
| **新增人物角色**（教练/经纪人/评论员/主持人/总经理/球探…） | `persons.role` 是自由字符串，新增角色直接入库即可 |
| **新增查询工具** | `tools.py` 加一个函数 + 注册进 `TOOLS`/`TOOL_HANDLERS` 即自动接入对话 |
| **向量库隔离** | Chroma 按集合名隔离（`nba_fan_knowledge_v1` → `cba_...`），互不影响 |
| **数据更新** | 修改 `seed_*.py` 后 `./start.sh seed --rebuild-vector` 一键重建 |

## 🧠 对话管线要点

1. **工具优先**：系统提示词强制「数据问题先查库」，8 个工具返回结构化 JSON
2. **思考模式兼容**：DeepSeek 思考模型要求回传 `reasoning_content`，已处理
3. **文本工具调用兜底**：模型偶尔把工具调用写成正文，正则解析 + 未知工具名智能映射
4. **实体覆盖补全**：多实体问题（「约基奇和字母哥…」）自动拆词补查，杜绝漏数据
5. **多层兜底**：LLM 异常 → 关键词预检索注入；最终轮仍异常 → 工具结果摘要
6. **诚实原则**：查不到如实说明，常识补充与数据库数据明确区分

## 📊 数据规模（模拟数据，2025-26 赛季）

30 支球队 · 154 名球员（含绰号别名）· 54 场比赛（常规赛/季后赛/总决赛/夏季联赛）· 93 条技术统计 · 46 篇新闻/百科 · 38 位人物

> ⚠️ 数据为演示用模拟数据（2026 总决赛剧情：雷霆 4-2 凯尔特人，SGA FMVP），接入真实数据源时仅需替换 seed 数据。