从零开始做一个AI Agent（六）文本切块：chunk、metadata、语义类型和 embedding 状态

从零开始做一个 AI Agent以 Java Web RAG 学习助手为例本文是一套面向技术博客专栏的完整教程。它不是只讲概念而是以当前项目为真实案例从一个最小后端 API 出发逐步扩展到课程资料知识库、RAG 问答、轻量级 Agent Harness、工具注册表、执行 Trace、答案校验、学习记忆和前端工作台。示例项目定位面向 Java Web 课程资料的 RAG Agent 学习助手用户可以上传课程课件、实验指导书、代码文件和配置文件。系统会解析资料、切块、建立检索索引用户提交学习任务后Agent 会判断任务类型、规划步骤、调用工具、生成回答、校验引用并把执行过程展示给前端。专栏总目录项目总览从普通问答到课程学习 Agent技术栈和工程结构FastAPI、Vue、SQLite、RAG、Agent Harness后端基础设施配置、数据库、模型和 Schema资料上传文件存储、文档记录和重建索引文档解析PDF、Word、PPT、Markdown、代码文件如何进入系统文本切块chunk、metadata、语义类型和 embedding 状态检索系统关键词检索、向量检索、query rewrite 和 rerankLLM 与 Embedding Providerstub、OpenAI-compatible API 和本地模型接入Chat 问答入口兼容普通问答同时接入 Agent 主链路Agent Harness一次 Agent run 的生命周期Planner、Executor 与 Tool RegistryAgent 如何规划和调用工具Agent 校验、安全边界与资料不足处理Agent 记忆短期上下文、长期学习画像和推荐下一步前端工作台资料管理、Agent 任务、Trace、历史和健康状态测试、局限和演进从教学项目走向生产级 Agent SaaS第 6 篇文本切块chunk、metadata、语义类型和 embedding 状态6.1 为什么要 chunk大文档不能直接进入检索和 Prompt。chunk 的作用是控制单段长度 保留来源信息 支持局部检索 支持局部引用 支持 embedding6.2 切块入口文件backend/app/services/chunking.py入口函数defchunk_parsed_document(parsed:ParsedDocument,max_chars:int900,overlap_chars:int120,)-list[ChunkData]:默认策略每块最大 900 字符 相邻块重叠 120 字符重叠的意义是避免知识点刚好被切断。6.3 ChunkData 结构dataclass(frozenTrue)classChunkData:content:strchunk_type:strsource_title:strsource_path:strsource_page:int|Nonelanguage:str|Nonemetadata:dict[str,Any]这些字段最终会写入chunks表。6.4 LLM metadata enrichment每个 chunk 会尝试调用 LLM 生成元数据semantic_type entities summary允许的 semantic_typeconcept lab_step code error exam_hint configuration general如果 LLM 不可用系统会兜底代码 chunk - semantic_type code 其他 chunk - semantic_type general这体现了项目的稳定性原则LLM 增强可以失败但核心入库流程不能因为 LLM 不可用就完全不可用。6.5 文档入库状态流转文件backend/app/services/ingestion.py状态流转uploaded - processing - chunked - indexed失败时failed error_message入库流程会先删除旧 chunks再写入新 chunks避免 reindex 后出现重复数据。