🏀 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）
🚀 快速开始
# 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 一键重建 |
🧠 对话管线要点
- 工具优先：系统提示词强制「数据问题先查库」，8 个工具返回结构化 JSON
- 思考模式兼容：DeepSeek 思考模型要求回传
reasoning_content，已处理 - 文本工具调用兜底：模型偶尔把工具调用写成正文，正则解析 + 未知工具名智能映射
- 实体覆盖补全：多实体问题（「约基奇和字母哥…」）自动拆词补查，杜绝漏数据
- 多层兜底：LLM 异常 → 关键词预检索注入；最终轮仍异常 → 工具结果摘要
- 诚实原则：查不到如实说明，常识补充与数据库数据明确区分
📊 数据规模（模拟数据，2025-26 赛季）
30 支球队 · 154 名球员（含绰号别名）· 54 场比赛（常规赛/季后赛/总决赛/夏季联赛）· 93 条技术统计 · 46 篇新闻/百科 · 38 位人物
⚠️ 数据为演示用模拟数据（2026 总决赛剧情：雷霆 4-2 凯尔特人，SGA FMVP），接入真实数据源时仅需替换 seed 数据。