XiaoGuan（小官）

思政课程智能问答系统。基于 RAG（检索增强生成） + 领域微调 双通道架构，对高校思想政治理论课教材进行语义检索与可控生成，提供准确、规范的课程问答服务。

项目概览

本项目按工程阶段划分为四个模块：

阶段	目录	职责
Phase 1 — 数据	Phase1_Data/	思政课本 Markdown 语料 + 评估题库
Phase 2 — 微调	Phase2_Tuning/	LoRA 微调 Qwen2.5-7B-Instruct，改善公文/官宣语体
Phase 3 — RAG	Phase3_RAG/	向量索引构建 + 检索增强生成管线
Phase 4 — Web	Phase4_Web/	Web 前端，基座模型与微调模型 RAG 效果并行对比

架构

Phase1_Data/                  Phase2_Tuning/
  思政课本 (.md)  ──→  Chunk   DISC-Law-SFT ──→ LoRA ──→ GaryAgasa/xiaoguan
       │                                              (HuggingFace)
       ▼
Phase3_RAG/                   Phase4_Web/
  ChromaDB + e5-large-v2        FastAPI ──→ 浏览器
       │                            │
       ▼                            ▼
  vLLM (Qwen2.5-7B)  ←──── 双模型对比页面

检索链路： 用户提问 → Embedding 向量检索 → ChromaDB 取 Top-K 段落 → 拼接 Prompt → vLLM 生成 → 返回回答

微调策略： 基于 Qwen2.5-7B-Instruct，使用 DISC-Law-SFT（中文法律 SFT 数据集，~17 万条）进行 LoRA 低秩适配（rank=16），目的是改善模型的规范化书面表达能力，而非注入领域知识。领域知识由 RAG 阶段的教材检索提供。

硬件需求

组件	最低要求	推荐配置
向量索引构建	CPU / 4 GB RAM	GPU（任意显存 ≥ 2 GB）
vLLM 推理 (7B)	16 GB 显存	24 GB 显存（RTX 3090/4090）
LoRA 微调 (7B)	16 GB 显存	24 GB 显存（RTX 3090/4090）
Phase4 双模型对比	两张 24 GB GPU	两张 RTX 3090/4090

快速开始

1. 克隆仓库

git clone <repo-url> && cd XiaoGuan

2. 构建向量索引（Phase 3）

cd Phase3_RAG
pip install -r requirements.txt
python build_index.py          # 首次运行，构建 ChromaDB
python build_index.py --rebuild  # 需要重建时

3. 部署模型服务（Phase 3 + Phase 4）

基座模型和微调模型需分别部署到两张 GPU 上：

# 终端 1 — 基座模型 (卡 0，端口 8000)
CUDA_VISIBLE_DEVICES=0 vllm serve Qwen/Qwen2.5-7B-Instruct --port 8000

# 终端 2 — 微调模型 (卡 1，端口 8001)
CUDA_VISIBLE_DEVICES=1 vllm serve GaryAgasa/xiaoguan --port 8001

4. 启动 Web 对比服务（Phase 4）

cd Phase4_Web
pip install -r requirements.txt
cp .env.example .env           # 按需编辑 vLLM 地址
python app.py                  # 默认 http://0.0.0.0:5000

5. 命令行问答（Phase 3）

cd Phase3_RAG
python query.py -q "如何理解中国式现代化？"
python query.py                # 交互模式

数据说明

教材语料

5 本高等教育出版社思政课教材的 Markdown 文本，位于 Phase1_Data/：

• 习近平新时代中国特色社会主义思想概论（习概）
• 马克思主义基本原理（马原）
• 毛泽东思想和中国特色社会主义理论体系概论（毛概）
• 中国近现代史纲要（近纲）
• 思想道德与法治（思修）

微调数据

DISC-Law-SFT — 复旦大学发布的中文法律 SFT 数据集。选用法律文本作为微调语料，是因为法律与思政/公文文本在语言风格上高度一致：严谨、规范、书面化。

评估数据集

29 道问答题，覆盖全部 5 门课程，每门课一个 JSON 文件（Phase1_Data/eval/）。可直接在 Phase4 Web 前端下拉选择，或在命令行通过 evaluate.py 批量运行。

模型发布

微调后的模型已发布至 HuggingFace Hub：

GaryAgasa/xiaoguan

目录结构

XiaoGuan/
├── README.md
├── Phase1_Data/               # 原始数据
│   ├── 习概.md
│   ├── 马原.md
│   ├── 毛概.md
│   ├── 近纲.md
│   ├── 思修.md
│   └── eval/                  # 评估题库（5 门课 × JSON）
├── Phase2_Tuning/             # 模型微调
│   ├── README.md
│   ├── configs/               # LLaMA-Factory 训练配置
│   ├── scripts/               # 数据准备 / 训练 / 合并 / 评估 / 发布
│   ├── data/                  # 训练数据
│   └── output/                # LoRA adapter + merged model
├── Phase3_RAG/                # RAG 管线
│   ├── README.md
│   ├── config.py              # 全局配置
│   ├── build_index.py         # 文档切片 + 向量化 + ChromaDB
│   ├── query.py               # RAG 检索 + vLLM 生成
│   ├── evaluate.py            # 批量评估脚本
│   ├── deploy_vllm.sh         # vLLM 部署脚本
│   └── vector_db/             # ChromaDB 持久化目录
└── Phase4_Web/                # Web 对比前端
    ├── README.md
    ├── app.py                 # FastAPI 后端
    ├── requirements.txt
    ├── run.sh                 # 一键启动脚本
    ├── templates/
    │   └── index.html         # 双栏对比页面
    └── static/
        ├── style.css
        └── script.js

技术栈

层级	技术选型
基座模型	Qwen2.5-7B-Instruct
微调方法	LoRA（LLaMA-Factory）
微调数据	DISC-Law-SFT
Embedding	intfloat/e5-large-v2
向量数据库	ChromaDB
推理引擎	vLLM（OpenAI-compatible API）
Web 框架	FastAPI + Uvicorn
前端	Vanilla HTML/CSS/JS（零依赖）

License

Apache-2.0