FitPilot · AI 健身私教

RAG + 多工具 Agent 的智能健身私教系统 —— 会说"我不知道"、记得住你、能查会算、过程透明

FitPilot 不是"套壳问答机"：它有可溯源的知识问答（混合检索 + 双防线拒答）、能动手的工具层（手写 function calling，记录训练/查营养/追踪体征）、认识用户的长期画像（"我 180 斤"自动换算入库、"降到 120 斤"覆盖更新）、以及一套完整的评测体系（248 题 + 同基座 LoRA 三组对比实验）。

核心指标

完整数据与解读见 docs/eval-report.md（检索对比）与 docs/ft-compare-report.md（微调实验）。

Related MCP server: openrhyme-mcp

架构

flowchart TB
    U[用户] --> W[Vue3 前端<br/>SSE 流式 · 过程可视化 · 会话历史]
    W --> A[FastAPI 后端<br/>SSE 事件协议]
    A --> R{LangGraph<br/>意图路由}
    R -->|chat| L[LLM 直接回答]
    R -->|knowledge| RG[RAG 链路<br/>混合检索 → 拒答闸门 → 带引用生成]
    R -->|task| TL[工具循环<br/>5 工具 · 5 轮熔断 · 错误自纠]
    R -->|mixed| MX[混合三步<br/>工具取数 → 检索 → 综合合成]
    RG --> Q[(Qdrant<br/>bge-m3 向量)]
    RG --> BM[(BM25<br/>jieba 分词)]
    RG -->|RRF 融合 K=60| RG
    TL --> DB[(SQLite<br/>训练记录 · 体征 · 画像)]
    MX --> TL
    MX --> RG
    A -. 记忆 .-> MEM[短期压缩 + 长期画像]
    A -. 观测 .-> LF[LangFuse 全链路 Trace]

关键设计：

• 模型是可插拔组件——生成通道整体可切换（改两个环境变量即可从智谱 GLM 切到自托管 vLLM），裁判模型与被测模型分通道，实验已验证

• 分级知识源——本地知识库优先；联网搜索（search_web 工具）只兜底健身相关的时效性问题，回答显式标注"来自网络检索"并附来源链接；知识库外问题照常拒答，联网不稀释拒答语义

• 双防线拒答——检索层闸门（top1 向量分 < 0.61 直接拒答，阈值按 embedding 模型标定）+ 生成层结构化标记 【无法回答】，拒答召回 100% 而知识题误拒 < 9%

• 混合题三步链路——工具只负责取数据，知识由 RAG 供给，最后 LLM 合成；避免工具结果污染知识生成的"各自专业"问题

• 手写 function calling 循环——不用框架代办：schema 声明、多轮终止、工具错误转模型可读信息促其自纠、超限熔断

它能做什么

评测体系

• 评测集 248 题：knowledge 201 + reject 20（考幻觉抑制）+ task 12 + mixed 15；双语表头 CSV，含多可接受出处口径

• 工程韧性：断点续跑（逐题落盘）、单题异常隔离、并发可配（embedding 限流预算）、强裁判模型关思考

• LoRA 三组对比实验（详见 docs/ft-compare-report.md）：

  • SFT 语料 791 条由知识库蒸馏（6 种问法变体），LoRA rank16 仅训 0.96% 参数，RTX 4080 SUPER 上 3.6 分钟完成训练

  • vLLM 单进程双模型名（基座 / LoRA）保证三组推理参数完全一致

  • 结论：微调单独用反而降分且丢失拒答边界感（60%→10%），检索闸门才是机制性防线（100%）——微调塑风格，检索供事实

LoRA adapter（115MB）超出 git 单文件限制，见仓库 Release 下载，挂载到任意 Qwen2.5-3B-Instruct 基座即可复现。

快速开始

方式一：Docker 一键部署（推荐）

cp .env.example .env   # 填入 ZHIPU_API_KEY（EMBEDDING_*/LANGFUSE_* 可选）
docker compose up -d --build
# 打开 http://localhost:8090

Nginx 前端(8090) → FastAPI 后端 → Qdrant 向量库三服务编排；数据落宿主机 ./data 卷；SSE 经 Nginx 反代透传（proxy_buffering off）。

方式二：本地开发

uv sync                                  # 需先 pip install uv
cp .env.example .env                     # 填入 ZHIPU_API_KEY
docker compose up -d qdrant              # 启动向量库
.venv/Scripts/python.exe scripts/smoke_test.py
.venv/Scripts/python.exe scripts/build_index.py   # 建索引（首次必须）
.venv/Scripts/python.exe scripts/run_server.py    # 后端 :8000
cd web && npm install && npm run dev               # 前端 :5174

接入 MCP 客户端（Claude Desktop / Cursor 等）

工具层已按 MCP 标准协议暴露（app/mcp_server.py，stdio 传输），任何 MCP 客户端可直接操作本项目的训练库/营养库/联网搜索。在客户端配置（如 Claude Desktop 的 claude_desktop_config.json）中添加：

{
  "mcpServers": {
    "fitpilot": {
      "command": "<项目根>/.venv/Scripts/python.exe",
      "args": ["<项目根>/app/mcp_server.py"]
    }
  }
}

验证：python scripts/test_mcp_server.py（stdio 握手 → 列工具 → 只读调用全链路）。

复现微调实验

训练与服务配置在 scripts/autodl/（LLaMA-Factory yaml + vLLM 双模型脚本），语料生成 scripts/gen_sft_data.py，三组对比评测 scripts/eval_finetune.py（支持断点续跑 / 原位重判 / 分通道裁判）。单卡 24GB+ 显存即可复现。

技术栈

后端 Python 3.12 · FastAPI · SSE · LangGraph · pydantic-settings · uv RAG Qdrant · BAAI/bge-m3（硅基流动） · rank-bm25 + jieba · RRF 融合 Agent 手写 function calling 循环 · 6 工具（FC/MCP 双协议暴露） · LangGraph StateGraph 四路意图路由 记忆 短期压缩摘要 + 长期画像（触发词/量纲正则 → LLM 抽取 → SQLite） 微调 LLaMA-Factory · Qwen2.5-3B-Instruct · vLLM（LoRA 热挂载） 前端 Vue3 · Vite · Element Plus · SSE 流式渲染 观测 LangFuse v5（OTel 架构） 部署 Docker · Nginx

项目结构

app/
├── core/       # 配置(模型可插拔) · LLM/Embedding双通道客户端 · LangFuse观测
├── rag/        # 切块(uuid5稳定ID) · 混合检索 · 拒答闸门 · 带引用生成
├── agent/      # LangGraph路由 · 工具循环(熔断) · 5个工具
├── memory/     # 短期压缩 + 长期画像抽取
└── api/        # FastAPI · SSE事件协议 · 会话历史
app/mcp_server.py  # MCP 服务：6 工具经标准协议(stdio)暴露给任意 MCP 客户端
data/
├── corpus/     # 知识库语料 31篇/183章
├── sft/        # 微调语料 791条
└── eval/       # 评测集248题 + 逐题明细
scripts/        # 建索引/评测/微调/部署脚本（autodl/ 为云端训练配置）
docs/           # 评测报告×3 · 微调对比 · badcase · 开发日志 · 观测统计

文档

• 评测报告：三路检索对比 —— 248 题，结论随 embedding 模型变化的方法论教训

• 微调三组对比 —— LoRA+RAG 96.9% 的完整实验记录

• Badcase 分析 —— 误拒/漏检/生成质量分类归因

• 开发日志 —— 7 条踩坑记录（评测四连败、429 静默吞错等）

• LangFuse 观测统计

Roadmap

• 联网搜索工具（分级知识源：本地知识库优先，联网只兜底时效性健身问题，回答标注来源层级）

• MCP 工具接入（6 工具暴露为 MCP server，Claude Desktop/Cursor 可直接操作，app/mcp_server.py）

• 检索重排（cross-encoder rerank）与查询改写

• 评测集扩充与多裁判一致性校验

开发里程碑

8 步完整开发路线全部完成（2026-10-28 ~ 10-31）：检索链路 → 带引用生成与首轮评测 → Agent 工具层 → LangGraph 路由与双层记忆 → FastAPI+SSE+Vue 前端 → LangFuse 观测与 Docker 部署 → 248 题全量评测与 LoRA 对比实验 → 开源发布。每一步的踩坑与排查过程记录在开发日志。