企业官网建设流程全解析

AutoRAG Langchain Parse 模块实战指南：用 LangChain Document Loaders 解析 PDF、CSV、JSON 等原始文档

【免费下载链接】AutoRAGAutoRAG: Now your agent can find anything in your computer. It gets smarter if you are using it frequently.项目地址: https://gitcode.com/GitHub_Trending/au/AutoRAG

AutoRAG 的langchain_parse解析模块将 LangChain 生态的 Document Loaders 直接接入 RAG 数据构建管线，让开发者仅凭一行 YAML 配置即可完成 PDF、CSV、JSON、Markdown、HTML、XML 乃至混合目录的文本抽取。读完本文，你将掌握每种文件类型的可用解析方法、JSON 必需的jq_schema参数、调用外部 API 的解析方式，以及如何注册 LangChain 中未被内置的 Loader 来扩展 AutoRAG。

为什么需要 Langchain Parse

RAG 的效果上限取决于输入语料的质量：如果原始文档没有被正确解析，后续的分块（Chunk）与检索（Retrieval）优化都将事倍功半。AutoRAG 在数据创建阶段（Data Creation）提供了 Parse 步骤，而langchain_parse是其中最通用、覆盖文件类型最广的解析模块——它直接复用 LangChain 社区维护的langchain_community.document_loaders，你不需要自己编写任何文件解析代码。

从源码结构看，langchain_parse的实现位于 legacy/autorag/data/parse/langchain_parse.py，外层由 legacy/autorag/data/parse/base.py 中的parser_node装饰器统一包装，负责 glob 匹配文件、按file_type过滤、注入默认参数，并把解析结果统一输出为包含texts、path、page、last_modified_datetime四列的 DataFrame。也就是说，无论你选用哪种 Loader，产出的数据格式对下游分块模块都是完全一致的。

按文件类型选择解析方法

AutoRAG 根据文件扩展名把解析需求分为七类：PDF、CSV、JSON、Markdown、HTML、XML 以及所有文件（all_files）。每种类型都有对应的 LangChain Loader 可供选择，下面逐一说明。

1. PDF

PDF 是 RAG 最常见的输入格式，AutoRAG 内置了 6 种 PDF 解析方法，均来自langchain_community.document_loaders：

• pdfminer（PDFMiner）
• pdfplumber（PDFPlumber）
• pypdfium2（PyPDFium2）
• pypdf（PyPDF）
• pymupdf（PyMuPDF）
• unstructuredpdf（UnstructuredPDF）

YAML 配置示例：

modules: - module_type: langchain_parse parse_method: [ pdfminer, pdfplumber ]

在 legacy/autorag/data/init.py 中可以看到这 6 个 Loader 被注册进parse_modules字典，对应的键名均为小写形式。需要特别留意的是，PDF 解析方法的page输出行为不同：在 langchain_parse.py 中，只有pymupdf、pdfplumber、pypdf、pypdfium2会按页输出（pages = list(range(1, len(documents) + 1))），而pdfminer的pages恒为-1。这一点在 legacy/tests/autorag/data/parse/test_langchain_parse.py 中有明确验证：test_langchain_parse_single_pdf断言pdfminer的pages == [-1]，而test_langchain_parse_single_pdf_pages断言pymupdf对同一份两页 PDF 输出pages == [1, 2]。

2. CSV

CSV 使用 LangChain 的 CSV Loader，解析方法名为csv：

modules: - module_type: langchain_parse parse_method: csv

3. JSON

JSON 解析使用json方法，必须提供jq_schema参数——它是一条 jq 查询表达式，用于从 JSON 文件中抽取需要进入语料的文本内容。这是所有解析方法中唯一带"必填参数"的类型，因为 JSON 的字段结构完全由你的数据决定，框架无法猜测哪一层才是正文。

- module_type: langchain_parse parse_method: json jq_schema: .messages[].content

在测试 test_langchain_parse.py 中，jq_schema=".content"会把样本 JSON 解析为["This is a sample JSON file"]，可见jq_schema直接决定了抽取出的文本内容。官方样例配置 file_types_full.yaml 中同样使用.content作为演示。

4. Markdown

Markdown 使用 Unstructured 生态的 Markdown Loader，解析方法名为unstructuredmarkdown：

- module_type: langchain_parse parse_method: unstructuredmarkdown

5. HTML

HTML 使用基于 BeautifulSoup 的bshtml方法：

- module_type: langchain_parse parse_method: bshtml

6. XML

XML 使用unstructuredxml方法：

- module_type: langchain_parse parse_method: unstructuredxml

7. 所有文件（all_files）

当输入目录包含多种格式、或文件格式不易区分时，可以使用file_type: all_files，此时有三种全文件解析方法：

• directory：LangChain 的 DirectoryLoader，按目录批量加载；
• unstructured：Unstructured 全家桶，自动识别文件类型；
• upstagedocumentparse：Upstage 的 Document Parse 服务。

其中unstructured与upstagedocumentparse需要外部 API：

• Unstructured：需要设置环境变量UNSTRUCTURED_API_KEY；
• Upstage：需要设置环境变量UPSTAGE_API_KEY。

- module_type: langchain_parse parse_method: upstagedocumentparse

关于directory与unstructured的差异，源码中有明确的调用路径：在 langchain_parse.py 的parse_all_files中，unstructured传入的是文件路径列表（对应UnstructuredLoader，内部逐个调用UnstructuredFileLoader，见 legacy/autorag/data/init.py），而directory通过glob/path参数构造DirectoryLoader（这两个参数由 base.py 从data_path_glob自动拆分注入）。三种全文件方法会从文档元数据的source字段还原原始文件路径，页面数统一记为-1。

完整的 all_files 配置可以参考 all_files_full.yaml，其中并列展示了directory、unstructured、upstagedocumentparse以及 AutoRAG 的其他全文件解析模块（clova、llamaparse）。注意该文件注释明确说明：同一份配置里只能启用其中一个全文件方法，若需组合使用需拆成多个 YAML 分别运行。

注册未内置的解析方法

LangChain 的 Document Loaders 生态远不止上述内置项。如果你的需求恰好不在可用列表内（例如 PyPDFDirectoryLoader），AutoRAG 提供了非常轻量的扩展入口：直接向parse_modules字典注册即可。

from autorag.data import parse_modules from langchain_community.document_loaders import PyPDFDirectoryLoader parse_modules["pypdfdirectory"] = PyPDFDirectoryLoader

注册后，在 YAML 中即可直接使用：

- module_type: langchain_parse parse_method: pypdfdirectory

使用该机制时务必遵守一条约束：

注册到parse_modules的键（key）必须始终是小写。

这是因为 base.py 在装饰器中执行了parse_method = parse_method.lower()，且 langchain_parse.py 通过parse_modules[parse_method]直接索引字典，大小写不一致会导致 KeyError。此外，注册的 Loader 必须符合 LangChain 的通用接口约定——构造函数接收data_path（文件路径），并提供返回 Document 列表的load()方法；若该 Loader 能按页输出，它自然也会被pymupdf/pdfplumber等同等的按页逻辑正确处理。

与文件类型过滤、默认方法的配合

langchain_parse并非单独使用，它与parser_node装饰器的file_type过滤机制紧密配合：

• file_type: pdf时，base.py 会从 glob 匹配结果中筛出扩展名为.pdf的文件再交给解析器；
• 若省略parse_method，则对应扩展名使用默认方法：PDF 默认pdfminer、CSV 默认csv、Markdown 默认unstructuredmarkdown、HTML 默认bshtml、XML 默认unstructuredxml；
• JSON 没有默认方法，因为jq_schema必须由用户显式指定，无法省略。

同时langchain_parse的parse_method是必填校验项：在 base.py 中，若parse_method is None会直接抛出ValueError("parse_method is required for langchain_parse")，对应测试用例test_langchain_parse_requires_parse_method（见 test_langchain_parse.py）。

端到端运行示例

把上述知识串起来，一个完整的解析流程只需三步。

首先，定义解析配置 YAML（这里同时覆盖 PDF 与 JSON）：

modules: # PDF - module_type: langchain_parse file_type: pdf parse_method: pdfminer # JSON - module_type: langchain_parse file_type: json parse_method: json jq_schema: .content

然后，创建 Parser 实例并启动解析（完整示例见 legacy/docs/source/data_creation/parse/parse.md）：

from autorag.parser import Parser parser = Parser(data_path_glob="your/data/path/*.pdf") parser.start_parsing("your/path/to/parse_config.yaml")

其中data_path_glob支持 glob 通配符（如*.pdf、*），解析结果会写入项目目录：按文件类型生成独立的pdf.parquet、json.parquet等文件，并汇总为parsed_result.parquet，同时生成本次使用的 YAML 副本与summary.csv摘要。

输出列与页面语义

无论使用哪种解析方法，langchain_parse的输出统一包含以下列：

页面语义尤其值得关注：langchain_parse整体上不按页解析（与clova、table_hybrid_parse相反），因此多数方法pages为-1；只有pymupdf、pdfplumber、pypdf、pypdfium2四种方法会给出真实页号，便于下游做基于页码的溯源。测试用例test_langchain_parse_multiple_pdf_pages对此有精确断言：两页文档用pymupdf解析后pages == [1, 2]。

小结

langchain_parse是 AutoRAG 数据管线中连接"原始文件"与"可检索语料"的关键桥梁：内置 14 种主流 Loader 覆盖六类文件格式与混合目录；JSON 的jq_schema与 PDF 的按页输出等细节决定了最终语料质量；而parse_modules注册机制让 LangChain 生态的任何 Loader 都能以三行代码接入。合理选择解析方法、正确配置必填参数，是构建高质量 RAG 语料的第一步。

【免费下载链接】AutoRAGAutoRAG: Now your agent can find anything in your computer. It gets smarter if you are using it frequently.项目地址: https://gitcode.com/GitHub_Trending/au/AutoRAG