CS-RAG 课程资料问答助手

CS-RAG 是一个面向课程资料场景的问答系统，支持文档上传、异步索引、关联资料对话、流式回答与模型配置管理。

项目定位

• 面向课程场景的 RAG 问答助手
• 优先使用上传资料回答问题
• 当检索证据不足时可回退通用模型回答
• 支持资料库管理与会话历史追踪

核心功能

1. 对话问答

• 普通问答：POST /ask
• 流式问答（SSE）：GET /ask/stream / POST /ask/stream
• 会话历史读取：GET /history
• 支持关联文件（file_ids）
• 回答支持引用片段与置信度

2. 资料库

• 文件上传：pdf/pptx/docx/txt
• 后台异步索引：上传接口快速返回，后台执行解析与索引
• 进度可视化：uploaded -> extracting -> chunking -> embedding -> upserting -> ready/failed
• 文件预览、删除、摘要
• 可配置上传目录与最大文件大小

3. 模型与设置

• 多模型管理：新增、编辑、删除、设默认、连通性测试
• 模型密钥不在模型列表明文返回（仅返回 api_key_configured）
• 应用设置支持资料库目录和上传大小限制

处理流程

A. 文档上传与索引流程

1. 前端上传文件到 /kb/upload
2. 后端落盘并写入 knowledge_files 记录（状态 uploaded）
3. 后台任务执行：
   • 文本提取（extracting）
   • 分块（chunking）
   • 向量阶段（embedding / upserting）
4. 索引成功：状态 ready
5. 索引失败：状态 failed，写入 error_message

B. 问答流程

1. 用户发起问题，可附带 file_ids
2. 后端执行检索与上下文构建
3. 调用大模型生成答案
4. 返回答案 + 引用 + 置信度（流式场景按 SSE 事件分段返回）

工作流程（技术链条）

本项目的完整技术链条如下：

用户输入 -> 向量语义检索 -> 知识图谱关联扩展 -> 语义相关度排序 -> LLM 深度分析 -> 前端可视化输出

对应实现可概括为：

• 后端基于 FastAPI + AsyncIO 提供 RESTful API 与高并发处理能力。
• 前端基于 Vue 3 + Element Plus 快速构建交互界面，支持流式输出与资料关联操作。
• 检索层使用 MaxKB（向量检索）并结合 Neo4j 做知识关联扩展。
• 大模型层接入 OpenAI 兼容接口（默认 Qwen 兼容配置）完成问答与总结生成。
• 文档处理链路使用 pypdf、python-docx、python-pptx 等组件完成解析、切分与结果组织。

这条链路覆盖了“数据输入 -> 特征抓取 -> 知识串联 -> 智能解析 -> 结果呈现”的全流程。

技术栈

• 前端：Vue 3、Vite、Element Plus、Pinia、Axios、TypeScript
• 后端：FastAPI、SQLAlchemy、Alembic、Pydantic
• 数据库：MySQL
• 图谱扩展：Neo4j
• 检索/知识库：MaxKB（可降级）
• 模型接入：OpenAI 兼容接口（默认 Qwen 兼容配置）
• 运行环境：Docker Compose（依赖服务）+ 本地 Node/Python

目录结构

• frontend/：前端代码
• backend/：后端代码
• docker/：依赖服务编排
• API.md：接口文档
• WINDOWS_SETUP.md：Windows 从零部署指南
• PROGRESS.md：项目进度

快速开始

建议按下面顺序：

1. 按 WINDOWS_SETUP.md 完成环境部署
2. 启动后端与前端
3. 打开前端页面上传资料并发起问答
4. 如需接口联调，查看 API.md

端口约定（默认）

• 前端：http://localhost:5173
• 后端：http://localhost:8000
• 后端文档：http://localhost:8000/docs

补充说明

• 生产环境建议使用反向代理与 HTTPS
• 若使用外部模型 API，请在设置页或环境变量中正确配置密钥与 Base URL