从零开始做一个 AI Agent（附录十一）项目中的相关注解

原创于 2026-08-22 09:22:57 发布 · 174 阅读

2 ·

本内容遵循CC 4.0 BY-SA版权协议

GEO检测

收录于

从零开始做一个 AI Agent

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

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

在这里插入图片描述

项目中的相关注解

@dataclass(frozen=True)

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

拆开看：

from dataclasses import dataclass

@dataclass(frozen=True)
class RetrievedChunk:
    chunk_id: int
    document_id: int
    content: str
    score: float

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

你就可以这样创建对象：

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

不用自己手写：

class RetrievedChunk:
    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)
class RetrievedChunk:
    chunk_id: int
    document_id: int
    content: str
    source_title: str | None
    source_path: str | None
    source_page: int | None
    language: str | None
    score: 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. 附录十二：手把手带你运行项目

标签

#agent #AI #rag