Parser 子系统 / Parser Subsystem

Parser 子系统负责把不同格式的文档字节流转换为可分块的纯文本与基础元数据，是 IngestionService 进入分块和向量化之前的第一道内容标准化层。

本文聚焦解析器的职责边界、内置选择逻辑、可选 Docling 路径和扩展方式；具体对象、抽象基类和注册函数以 Parser API 参考中的自动渲染结果为准。

何时阅读本页 / When to Read This Page

适合在以下场景阅读本页：

需要确认某种文档格式是否能被当前系统解析
需要理解 content_type 和扩展名如何映射到具体 parser
需要判断 PDF/DOCX 在有无 docling 依赖时会走哪条路径
需要新增自定义 parser 并接入现有注册表

关键文件 / Key Files

路径	作用
`ai_service/services/parsers/__init__.py`	解析器注册表、扩展名映射和选择函数入口
`ai_service/services/parsers/base.py`	`BaseDocumentParser` 与 `ParseResult` 定义
`ai_service/services/parsers/text_parser.py`	纯文本与 Markdown 解析器
`ai_service/services/parsers/pdf_parser.py`	PDF 解析器
`ai_service/services/parsers/docx_parser.py`	DOCX 解析器
`ai_service/services/parsers/docling_parser.py`	可选的 Docling 高保真解析器
Parser API 参考	parser 对象与注册函数的源码级说明

核心类与函数 / Core Classes and Functions

BaseDocumentParser 所有解析器的统一抽象接口，定义 parse()、支持的 MIME 类型和扩展名。
ParseResult 统一表示解析结果，包含提取文本、metadata、页数和字符数。
get_parser 按 content_type 选择解析器，是摄取链路的主入口。
get_parser_for_extension 按扩展名选择解析器，适合在 MIME 类型缺失时做回退。
is_supported_content_type / is_supported_extension 用于上传前校验或控制面能力提示。

规则：本页不再手工复制 BaseDocumentParser 接口代码或各 parser 的完整方法签名。对象级细节请以 Parser API 参考为准。

选择逻辑 / Selection Logic

flowchart LR
    A[Uploaded file bytes] --> B[Resolve content_type or extension]
    B --> C{Supported type}
    C -->|text or markdown| D[TextDocumentParser]
    C -->|pdf| E{Docling available}
    C -->|docx| F{Docling available}
    E -->|Yes| G[DoclingDocumentParser]
    E -->|No| H[PDFDocumentParser]
    F -->|Yes| G
    F -->|No| I[DocxDocumentParser]
    D --> J[ParseResult]
    G --> J
    H --> J
    I --> J

运行规则

文本和 Markdown 始终走 TextDocumentParser
PDF 和 DOCX 在安装 docling 时优先走 DoclingDocumentParser
若 docling 不可用，则分别回退到 PDFDocumentParser 和 DocxDocumentParser
未识别的 MIME 类型或扩展名会在选择阶段直接报错，而不是进入后续摄取流程

支持格式 / Supported Formats

格式	扩展名	MIME 类型	默认解析器
纯文本	`.txt`	`text/plain`	`TextDocumentParser`
Markdown	`.md`, `.markdown`	`text/markdown` 等	`TextDocumentParser`
PDF	`.pdf`	`application/pdf`	`PDFDocumentParser` 或 `DoclingDocumentParser`
DOCX	`.docx`	`application/vnd.openxmlformats-officedocument.wordprocessingml.document`	`DocxDocumentParser` 或 `DoclingDocumentParser`

内置解析器 / Built-in Parsers

TextDocumentParser

适用于纯文本与 Markdown
支持多编码回退和换行符规范化
适合说明文档、FAQ、规则文本等轻结构内容

PDFDocumentParser

适用于未启用 Docling 时的 PDF 文本提取
基于 pypdf，会按页提取文本和基础元数据
对扫描件、图片型 PDF 或复杂版式文档的表现有限

DocxDocumentParser

适用于未启用 Docling 时的 Word 文档提取
基于 python-docx，提取段落、表格和部分文档属性
对复杂页眉页脚和高度定制结构的覆盖有限

DoclingDocumentParser

当 docling 可用时，PDF 和 DOCX 会优先走这一路径
目标是保留更高质量的结构信息，例如标题层级、表格和 Markdown 表达
适用于对结构保真度要求更高的文档摄取场景

扩展方式 / Extensibility

新增 parser 时，建议遵循以下最小流程：

实现 BaseDocumentParser
返回统一 ParseResult
在 ai_service/services/parsers/__init__.py 中注册 MIME 类型和扩展名映射
为新 parser 增加针对真实样本的测试

最小示例

from ai_service.services.parsers.base import BaseDocumentParser, ParseResult


class CSVDocumentParser(BaseDocumentParser):
    @property
    def supported_content_types(self) -> list[str]:
        return ["text/csv", "application/csv"]

    @property
    def supported_extensions(self) -> list[str]:
        return [".csv"]

    def parse(self, file_data: bytes, filename: str) -> ParseResult:
        decoded_text = file_data.decode("utf-8")
        return ParseResult(
            text=decoded_text,
            metadata={"filename": filename},
        )

不应在本页重复维护的内容 / What This Page Should Not Duplicate

以下内容应留在 API 参考或具体源码 docstring，而不是继续堆在模块页中：

BaseDocumentParser 的完整接口定义代码块
ParseResult 的完整字段表
get_parser()、get_parser_for_extension() 的详细参数和返回值说明
各 parser 类的完整方法签名和异常细节