hz4th_coder/nba-fan-hub
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
4e360be8c77cbf359b9200204304097869c65c75
nba-fan-hub/README.md
T

8.6 KiB
Raw Blame History

🏀 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 一键重建

🧠 对话管线要点

  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 数据。

Reference in New Issue View Git Blame Copy Permalink