从零开始做一个课程资料 RAG Agent 问答系统（二）项目运行

从零开始做一个课程资料 RAG Agent 问答系统

本文是一份面向初学者的手把手开发教程，基于当前仓库里的后端 MVP 项目和本轮对话整理而成。

项目目标：做一个面向高校单门 Java Web 开发课程的资料问答系统。教师上传课程 PPT、教材 PDF、实验指导书、示例代码后，学生可以围绕课程资料提问：

这章重点是什么？
实验怎么做？
这段代码是什么意思？
考试可能怎么出题？
报错应该怎么排查？

当前版本是后端 MVP。它已经具备文件上传、资料解析、文本切块、本地检索、问答接口和引用来源返回能力，但还没有前端页面，也还没有接真实大模型 API。

5. 从零开始运行项目

下面以 Windows + PyCharm 为例。

5.1 用 PyCharm 打开项目

打开目录：

text 复制代码

E:\agent

建议打开项目根目录，不要只打开 backend。这样可以同时看到后端代码、设计文档、教程文档和 Git 配置。

5.2 进入后端目录

打开 PyCharm Terminal：

powershell 复制代码

cd E:\agent\backend

5.3 创建虚拟环境

powershell 复制代码

python -m venv .venv

虚拟环境用于隔离依赖，避免污染全局 Python。

5.4 激活虚拟环境

powershell 复制代码

.\.venv\Scripts\activate

激活成功后，命令行前面通常会出现：

text 复制代码

(.venv)

5.5 安装项目依赖

powershell 复制代码

python -m pip install -e ".[dev]"

含义：

text 复制代码

pip install      安装 Python 包
-e               editable，可编辑安装，本地代码改动立即生效
.[dev]           安装当前项目和开发依赖

依赖配置在：

text 复制代码

backend/pyproject.toml

包括：

fastapi
uvicorn
sqlalchemy
pydantic-settings
python-multipart
pypdf
python-docx
python-pptx
pytest
httpx

5.6 创建 .env 文件

powershell 复制代码

copy .env.example .env

默认配置：

env 复制代码

APP_ENV=local
DATABASE_URL=sqlite:///./rag_assistant.db
UPLOAD_DIR=uploads

5.7 启动后端

powershell 复制代码

uvicorn app.main:app --reload

启动成功后访问：

text 复制代码

http://127.0.0.1:8000/docs

6. Swagger 页面怎么用

Swagger 是后端接口文档和测试页面。你主要使用上面的接口区域，不需要直接操作底部的 Schemas。

6.1 健康检查

找到：

text 复制代码

GET /api/health

操作：

点开接口。
点击 Try it out。
点击 Execute。

成功返回：

json 复制代码

{
  "status": "ok",
  "service": "java-web-rag-assistant"
}

说明后端服务正常。

6.2 上传课程资料

找到：

text 复制代码

POST /api/documents

操作：

点开接口。
点击 Try it out。
在 file 位置选择课程资料文件。
点击 Execute。

支持的文件类型包括：

PDF
DOCX
PPTX
Markdown
TXT
Java
XML
HTML
JSP
JavaScript
CSS
SQL

成功后返回类似：

json 复制代码

{
  "id": 1,
  "filename": "JavaWeb实验指导书.pdf",
  "file_type": "pdf",
  "status": "indexed",
  "error_message": null,
  "created_at": "2026-06-20T10:00:00",
  "updated_at": "2026-06-20T10:00:00"
}

重点看 status。如果 status 是 indexed，表示文档已经解析并切块入库，可以参与问答。

6.3 查看已上传文档

找到：

text 复制代码

GET /api/documents

点击 Try it out，再点击 Execute。

它会返回当前系统里已经上传过的文档列表。

6.4 删除文档

找到：

text 复制代码

DELETE /api/documents/{document_id}

document_id 来自 GET /api/documents 返回结果里的 id 字段。

删除时会删除：

SQLite 里的 document 记录
SQLite 里的 chunk 记录
本地 uploads 里的原始文件

6.5 调用问答接口

找到：

text 复制代码

POST /api/chat/ask

请求体示例：

json 复制代码

{
  "question": "这个实验怎么做？",
  "question_type": "lab_steps",
  "session_id": null
}

返回结果示例：

json 复制代码

{
  "session_id": 1,
  "answer": "回答内容",
  "citations": [
    {
      "chunk_id": 1,
      "document_id": 1,
      "source_title": "实验一",
      "source_path": "JavaWeb实验指导书.pdf",
      "source_page": 3,
      "score": 0.45
    }
  ]
}

重点看：

text 复制代码

answer       系统回答
citations    引用来源

6.6 question_type 怎么填

常用问题类型：

text 复制代码

lab_steps          实验步骤类问题
code_explanation   代码解释类问题
error_debugging    报错排查类问题
exam_prediction    考点预测类问题
chapter_summary    章节重点类问题

实验步骤：

json 复制代码

{
  "question": "登录注册实验怎么做？",
  "question_type": "lab_steps",
  "session_id": null
}

代码解释：

json 复制代码

{
  "question": "LoginServlet 这段代码是什么意思？",
  "question_type": "code_explanation",
  "session_id": null
}

报错排查：

json 复制代码

{
  "question": "Tomcat 启动失败怎么排查？",
  "question_type": "error_debugging",
  "session_id": null
}

考点预测：

json 复制代码

{
  "question": "Servlet 生命周期可能怎么出题？",
  "question_type": "exam_prediction",
  "session_id": null
}

7. Swagger 里的 Schemas 是什么

Swagger 页面底部的 Schemas 是接口数据结构说明。

它不是接口，而是告诉你：

请求体应该长什么样。
响应结果有哪些字段。
每个字段是什么类型。
哪些字段可以为空。
哪些字段必填。

可以类比 Java 里的 DTO 类。

例如 ChatAskRequest 表示提问接口请求格式：

json 复制代码

{
  "question": "这个实验怎么做？",
  "question_type": "lab_steps",
  "session_id": null
}

类似 Java：

java 复制代码

public class ChatAskRequest {
    private String question;
    private String questionType;
    private Long sessionId;
}

DocumentRead 表示文档接口返回格式：

json 复制代码

{
  "id": 1,
  "filename": "JavaWeb实验指导书.pdf",
  "file_type": "pdf",
  "status": "indexed",
  "error_message": null,
  "created_at": "2026-06-20T10:00:00",
  "updated_at": "2026-06-20T10:00:00"
}

实际使用时，主要点接口，不需要直接操作 Schemas。