从零开始做一个AI Agent（五）文档解析

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

本文是一套面向技术博客专栏的完整教程。它不是只讲概念，而是以当前项目为真实案例，从一个最小后端 API 出发，逐步扩展到课程资料知识库、RAG 问答、轻量级 Agent Harness、工具注册表、执行 Trace、答案校验、学习记忆和前端工作台。

示例项目定位：

text 复制代码

面向 Java Web 课程资料的 RAG Agent 学习助手

用户可以上传课程课件、实验指导书、代码文件和配置文件。系统会解析资料、切块、建立检索索引；用户提交学习任务后，Agent 会判断任务类型、规划步骤、调用工具、生成回答、校验引用，并把执行过程展示给前端。

专栏总目录

项目总览：从普通问答到课程学习 Agent
技术栈和工程结构：FastAPI、Vue、SQLite、RAG、Agent Harness
后端基础设施：配置、数据库、模型和 Schema
资料上传：文件存储、文档记录和重建索引
文档解析：PDF、Word、PPT、Markdown、代码文件如何进入系统
文本切块：chunk、metadata、语义类型和 embedding 状态
检索系统：关键词检索、向量检索、query rewrite 和 rerank
LLM 与 Embedding Provider：stub、OpenAI-compatible API 和本地模型接入
Chat 问答入口：兼容普通问答，同时接入 Agent 主链路
Agent Harness：一次 Agent run 的生命周期
Planner、Executor 与 Tool Registry：Agent 如何规划和调用工具
Agent 校验、安全边界与资料不足处理
Agent 记忆：短期上下文、长期学习画像和推荐下一步
前端工作台：资料管理、Agent 任务、Trace、历史和健康状态
测试、局限和演进：从教学项目走向生产级 Agent SaaS

第 5 篇：文档解析：PDF、Word、PPT、Markdown、代码文件如何进入系统

5.1 解析入口

文件：

text 复制代码

backend/app/services/parsers.py

核心函数：

python 复制代码

def parse_file(path: Path) -> ParsedDocument:

根据扩展名选择解析器：

text 复制代码

.java / .xml / .properties / .yml / .sql / .html / .jsp / .js / .css -> plain code
.md / .txt -> plain text
.pdf -> pypdf
.docx -> python-docx
.pptx -> python-pptx

5.2 ParsedDocument 和 ParsedSection

解析结果不是直接写字符串，而是结构化对象：

python 复制代码

@dataclass(frozen=True)
class ParsedSection:
    text: str
    content_type: str
    source_path: str
    source_page: int | None = None
    language: str | None = None

python 复制代码

@dataclass(frozen=True)
class ParsedDocument:
    title: str
    sections: list[ParsedSection]

这样做的好处是：

text 复制代码

1. PDF / PPT 可以保留页码。
2. 代码文件可以保留 language。
3. chunk 阶段可以继承 source_path 和 source_page。
4. citation 可以回到具体来源。

5.3 PDF 解析

PDF 使用 pypdf.PdfReader：

text 复制代码

逐页读取
-> page.extract_text()
-> 每页一个 ParsedSection
-> source_page = 页码

适合教材、讲义、实验指导书。

5.4 DOCX 解析

Word 使用 python-docx：

text 复制代码

读取 paragraphs
-> 过滤空段落
-> 合并成文本
-> 作为一个 ParsedSection

5.5 PPTX 解析

PPT 使用 python-pptx：

text 复制代码

遍历 slides
-> 遍历 shapes
-> 提取 shape.text
-> 每页幻灯片一个 ParsedSection

5.6 代码和纯文本解析

代码和文本统一走 _parse_plain_file：

text 复制代码

读取 UTF-8 文本
-> content_type = code 或 text
-> language = java / xml / jsp / sql / ...

这对于 Java Web 项目非常重要，因为很多知识在代码和配置文件里，而不是只在课件里。