从零开始做一个AI Agent（附录十二）手把手带你运行项目-北京尧图网络

从零开始做一个 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. 附录十二手把手带你运行项目

从零开始做一个AI Agent（附录十二）手把手带你运行项目

相关推荐

家庭NAS选购终极指南：13款主流产品横评，从易用到专业全覆盖

RAG系统从Demo到生产：十二大痛点与工程化解决方案

AI Agent如何构建智能决策系统：从体育管理到通用工作流

更多资讯

装修物业要电工证？实操考试心里没底怕挂科，先搞清楚含金量

十堰换电工证值不值得考？别再被中介坑了

江苏盐城考电工证真实经历：工地太忙没时间复习怎么办？

福州考电工证需要多久？工地太忙根本没时间复习考试，郑州报考避坑指南来了

李云龙电工证考试真题与备考技巧：2026河南最新政策下的实战指南

电工证太难考？慈溪浒山考电工证的真实经历告诉你怎么搞定

今日更新

金坛办电工证在哪里？考前押题能帮你少走弯路

怎样查看真假电工证怎么考

史密斯内部电工证值不值得考？怕考不过白交培训费的看过来

本周精选

安监局电工证分数查询怎么查才能知道含金量高不高

新疆电工作业干活累吗良心建议助你避开考不过的坑

中牟县电工证怎么报名外省证能转吗

本月热门

面向复杂光照与角度的宠物面部识别鲁棒性增强策略

基于DRV8818与STM32的双极步进电机驱动方案实战解析

DRV8818PWPR+PIC18F45K80双极步进电机控制方案实战

读完文章，想聊聊您的网站？