LlamaIndex 集成 Upstage 文档解析器：UpstageDocumentParseReader 与 UpstageLayoutAnalysisReader 实战指南

LlamaIndex 集成 Upstage 文档解析器：UpstageDocumentParseReader 与 UpstageLayoutAnalysisReader 实战指南

【免费下载链接】llama_indexLlamaIndex is the leading document agent and OCR platform项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index

本文基于 LlamaIndex 仓库中llama-index-readers-upstage集成包，系统讲解如何在 LlamaIndex 生态中接入 Upstage 的文档 AI 能力，实现 PDF、图片等文档中文本、表格、图例等版面元素的自动检测与提取。读完本文，你将掌握UpstageDocumentParseReader（推荐）与UpstageLayoutAnalysisReader（已弃用）两类 Reader 的完整参数语义、分页调用原理、输出拆分策略，以及如何在 RAG 流水线中把解析结果转换为 LlamaIndex 的Document节点。

一、集成包概览与安装

llama-index-readers-upstage是 LlamaIndex 官方维护的 Upstage 集成包，位于仓库的 llama-index-integrations/readers/llama-index-readers-upstage 目录。它封装了 Upstage Document AI 系列 API（布局分析 Layout Analysis 与文档解析 Document Parse），将版面检测结果以 LlamaIndex 标准Document对象返回，可直接接入索引、检索与问答流程。

该包在 pyproject.toml 中声明了两个核心依赖：

• pymupdf>=1.23.21,<2：用于在客户端本地读取 PDF 并完成分页切片；
• llama-index-core>=0.13.0,<0.15：提供BaseReader基类与Document数据模型。

包内暴露两个 Reader 类（见init.py）：

• UpstageDocumentParseReader：基于 Upstage Document Parse API 的解析器，支持输出 Markdown，是当前推荐入口；
• UpstageLayoutAnalysisReader：基于 Upstage Layout Analysis API 的解析器，官方文档已标记为 deprecated（弃用）。

安装方式：

pip install llama-index-readers-upstage

使用前需要先在 Upstage 控制台申请 API Key，并通过环境变量注入：

import os os.environ["UPSTAGE_API_KEY"] = "YOUR_API_KEY"

API Key 的读取由模块内的get_from_param_or_env辅助函数完成（见 base.py 与 document_parse.py）：优先使用构造参数，其次读取UPSTAGE_API_KEY环境变量，两者均缺失时抛出ValueError。

二、UpstageDocumentParseReader（推荐）

UpstageDocumentParseReader是当前推荐的文档解析入口，源码位于 document_parse.py，默认请求https://api.upstage.ai/v1/document-ai/document-parse端点，默认模型为document-parse。

2.1 构造参数

ocr参数的两种取值语义：auto表示仅对图片输入执行 OCR 推理，对于 PDF 或非图片文档，引擎直接从文档中提取文本与坐标而不做图像转换；force表示无论输入类型如何，都先把文件转换为图像再执行 OCR 推理后再做版面检测。因此，若输入不是 PDF 而ocr="auto"，会触发错误。

base64_encoding支持Category字面量：paragraph、table、figure、header、footer、caption、equation、heading1、list、index、footnote、chart（完整定义见 document_parse.py）。例如传入["table"]，即可获得文档中所有表格的 base64 图像编码，用于把版面元素从原图中裁剪出来单独存储。

2.2 加载数据

load_data/lazy_load_data方法接受单个或列表形式的str | pathlib.Path文件路径。示例用法（摘自包内 README.md）：

import os os.environ["UPSTAGE_API_KEY"] = "YOUR_API_KEY" from llama_index.readers.upstage import UpstageDocumentParseReader file_path = "/PATH/TO/YOUR/FILE.pdf" reader = UpstageDocumentParseReader() # 对超大文件，建议使用 lazy_load_data 逐页加载以降低内存占用 docs = reader.load_data(file_path=file_path) for doc in docs[:3]: print(doc)

lazy_load_data是生成器实现，核心逻辑位于 document_parse.py，其行为受构造时split参数控制：

• split="none"：整份文档合并为单个Document，extra_info中携带total_pages（总页数）、output_format与split；
• split="element"：每个版面元素（段落、表格、图等）生成一个独立Document，extra_info包含page（页码）、id（元素 ID）、category（元素类别），以及可选的coordinates与base64_encoding（见_element_document，document_parse.py）；
• split="page"：同一页内的元素按页码聚合为一个Document，extra_info中的coordinates为该页所有元素坐标的列表（见_page_document，document_parse.py）。

当输入是 PDF 时，解析并非一次完成：Reader 使用 PyMuPDF（fitz）打开文件，按DEFAULT_NUMBER_OF_PAGE = 10页为一块进行切片，逐块向 API 发起请求（见_split_and_request，document_parse.py），这样能规避大文件的请求体大小限制并降低单次失败的影响面。当输入不是 PDF（如图片）时，则直接把文件字节流放入multipart表单发送。

请求的组装细节见_get_response（document_parse.py）：以Bearer <api_key>作为 Authorization 头，ocr、model、output_formats（形如['html']的字符串表示）、coordinates、base64_encoding一并作为表单数据提交；响应中的elements列表即为版面元素数组。异常处理覆盖了 HTTP 错误、请求异常、JSON 解码错误与兜底异常，全部以ValueError抛出并携带服务端错误详情（如HTTP error: {e.response.text}）。

2.3 输出格式与内容解析

API 返回的每个元素包含content字段，parse_output函数（document_parse.py）根据output_format取出对应的text、html或markdown子字段作为Document.text。这意味着同一版面元素可以按需选择纯文本（便于 embedding）、HTML（保留排版）或 Markdown（便于直接进入知识库）三种形态之一。

三、UpstageLayoutAnalysisReader（已弃用）

UpstageLayoutAnalysisReader是基于 Layout Analysis API 的旧版解析器，源码位于 base.py，默认请求https://api.upstage.ai/v1/document-ai/layout-analysis。包内 README 已明确将其标记为 deprecated，新项目建议直接使用UpstageDocumentParseReader，但该 Reader 的接口设计仍有参考价值，且存量代码可能继续使用。

3.1 构造参数

exclude支持的类别包括：paragraph、caption、table、figure、equation、footer、header。默认排除页眉页脚，这一设计对 RAG 场景很友好——避免把重复的导航文本切进检索单元。use_ocr=True时会调用 OCR 模型，可处理图片格式文档，但推理耗时相应增加。

3.2 加载数据与输出控制

与新版不同，旧版把output_type与split作为load_data/lazy_load_data的调用参数传入（见 base.py）：

• file_path（必填）：单个或列表形式的str | pathlib.Path路径；
• output_type（可选，默认"html"）：既可以是"text"/"html"字符串，也可以是形如{"paragraph": "text", "table": "html"}的字典，实现按类别分别指定输出格式——未在字典中指定的类别，且未被exclude排除的，回退使用html。这一能力由parse_output实现（base.py）；
• split（可选，默认"none"）："none"不拆分，"page"按页聚合，"element"按版面元素拆分。

_element_document会把元素渲染为Document，其extra_info含page、id、type、split以及序列化后的bounding_box（base.py）；_page_document则把同页元素文本用空格拼接成一个Document（base.py）。PDF 输入同样按每 10 页一块切片请求（DEFAULT_NUMBER_OF_PAGE），并在_get_response中按exclude过滤元素后再返回（base.py）。

示例用法（摘自包内 README.md）：

import os os.environ["UPSTAGE_API_KEY"] = "YOUR_API_KEY" from llama_index.readers.upstage import UpstageLayoutAnalysisReader file_path = "/PATH/TO/YOUR/FILE.pdf" reader = UpstageLayoutAnalysisReader( use_ocr=False, exclude=["header", "footer"] ) # 按元素拆分，且段落元素输出纯文本、其余输出 html docs = reader.load_data( file_path=file_path, split="element", output_type={"paragraph": "text"} ) for doc in docs[:3]: print(doc)

四、与 LlamaIndex 核心的对接方式

两个 Reader 都继承自llama_index.core.readers.base.BaseReader，lazy_load_data产出标准的llama_index.core.schema.Document。测试用例 test_readers_upstage.py 通过检查类的 MRO（方法解析顺序）断言两个类都满足BaseReader继承关系，从侧面验证了接口契约的一致性。

由于返回的是标准Document，你可以把解析结果直接交给后续管线，例如：

• 按split="element"产出细粒度节点，配合 LlamaIndex 的VectorStoreIndex构建高精度检索；
• 按split="page"保持页码上下文，extra_info["page"]可直接用于引用溯源（citation）；
• 将UpstageDocumentParseReader的output_format="markdown"输出接入知识库，保留标题层级与表格结构；
• 通过base64_encoding=["table", "figure"]同时拿到版面裁剪图像，支持多模态检索场景。

五、注意事项与最佳实践

1. API Key 安全：优先使用环境变量UPSTAGE_API_KEY，避免把密钥硬编码进脚本；模块内的validate_api_key（base.py）会在 Key 为空时立即抛出ValueError。
2. 文件校验：validate_file_path（base.py）会在文件不存在时抛出FileNotFoundError，建议在调用前自行确认路径可达。
3. 大文件处理：无论新旧 Reader，PDF 都会按 10 页一块切片请求，避免单次请求过大；客户端侧建议使用lazy_load_data配合生成器逐块消费，降低内存峰值。
4. OCR 取舍：数字原生 PDF 直接用ocr="auto"（或旧版use_ocr=False）即可获得高质量文本；扫描件、图片则需ocr="force"（或use_ocr=True），但要接受更长的推理耗时。
5. 版本选择：新项目优先使用UpstageDocumentParseReader（支持 Markdown、坐标、base64 裁剪等更丰富能力），仅在维护存量代码时保留UpstageLayoutAnalysisReader。关于版本与依赖的完整声明可查看 pyproject.toml。

综上，llama-index-readers-upstage把 Upstage 的文档 AI 能力完整嵌入 LlamaIndex 数据加载层：从版面检测、OCR 到多粒度拆分、多格式输出，再到标准Document元数据保留，为文档密集型 RAG 应用提供了开箱即用的高质量解析方案。

【免费下载链接】llama_indexLlamaIndex is the leading document agent and OCR platform项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index