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 中声明了两个核心依赖pymupdf1.23.21,2用于在客户端本地读取 PDF 并完成分页切片llama-index-core0.13.0,0.15提供BaseReader基类与Document数据模型。包内暴露两个 Reader 类见init.pyUpstageDocumentParseReader基于 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_KEYAPI 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 构造参数参数类型默认值说明api_keystrNoneUpstage API 访问令牌为空时回退读取环境变量UPSTAGE_API_KEYbase_urlstrhttps://api.upstage.ai/v1/document-ai/document-parse自定义 API 端点地址modelstrdocument-parse使用的解析模型名称splitnone \| page \| elementnone输出拆分粒度ocrauto \| forceautoOCR 策略详见下文output_formattext \| html \| markdownhtml版面元素内容的输出格式coordinatesboolTrue是否在结果中返回每个版面元素的边界框坐标base64_encodingList[Category][]指定哪些版面类别额外以 base64 字符串形式返回便于裁剪原图ocr参数的两种取值语义auto表示仅对图片输入执行 OCR 推理对于 PDF 或非图片文档引擎直接从文档中提取文本与坐标而不做图像转换force表示无论输入类型如何都先把文件转换为图像再执行 OCR 推理后再做版面检测。因此若输入不是 PDF 而ocrauto会触发错误。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.mdimport 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_pathfile_path) for doc in docs[:3]: print(doc)lazy_load_data是生成器实现核心逻辑位于 document_parse.py其行为受构造时split参数控制splitnone整份文档合并为单个Documentextra_info中携带total_pages总页数、output_format与splitsplitelement每个版面元素段落、表格、图等生成一个独立Documentextra_info包含page页码、id元素 ID、category元素类别以及可选的coordinates与base64_encoding见_element_documentdocument_parse.pysplitpage同一页内的元素按页码聚合为一个Documentextra_info中的coordinates为该页所有元素坐标的列表见_page_documentdocument_parse.py。当输入是 PDF 时解析并非一次完成Reader 使用 PyMuPDFfitz打开文件按DEFAULT_NUMBER_OF_PAGE 10页为一块进行切片逐块向 API 发起请求见_split_and_requestdocument_parse.py这样能规避大文件的请求体大小限制并降低单次失败的影响面。当输入不是 PDF如图片时则直接把文件字节流放入multipart表单发送。请求的组装细节见_get_responsedocument_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 构造参数参数类型默认值说明api_keystrNoneAPI 访问令牌为空时回退读取UPSTAGE_API_KEY环境变量use_ocrboolFalse是否对文档启用 OCR 提取文本False时直接使用数字原生 PDF 内嵌文本excludelist[header, footer]从输出中排除的版面元素类别列表exclude支持的类别包括paragraph、caption、table、figure、equation、footer、header。默认排除页眉页脚这一设计对 RAG 场景很友好——避免把重复的导航文本切进检索单元。use_ocrTrue时会调用 OCR 模型可处理图片格式文档但推理耗时相应增加。3.2 加载数据与输出控制与新版不同旧版把output_type与split作为load_data/lazy_load_data的调用参数传入见 base.pyfile_path必填单个或列表形式的str | pathlib.Path路径output_type可选默认html既可以是text/html字符串也可以是形如{paragraph: text, table: html}的字典实现按类别分别指定输出格式——未在字典中指定的类别且未被exclude排除的回退使用html。这一能力由parse_output实现base.pysplit可选默认nonenone不拆分page按页聚合element按版面元素拆分。_element_document会把元素渲染为Document其extra_info含page、id、type、split以及序列化后的bounding_boxbase.py_page_document则把同页元素文本用空格拼接成一个Documentbase.py。PDF 输入同样按每 10 页一块切片请求DEFAULT_NUMBER_OF_PAGE并在_get_response中按exclude过滤元素后再返回base.py。示例用法摘自包内 README.mdimport 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_ocrFalse, exclude[header, footer] ) # 按元素拆分且段落元素输出纯文本、其余输出 html docs reader.load_data( file_pathfile_path, splitelement, output_type{paragraph: text} ) for doc in docs[:3]: print(doc)四、与 LlamaIndex 核心的对接方式两个 Reader 都继承自llama_index.core.readers.base.BaseReaderlazy_load_data产出标准的llama_index.core.schema.Document。测试用例 test_readers_upstage.py 通过检查类的 MRO方法解析顺序断言两个类都满足BaseReader继承关系从侧面验证了接口契约的一致性。由于返回的是标准Document你可以把解析结果直接交给后续管线例如按splitelement产出细粒度节点配合 LlamaIndex 的VectorStoreIndex构建高精度检索按splitpage保持页码上下文extra_info[page]可直接用于引用溯源citation将UpstageDocumentParseReader的output_formatmarkdown输出接入知识库保留标题层级与表格结构通过base64_encoding[table, figure]同时拿到版面裁剪图像支持多模态检索场景。五、注意事项与最佳实践API Key 安全优先使用环境变量UPSTAGE_API_KEY避免把密钥硬编码进脚本模块内的validate_api_keybase.py会在 Key 为空时立即抛出ValueError。文件校验validate_file_pathbase.py会在文件不存在时抛出FileNotFoundError建议在调用前自行确认路径可达。大文件处理无论新旧 ReaderPDF 都会按 10 页一块切片请求避免单次请求过大客户端侧建议使用lazy_load_data配合生成器逐块消费降低内存峰值。OCR 取舍数字原生 PDF 直接用ocrauto或旧版use_ocrFalse即可获得高质量文本扫描件、图片则需ocrforce或use_ocrTrue但要接受更长的推理耗时。版本选择新项目优先使用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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考