从零开始做一个 AI Agent以 Java Web RAG 学习助手为例本文是一套面向技术博客专栏的完整教程。它不是只讲概念而是以当前项目为真实案例从一个最小后端 API 出发逐步扩展到课程资料知识库、RAG 问答、轻量级 Agent Harness、工具注册表、执行 Trace、答案校验、学习记忆和前端工作台。用户可以上传课程课件、实验指导书、代码文件和配置文件。系统会解析资料、切块、建立检索索引用户提交学习任务后Agent 会判断任务类型、规划步骤、调用工具、生成回答、校验引用并把执行过程展示给前端。手把手带你运行项目下面以 Windows PyCharm 为例。1 用 PyCharm 打开项目打开目录E:\agent建议打开项目根目录不要只打开 backend。这样可以同时看到后端代码、设计文档、教程文档和 Git 配置。2 进入后端目录打开 PyCharm Terminalcd E:\agent\backend3 创建虚拟环境python-m venv.venv虚拟环境用于隔离依赖避免污染全局 Python。4 激活虚拟环境.\.venv\Scripts\activate激活成功后命令行前面通常会出现(.venv)5 安装项目依赖python-m pip install-e.[dev]含义pip install 安装 Python 包 -e editable可编辑安装本地代码改动立即生效 .[dev] 安装当前项目和开发依赖依赖配置在backend/pyproject.toml包括fastapiuvicornsqlalchemypydantic-settingspython-multipartpypdfpython-docxpython-pptxpytesthttpx6 创建 .env 文件copy.env.example.env默认配置APP_ENVlocal DATABASE_URLsqlite:///./rag_assistant.db UPLOAD_DIRuploads7 启动后端uvicorn app.main:app--reload启动成功后访问http://127.0.0.1:8000/docs2. Swagger 页面怎么用Swagger 是后端接口文档和测试页面。你主要使用上面的接口区域不需要直接操作底部的 Schemas。2.1 健康检查找到GET /api/health操作点开接口。点击 Try it out。点击 Execute。成功返回{status:ok,service:java-web-rag-assistant}说明后端服务正常。2.2 上传课程资料找到POST /api/documents操作点开接口。点击 Try it out。在 file 位置选择课程资料文件。点击 Execute。支持的文件类型包括PDFDOCXPPTXMarkdownTXTJavaXMLHTMLJSPJavaScriptCSSSQL成功后返回类似{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表示文档已经解析并切块入库可以参与问答。2.3 查看已上传文档找到GET /api/documents点击 Try it out再点击 Execute。它会返回当前系统里已经上传过的文档列表。2.4 删除文档找到DELETE /api/documents/{document_id}document_id 来自 GET /api/documents 返回结果里的 id 字段。删除时会删除SQLite 里的 document 记录SQLite 里的 chunk 记录本地 uploads 里的原始文件2.5 调用问答接口找到POST /api/chat/ask请求体示例{question:这个实验怎么做,question_type:lab_steps,session_id:null}返回结果示例{session_id:1,answer:回答内容,citations:[{chunk_id:1,document_id:1,source_title:实验一,source_path:JavaWeb实验指导书.pdf,source_page:3,score:0.45}]}重点看answer 系统回答 citations 引用来源2.6 question_type 怎么填常用问题类型lab_steps 实验步骤类问题 code_explanation 代码解释类问题 error_debugging 报错排查类问题 exam_prediction 考点预测类问题 chapter_summary 章节重点类问题实验步骤{question:登录注册实验怎么做,question_type:lab_steps,session_id:null}代码解释{question:LoginServlet 这段代码是什么意思,question_type:code_explanation,session_id:null}报错排查{question:Tomcat 启动失败怎么排查,question_type:error_debugging,session_id:null}考点预测{question:Servlet 生命周期可能怎么出题,question_type:exam_prediction,session_id:null}3. Swagger 里的 Schemas 是什么Swagger 页面底部的 Schemas 是接口数据结构说明。它不是接口而是告诉你请求体应该长什么样。响应结果有哪些字段。每个字段是什么类型。哪些字段可以为空。哪些字段必填。可以类比 Java 里的 DTO 类。例如 ChatAskRequest 表示提问接口请求格式{question:这个实验怎么做,question_type:lab_steps,session_id:null}类似 JavapublicclassChatAskRequest{privateStringquestion;privateStringquestionType;privateLongsessionId;}DocumentRead 表示文档接口返回格式{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。本系列总目录1. 项目总览从普通问答到课程学习 Agent2. 技术栈和工程结构FastAPI、Vue、SQLite、RAG、Agent Harness3. 后端基础设施配置、数据库、模型和 Schema4. 资料上传文件存储、文档记录和重建索引5. 文档解析PDF、Word、PPT、Markdown、代码文件如何进入系统6. 文本切块chunk、metadata、语义类型和 embedding 状态7. 检索系统关键词检索、向量检索、query rewrite 和 rerank8. LLM 与 Embedding Providerstub、OpenAI-compatible API 和本地模型接入9. Chat 问答入口兼容普通问答同时接入 Agent 主链路10. Agent Harness一次 Agent run 的生命周期11. Planner、Executor 与 Tool RegistryAgent 如何规划和调用工具12. Agent 校验、安全边界与资料不足处理13. Agent 记忆短期上下文、长期学习画像和推荐下一步14. 前端工作台资料管理、Agent 任务、Trace、历史和健康状态15. 测试、局限和演进从教学项目走向生产级 Agent SaaS16. 技术细节复现17. 附录一SQLite与SQLAlchemy18. 附录二接入大模型19. 附录三配置ollama本地大模型/deepseek线上大模型20. 附录四Agent Harness API详解21. 附录五Agent 工具注册表详解22. 附录六工程化 Agent思维23. 附录七安装embedding模型详解24. 附录八本项目为啥不用LangChain25. 附录九UI界面详解26. 附录十整体核心流程详解27. 附录十一项目中的相关注解28. 附录十二手把手带你运行项目