企业官网建设流程全解析

从零开始做一个 AI Agent：以 Java Web RAG 学习助手为例

🎯本文是一套面向技术博客专栏的完整教程。它不是只讲概念，而是以当前项目为真实案例，从一个最小后端 API 出发，逐步扩展到课程资料知识库、RAG 问答、轻量级 Agent Harness、工具注册表、执行 Trace、答案校验、学习记忆和前端工作台。
🎯用户可以上传课程课件、实验指导书、代码文件和配置文件。系统会解析资料、切块、建立检索索引；用户提交学习任务后，Agent 会判断任务类型、规划步骤、调用工具、生成回答、校验引用，并把执行过程展示给前端。

项目中的相关注解

@dataclass(frozen=True)

@dataclass(frozen=True)是 Python 里的一个装饰器，用来快速定义“数据对象”，并且让这个对象创建后不能再被修改。

拆开看：

fromdataclassesimportdataclass@dataclass(frozen=True)classRetrievedChunk:chunk_id:intdocument_id:intcontent:strscore:float

等价于：Python 自动帮你生成__init__、__repr__、__eq__等方法。

你就可以这样创建对象：

chunk=RetrievedChunk(chunk_id=1,document_id=10,content="LoginServlet 负责处理登录请求",score=0.8,)

不用自己手写：

classRetrievedChunk:def__init__(self,chunk_id,document_id,content,score):self.chunk_id=chunk_id self.document_id=document_id self.content=content self.score=score

frozen=True的意思是：对象创建之后字段不能改。

例如：

chunk.score=0.9

会报错：

dataclasses.FrozenInstanceError

所以：

@dataclass(frozen=True)

可以理解成：

定义一个轻量级数据结构，并且让它不可变

在你当前项目里：

@dataclass(frozen=True)classRetrievedChunk:chunk_id:intdocument_id:intcontent:strsource_title:str|Nonesource_path:str|Nonesource_page:int|Nonelanguage:str|Nonescore:float

它表示“检索出来的资料片段”。

加frozen=True的好处是：

• 防止后续代码误改检索结果
• 让数据对象更可靠
• 表示这个对象只是一个结果载体，不应该被业务逻辑继续修改

一句话：

@dataclass(frozen=True) = 自动生成数据类常用方法 + 创建后禁止修改字段。

本系列总目录

1. 项目总览：从普通问答到课程学习 Agent
2. 技术栈和工程结构：FastAPI、Vue、SQLite、RAG、Agent Harness
3. 后端基础设施：配置、数据库、模型和 Schema
4. 资料上传：文件存储、文档记录和重建索引
5. 文档解析：PDF、Word、PPT、Markdown、代码文件如何进入系统
6. 文本切块：chunk、metadata、语义类型和 embedding 状态
7. 检索系统：关键词检索、向量检索、query rewrite 和 rerank
8. LLM 与 Embedding Provider：stub、OpenAI-compatible API 和本地模型接入
9. Chat 问答入口：兼容普通问答，同时接入 Agent 主链路
10. Agent Harness：一次 Agent run 的生命周期
11. Planner、Executor 与 Tool Registry：Agent 如何规划和调用工具
12. Agent 校验、安全边界与资料不足处理
13. Agent 记忆：短期上下文、长期学习画像和推荐下一步
14. 前端工作台：资料管理、Agent 任务、Trace、历史和健康状态
15. 测试、局限和演进：从教学项目走向生产级 Agent SaaS
16. 技术细节复现
17. 附录一：SQLite与SQLAlchemy
18. 附录二：接入大模型
19. 附录三：配置ollama本地大模型/deepseek线上大模型
20. 附录四：Agent Harness API详解
21. 附录五：Agent 工具注册表详解
22. 附录六：工程化 Agent思维
23. 附录七：安装embedding模型详解
24. 附录八：本项目为啥不用LangChain
25. 附录九：UI界面详解
26. 附录十：整体核心流程详解
27. 附录十一：项目中的相关注解
28. 附录十二：手把手带你运行项目