企业官网建设流程全解析

AutoRAG 数据解析模块 API 全解析：parser_node 装饰器与六大 Parse 模块的配置、调用与实现原理

【免费下载链接】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 数据流水线中的autorag.data.parse包展开，该包是 RAG 构建流程中「文档解析（Parsing）」阶段的唯一入口：它负责把原始文件（PDF、CSV、JSON、Markdown、HTML、XML 或任意格式）解析成结构化文本，为后续分块（chunking）、向量化与检索提供原料。读完本文，你将掌握该包的模块划分、统一的输入输出协议（texts / path / page / last_modified_datetime）、parser_node装饰器的行为，以及langchain_parse、clova_ocr、llama_parse、table_hybrid_parse四大解析器的参数细节与底层实现，并能在解析 YAML 配置中正确组合它们。

包结构与 API 索引

autorag.data.parse包共包含 6 个公开模块，正是 API 文档legacy/docs/source/api_spec/autorag.data.parse.rst所列的 Submodules：

从包入口 legacy/autorag/data/parse/init.py 可以看到，默认直接导出的是langchain_parse，其余模块通过module_type字符串在配置中按名加载，具体注册机制见下文parse_modules与get_support_modules。

统一协议：parser_node 装饰器（base 模块）

所有解析器都通过 legacy/autorag/data/parse/base.py 中的parser_node装饰器包装。它定义了整个解析阶段统一的数据契约：

def parser_node(func): @functools.wraps(func) @result_to_dataframe(["texts", "path", "page", "last_modified_datetime"]) def wrapper( data_path_glob: str, file_type: str, parse_method: Optional[str] = None, **kwargs, ) -> Tuple[List[str], List[str], List[int], List[datetime]]: ...

装饰器内部依次完成四件事：

1. 文件收集与存在性检查：用glob(data_path_glob)展开用户传入的路径模式，若匹配不到任何文件则抛出FileNotFoundError("data does not exits in {data_path_glob}")。
2. file_type 白名单校验：仅允许pdf、csv、json、md、html、xml、all_files七种取值，其余值直接assert失败，提示search type {file_type} is not supported。
3. 按类型筛选文件：除all_files外，仅保留os.path.basename(data_path).split(".")[-1] == file_type的文件，避免把无关格式喂给解析器。
4. 按函数名分发：langchain_parse要求parse_method非空（否则抛ValueError），且当parse_method == "directory"时会把 glob 拆成path（目录）与glob（文件名模式）两个参数传入；clova_ocr、llama_parse、table_hybrid_parse则直接把筛选后的路径列表透传。

包装函数返回的元组经过result_to_dataframe变为四列：texts（解析文本）、path（来源文件路径）、page（页码，非分页解析为 -1）、last_modified_datetime（文件最后修改时间，由_add_last_modified_datetime通过get_file_metadata补齐）。这套统一契约保证了无论底层用哪个解析器，下游 chunk 阶段拿到的 DataFrame 结构完全一致。

运行入口：run_parser（run 模块）

legacy/autorag/data/parse/run.py 的run_parser是解析阶段的总调度，签名如下：

def run_parser( modules: List[Callable], module_params: List[Dict], data_path_glob: str, project_dir: str, all_files: bool, )

它的职责包括：

• 自动补齐缺失文件类型的默认模块：default_map为pdf、csv、md、html、xml提供了默认解析器（例如 PDF 默认pdfminer、CSV 默认csv、Markdown 默认unstructuredmarkdown、HTML 默认bshtml、XML 默认unstructuredxml）。当数据目录中出现 YAML 未配置的文件类型时，会自动追加对应默认模块；但JSON 例外——源码显式抛错：JSON file type must have a jq_schema so you must set it in the YAML file.，因为 JSON 解析必须由用户提供jq_schema，无法默认推断。
• 过滤无效模块：移除那些file_type在数据集中根本不存在的模块配置，避免空跑。
• 并行执行与测速：每个模块经measure_speed包装执行，返回解析结果与执行时间。
• 按类型落盘：all_files=False时每个file_type保存为独立的<file_type>.parquet；all_files=True时只允许一个解析模块（多于一个直接抛ValueError），结果保存为parsed_result.parquet；最终还会把所有类型的解析结果合并写入project_dir/parsed_result.parquet，并生成summary.csv（含 filename、module_name、module_params、execution_time 列），便于回溯每次解析用的模块与耗时。

模块一：langchain_parse —— 本地多格式解析

langchain_parse（legacy/autorag/data/parse/langchain_parse.py）通过 LangChain 的 document loaders 解析文档，是零外部依赖成本的首选。

参数：data_path_list（文件路径列表）、parse_method（LangChain loader 名称，必填）、**kwargs（透传给 loader 实例的额外参数，如编码、分隔符等）。

两种执行路径：

• 批量模式（parse_method为pymupdf、pdfplumber、pypdf、pypdfium2、pdfminer、unstructuredpdf、csv、json、unstructuredmarkdown、bshtml、unstructuredxml等）：使用mp.Pool(num_workers)多进程并行，num_workers = mp.cpu_count()，逐文件调用langchain_parse_pure。该函数从parse_modulesparse_method创建 loader，调用.load()取文档列表，texts取自每个文档的page_content；仅 PDF 系列 loader（pymupdf、pdfplumber、pypdf、pypdfium2）会按文档序号生成真实页码（range(1, len(documents) + 1)），其余格式页码一律为-1。
• 整批模式（parse_method为directory或unstructured）：不拆文件，直接对整个目录/文件集合解析。directory模式下装饰器会把 glob 拆成path+glob传入；unstructured模式则把所有文件一次性交给UnstructuredLoader。此模式下没有逐页信息，页码统一填-1。

parse_modules 注册表

parse_method的合法取值由 legacy/autorag/data/init.py 中的parse_modules字典定义：

• PDF：pdfminer、pdfplumber、pypdfium2、pypdf、pymupdf、unstructuredpdf
• CSV：csv
• JSON：json（需配合 jq_schema）
• Markdown：unstructuredmarkdown
• HTML：bshtml
• XML：unstructuredxml
• 全部文件：directory、unstructured、upstagedocumentparse

其中upstagedocumentparse通过UpstageLayoutAnalysisLoader兼容适配（legacy/autorag/data/init.py），优先导入UpstageDocumentParseLoader，失败时回退到UpstageLayoutAnalysisLoader，并给出安装提示。

模块二：clova_ocr —— Naver Clova OCR 云端解析

clova_ocr（legacy/autorag/data/parse/clova.py）把 PDF 逐页转成图片后调用 Naver Clova OCR 识别文本，适合扫描件、图片型 PDF。

参数：

实现要点：

• 凭证解析顺序为「显式参数 > 环境变量」，两者都缺失时抛KeyError并提示设置方式。
• 先用 PyMuPDF（fitz）把 PDF 每页渲染为 PNG 字节流（pdf_to_images），同时生成{pdf_path, pdf_page}的页面映射（generate_image_info）。
• 通过aiohttp异步并发（process_batch按 batch 限流）调用clova_ocr_pure，请求体为 Clova OCR V2 协议：version: "V2"、images[].format: "png"、enableTableDetection字段随table_detection传入。
• 响应解析：逐字段拼接inferText，lineBreak为真时插入换行；若响应含tables，则调用json_to_html_table把 Clova 返回的表格单元格（含rowSpan/colSpan合并单元格信息）还原成带rowspan/colspan属性的 HTML<table>，追加到文本尾部——这样表格结构信息不会在解析中丢失。
• 返回的pages是真实页码（从 1 开始），path是原始 PDF 路径。

模块三：llama_parse —— LlamaCloud 解析（支持多模态）

llama_parse（legacy/autorag/data/parse/llamaparse.py）基于 LlamaIndex 的LlamaParse服务，需要设置LLAMA_CLOUD_API_KEY环境变量。

参数：

实现要点：

• 启用多模态时，_add_multimodal_params会把多模态参数并入 kwargs，并校验模型名合法性：支持openai-gpt4o、openai-gpt-4o-mini（读OPENAI_API_KEY）、anthropic-sonnet-3.5（读ANTHROPIC_API_KEY）、gemini-1.5-flash/gemini-1.5-pro（读GEMINI_API_KEY）；custom-azure-model目前明确NotImplementedError；未知模型名抛ValueError。
• 若use_own_key=True，则用vendor_multimodal_api_key显式覆盖环境变量。
• 解析用parse_instance.aload_data(data_path)异步加载，pages按文档数量从 1 递增，texts取自每个文档的.text。

模块四：table_hybrid_parse —— 含表/无表页面混合解析

table_hybrid_parse（legacy/autorag/data/parse/table_hybrid_parse.py)是专门为「PDF 中既有纯文本页又有表格页」设计的混合策略：把表格页交给表格能力更强的解析器，把文本页交给普通解析器，最后按页序合并，避免表格页在纯文本解析中被破坏。

参数：

执行流程（源码逻辑）：

1. 在临时目录下建text/与table/两个子目录。
2. save_page_by_table用PyPDF2.PdfReader逐页拆出单页 PDF，并用pdfplumber的page.extract_tables()判断该页是否含表格，含表页存入table_dir、纯文本页存入text_dir，同时维护「临时单页文件 → 原始 PDF」的映射。
3. get_each_module_result分别对两个目录的*glob 调用指定的解析模块（通过get_support_modules取回被parser_node包装前的原始函数执行），得到各自的(texts, paths)。
4. 合并两批结果，并按临时文件名排序（保证原始页序），再通过path_map_dict还原原始文件路径，从文件名xxx_page_N.pdf中解析出真实页码。
5. 返回texts / path / pages，临时目录随上下文自动清理。

配置示例：如何组合这些模块

解析阶段通过项目目录下的 parse YAML 配置驱动，模块清单如下：

最简配置（legacy/sample_config/parse/simple_parse.yaml）：仅用langchain_parse的pdfminer解析 PDF：

modules: - module_type: langchain_parse file_type: pdf parse_method: pdfminer

全文件类型配置（legacy/sample_config/parse/all_files_full.yaml）：file_type: all_files时只能同时启用一个模块（run_parser会校验），可从directory、unstructured、upstagedocumentparse、clova、llamaparse中任选其一，例如启用 Clova OCR 表格检测：

modules: - module_type: clova file_type: all_files table_detection: true

或启用 LlamaParse 多模态（韩语 markdown 输出 + GPT-4o-mini 视觉）：

modules: - module_type: llamaparse file_type: all_files result_type: markdown language: ko use_vendor_multimodal_model: true vendor_multimodal_model_name: openai-gpt-4o-mini

混合解析配置（legacy/sample_config/parse/parse_hybird.yaml）：表格页用 LlamaParse、文本页用 pdfplumber，二者结果自动按页序合并：

modules: - module_type: table_hybrid_parse file_type: pdf text_parse_module: langchain_parse text_params: parse_method: pdfplumber table_parse_module: llamaparse table_params: result_type: markdown language: ko use_vendor_multimodal_model: true vendor_multimodal_model_name: openai-gpt-4o-mini

其余更完整的示例（含多文件类型、OCR、多模态）可参考 legacy/sample_config/parse/file_types_full.yaml、legacy/sample_config/parse/parse_multimodal.yaml 与 legacy/sample_config/parse/parse_ocr.yaml。

模块选型建议与注意事项

综合源码实现，选择解析器时可参考以下结论（均以当前仓库代码为准）：

• 普通文本型 PDF / CSV / Markdown / HTML / XML：优先langchain_parse，零 API 成本、多进程并行、支持真实页码，适合绝大多数本地文件。
• 扫描件、图片型 PDF：选择clova_ocr，注意batch上限为 5，需提前配置CLOVA_URL/CLOVA_API_KEY（或写入 YAML）；若文档含表格且需要保留表格结构，务必开启table_detection: true。
• 复杂版面、需要表格/版面还原：选择llamaparse，可组合result_type: markdown与多模态模型；注意其多模态模型名白名单与对应 API Key 环境变量的约束。
• PDF 中表格与正文混杂：选择table_hybrid_parse，让不同解析器各司其职，再按页序合并，是兼顾成本与质量的最优解。
• JSON 必须显式配置jq_schema，否则run_parser会直接报错；all_files模式下只能配置一个解析模块。
• 所有解析器的输出都会被parser_node统一补齐last_modified_datetime列，并以 parquet 形式落盘到项目目录的parsed_result.parquet，summary.csv中记录了每个文件类型所用模块与平均执行时间，可作为解析效果对比的依据。

【免费下载链接】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