langchain-paddleocr 实战指南用 PaddleOCRVLLoader 将 PDF 与图像接入 LangChain【免费下载链接】PaddleOCRTurn any PDF or image document into structured data for your AI. A powerful, lightweight OCR toolkit that bridges the gap between images/PDFs and LLMs. Supports 100 languages.项目地址: https://gitcode.com/GitHub_Trending/pa/PaddleOCR本篇技术指南以langchain-paddleocr集成包为核心讲解如何在 LangChain 生态中通过PaddleOCRVLLoader加载器调用百度 PaddleOCR-VL 系列视觉语言模型将本地或远程的 PDF、图像文档解析为结构化文本与版面信息并转换为标准的 LangChainDocument对象。读完本文你将掌握该加载器的完整参数体系、底层 SDK 调用链、认证方式与常见问题排查方法可直接将其接入 RAG 检索与 LLM 应用流水线。一、包定位与适用场景langchain-paddleocr是一个将 PaddleOCR 能力桥接到 LangChain 生态的 Python 集成包源码位于 langchain-paddleocr 目录。它解决的痛点非常明确让 LLM 应用直接读懂文档类非结构化数据。从PDF 与图像文件如 JPG、PNG 扫描件中提取文本内容同时输出版面布局信息标题、段落、表格、图表、印章等区块并组织为 Markdown支持本地文件与远程 URL两种输入来源结果以标准langchain_core.documents.Document形式产出天然适配 LangChain 的链式处理、向量化与检索流程。从pyproject.toml的元数据langchain-paddleocr/pyproject.toml可以看到该包当前版本为 0.2.2遵循 Apache License 2.0要求 Python ≥ 3.10核心依赖为paddleocr3.7.0、langchain-core1.2.5,2.0.0与pydantic2.0.0,3.0.0——也就是说它并非在本机跑推理而是通过 PaddleOCR 官方 SDK 调用云端文档解析 API。二、快速安装pip install langchain-paddleocr安装会同时拉取上述三个核心依赖。如果你想在项目中使用uv管理依赖仓库根目录还提供了 uv.lock 锁定文件开发与测试则可通过 Makefile 与pyproject.toml中声明的lint、typing、test等依赖组完成。三、快速上手五分钟跑通第一个文档解析langchain-paddleocr对外只暴露一个核心类PaddleOCRVLLoader见init.py 的导出列表这是 README 给出的最简用法from langchain_paddleocr import PaddleOCRVLLoader from pydantic import SecretStr loader PaddleOCRVLLoader( file_pathpath/to/document.pdf, base_urlyour-api-endpoint, modelPaddleOCR-VL-1.5, access_tokenSecretStr(your-access-token) # 如果使用环境变量 PADDLEOCR_ACCESS_TOKEN则此项为可选 ) docs loader.load() for doc in docs[:2]: print(fContent: {doc.page_content[:200]}...) print(fSource: {doc.metadata[source]}) print(---)这段代码做了三件事构造PaddleOCRVLLoader指定待解析文件、API 端点、模型名与访问令牌调用load()或lazy_load()执行解析遍历返回的Document列表读取page_content解析出的 Markdown 文本与metadata含source来源字段。下面逐层拆解其中每个环节的原理与可调参数。四、核心 API 详解PaddleOCRVLLoader 参数体系PaddleOCRVLLoader继承自langchain_core.document_loaders.BaseLoader源码见 document_loaders/paddleocr_vl.py构造函数的完整签名非常丰富参数可归为五类。4.1 基础参数参数类型默认值说明file_pathstr或Iterable[str]必填单个 PDF/图像路径或 URL也可传入可迭代对象批量处理多个文档access_tokenSecretStr \| NoneNoneAPI 访问令牌不传则读取环境变量PADDLEOCR_ACCESS_TOKENbase_urlstr \| None官方服务地址API 服务基础地址默认https://paddleocr.aistudio-app.commodelstr \| Model \| NoneNone由服务端决定PaddleOCR-VL 模型名或paddleocr.Model枚举值timeoutint300轮询等待超时秒关于base_url的默认值单元测试 test_paddleocr_vl_loader.py 中test_default_base_url明确断言未显式传入时loader._base_url https://paddleocr.aistudio-app.comtest_custom_base_url则验证自定义地址会被原样保留。4.2 文档预处理开关参数类型说明use_doc_orientation_classifybool是否启用文档方向分类自动判断 0/90/180/270 度use_doc_unwarpingbool是否启用文档去畸变矫正拍摄弯曲/透视变形use_layout_detectionbool是否启用版面分析use_chart_recognitionbool是否启用图表识别use_seal_recognitionbool是否启用印章识别use_ocr_for_image_blockbool是否对版面中的图像区块执行 OCR其中use_doc_orientation_classify与use_doc_unwarping的默认值为False且这两个默认开关会被显式写入options见源码第 154-190 行的构造逻辑与测试test_options_include_default_flags其余开关默认为None不传。4.3 版面检测参数参数类型说明layout_thresholdfloat \| dict[int, float]版面检测置信度阈值可按版面类别 ID 分别设置layout_nmsbool是否对版面检测框做非极大值抑制NMSlayout_unclip_ratiotuple[float,float] \| dict[int, tuple] \| float检测框扩边比例支持按类别设置layout_merge_bboxes_modestr \| dict[str, float]版面框合并模式layout_shape_modestr版面形状模式4.4 VLM 生成参数采样控制参数类型说明prompt_labelstr传给 VLM 的提示标签format_block_contentbool是否在 JSON 结果中保存格式化后的 Markdown 区块内容repetition_penaltyfloat重复惩罚系数抑制生成重复文本temperaturefloat采样温度控制随机性top_pfloat核采样阈值min_pixels/max_pixelsint预处理阶段允许的最小/最大像素数控制送入 VLM 的图像分辨率范围max_new_tokensintVLM 单次生成的最大 token 数vlm_extra_argsdict透传给服务端的额外 VLM 参数4.5 Markdown 输出与导出参数参数类型说明merge_layout_blocksbool是否跨栏合并版面块markdown_ignore_labelslist[str]在 Markdown 中忽略的版面标签如[image]prettify_markdownbool是否美化 Markdown 输出show_formula_numberbool是否在 Markdown 中显示公式编号restructure_pagesbool是否跨页重组解析结果merge_tablesbool是否跨页合并表格relevel_titlesbool是否重新调整标题层级return_markdown_imagesbool是否返回 Markdown 引用的图像output_formatslist[str]附加导出格式如docxvisualizebool是否包含可视化结果extra_optionsdict其他服务端选项原样透传4.6 参数如何传递到服务端源码第 154-192 行揭示了一个重要机制所有值为None的参数会被过滤掉只有非None的参数才会被组装成PaddleOCRVLOptions数据类若全部为None则_options为None不附加任何选项。随后PaddleOCRVLOptions.to_payload()实现在 paddleocr/_api_client/models.py会把字段名转换为驼峰命名并剔除None值其中extra_options中的键值对会被平铺合并进最终请求体——参数映射测试 test_paddleocr_vl_param_mapping.py 验证了extra_options{futureOption: enabled}最终会出现在to_payload()的顶层。五、支持哪些模型加载器的model参数可接受字符串或paddleocr.Model枚举。从 models.py 的枚举定义可见PaddleOCR 官方 API 的 VL 系列模型包括枚举值字符串名Model.PADDLE_OCR_VLPaddleOCR-VLModel.PADDLE_OCR_VL_15PaddleOCR-VL-1.5Model.PADDLE_OCR_VL_16PaddleOCR-VL-1.6同时该文件中还定义了_VL_MODELS集合用于判定模型是否为 VL 系列。在PaddleOCRVLLoader内部字符串会被_resolve_vl_model转换为枚举源码第 35-45 行若字符串非法则抛出ValueError(Unsupported model: ...)如果直接传入Model枚举则原样保留。测试test_custom_model_string印证了modelPaddleOCR-VL-1.5会被解析为Model.PADDLE_OCR_VL_15。需要说明的是模型默认值为None此时加载器不会在请求中携带model字段见测试test_parse_document_omits_model_by_default由服务端使用默认模型处理而底层 SDK 的PaddleOCRClient.parse_document若单独调用其默认模型是Model.PADDLE_OCR_VL_16见 client.py。六、返回结果Document 与原始响应lazy_load()为每个文件产出一个langchain_core.documents.Document源码第 244-264 行page_content所有页面的markdown_text按\n\f换页符拼接而成的纯文本即页面之间以换页符分隔metadata[source]文件路径或 URL 字符串metadata[model]若显式指定了模型则记录模型的字符串值metadata[paddleocr_vl_raw_response]完整的原始解析结果字典包含job_id任务 ID、data_info以及逐页的markdown_text、markdown_imagesMarkdown 引用图像、output_images输出图像、pruned_result裁剪后的结构化结果、input_image_url、exports如 docx 导出、markdown与raw字段——这对于需要深度使用版面结构化信息的 RAG 或文档问答场景非常有价值。若某文件未能提取出任何文本加载器会打印logger.warning提示但仍返回一个page_content为空的 Document不会中断整个批量流程源码第 249-255 行。七、底层原理一次文档解析的完整调用链PaddleOCRVLLoader只是门面真正的解析由 PaddleOCR 官方 SDK 完成。梳理 paddleocr_vl.py 的_process_file与 client.py 的实现调用链如下加载器判断输入是 URL 还是本地路径_is_url检查是否以http://或https://开头以上下文管理器方式创建PaddleOCRClient(token..., base_url..., client_platformlangchain, poll_timeout...)调用client.parse_document()——对 URL 传file_url参数对本地文件则先检查Path.exists()不存在时抛出ValueError(File not found: ...)测试test_lazy_load_raises_for_missing_file验证了该行为再传file_pathparse_document内部执行提交异步任务 → 轮询状态直至完成 → 拉取结果三步流程client.py 的类注释明确说明这是对官方异步任务 API 的同步封装返回DocParsingResult加载器从中提取各页markdown_text组装page_content并把job_id、data_info、逐页原始数据放入metadata。整个解析是异步任务模型提交后由Poller以poll_timeout即加载器的timeout参数默认 300 秒为上限轮询适合处理多页 PDF 等耗时较长的任务。SDK 还提供了AsyncPaddleOCRClient见 async_client.py供异步场景使用。八、认证与端点配置PaddleOCRClient的认证优先级client.py 第 48-70 行Token优先使用构造时传入的 token否则读取环境变量PADDLEOCR_ACCESS_TOKEN两者皆无则抛出AuthError(Token is required. ...)。在PaddleOCRVLLoader层面access_token以pydantic.SecretStr传入不传则同样回退到环境变量test_access_token_from_env验证了该回退逻辑。Base URL优先级为base_url参数 环境变量PADDLEOCR_BASE_URL SDK 内置默认地址。PaddleOCRVLLoader未传时使用其自身的默认地址https://paddleocr.aistudio-app.com。因此最省事的生产配置方式是导出环境变量export PADDLEOCR_ACCESS_TOKENyour-access-token然后构造加载器时完全省略access_token参数。若你部署了自建或代理的 PaddleOCR 服务再通过base_url覆盖默认端点即可。九、批量处理与 URL 输入file_path参数支持传入可迭代对象一次处理多个文档源码第 137-141 行会把单个字符串包装成列表Iterable 则原样保留lazy_load()会逐个文件产出 Documentfrom langchain_paddleocr import PaddleOCRVLLoader loader PaddleOCRVLLoader( file_path[ /data/docs/report.pdf, /data/docs/invoice.jpg, https://example.com/contract.pdf, # 远程 URL 同样支持 ], modelPaddleOCR-VL-1.5, ) for doc in loader.lazy_load(): # 惰性加载逐文件流式产出 print(doc.metadata[source], len(doc.page_content))使用lazy_load()而非load()的好处是多个文件逐个解析、逐个产出避免一次性把全部结果载入内存适合大批量文档处理。十、参数合法性校验服务端前的一道保险在请求真正发出前PaddleOCRVLOptions.to_payload()会调用_validate_vl_optionsmodels.py 第 184-202 行做参数校验违反规则会抛出InvalidRequestErrortop_p必须满足0 top_p 1temperature必须 0repetition_penalty必须 0min_pixels、max_pixels必须 0min_pixels不能大于max_pixels。这些约束对 VLM 采样与图像预处理直接生效构造加载器时若设置超出范围的数值会在请求阶段被 SDK 拦截而非等到服务端报错方便快速定位问题。十一、测试与质量保障仓库为langchain-paddleocr提供了完整的单元测试与集成测试骨架tests/unit_tests/document_loaders/test_paddleocr_vl_loader.py覆盖默认/自定义base_url、环境变量 token 回退、options 构建、缺失本地文件报错、默认模型省略、模型字符串映射、URL 输入等行为tests/unit_tests/document_loaders/test_paddleocr_vl_param_mapping.py验证加载器参数到PaddleOCRVLOptions的完整映射与extra_options的 payload 合并tests/integration_tests/document_loaders/真实调用服务的集成测试骨架配套测试数据位于 tests/data/含sample_pdf.pdf与sample_img.jpg工程上使用 ruffALL规则集 mypy strict 模式保证代码质量py.typed标记使包对类型检查器完全可见。十二、典型应用接入 RAG 流水线PaddleOCRVLLoader产出的Document可直接进入 LangChain 的标准检索链路——向量化后写入向量库供 RAG 检索metadata[paddleocr_vl_raw_response]中的版面结构标题、表格、公式、印章等标注还可用于构造更精细的段落切分或结构化索引。一个典型的组合用法from langchain_paddleocr import PaddleOCRVLLoader from langchain_text_splitters import RecursiveCharacterTextSplitter from langchain_core.vectorstores import InMemoryVectorStore from langchain_community.embeddings import ... # 按需选择 embedding 模型 loader PaddleOCRVLLoader( file_pathpath/to/document.pdf, modelPaddleOCR-VL-1.5, ) documents loader.load() # 基于 Markdown 标题结构切分保留版面语义 splitter RecursiveCharacterTextSplitter( chunk_size1000, chunk_overlap100, separators[\n\n, \n, , ] ) chunks splitter.split_documents(documents) # 向量化入库示意 vector_store InMemoryVectorStore.from_documents(chunks, embedding...) retriever vector_store.as_retriever(search_kwargs{k: 4})这样一份 PDF 或扫描件就变成了可被 LLM 精确检索的文本块打通了文档 → 结构化数据 → AI 应用的链路。十三、常见问题排查现象原因与解决AuthError: Token is required未配置访问令牌。设置环境变量PADDLEOCR_ACCESS_TOKEN或在构造时传入access_tokenSecretStr(...)ValueError: Unsupported model: xxxmodel参数既不是合法模型名也不是Model枚举值。请使用PaddleOCR-VL、PaddleOCR-VL-1.5、PaddleOCR-VL-1.6ValueError: File not found: ...本地文件路径不存在。确认路径拼写或改用远程 URLInvalidRequestError: top_p must be ...采样参数超出合法范围参见上文第十节的校验规则返回的page_content为空文档无可提取文本如纯图像页加载器会记录 warning 并返回空 Document可结合metadata[paddleocr_vl_raw_response]的原始数据定位原因长时间未返回多页 PDF 解析耗时较长可调大timeout参数默认 300 秒结语langchain-paddleocr通过一个继承BaseLoader的PaddleOCRVLLoader把 PaddleOCR-VL 系列模型的文档解析能力无缝接入 LangChain本地文件与远程 URL 皆可处理版面分析、表格/公式/印章识别、Markdown 化输出与原始结构化结果一并交付参数体系覆盖预处理、版面检测、VLM 采样与导出全链路。结合本仓库的源码与测试你可以精确掌握每个参数的去向与校验边界快速在 RAG、文档问答等 AI 应用中落地可靠的文档解析能力。完整的中英文使用说明可继续查阅 langchain-paddleocr/README_cn.md 与 langchain-paddleocr/README.md。【免费下载链接】PaddleOCRTurn any PDF or image document into structured data for your AI. A powerful, lightweight OCR toolkit that bridges the gap between images/PDFs and LLMs. Supports 100 languages.项目地址: https://gitcode.com/GitHub_Trending/pa/PaddleOCR创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 langchain-paddleocr 实战指南：用 PaddleOCRVLLoader 将 PDF 与图像接入 LangChain
langchain-paddleocr 实战指南用 PaddleOCRVLLoader 将 PDF 与图像接入 LangChain【免费下载链接】PaddleOCRTurn any PDF or image document into structured data for your AI. A powerful, lightweight OCR toolkit that bridges the gap between images/PDFs and LLMs. Supports 100 languages.项目地址: https://gitcode.com/GitHub_Trending/pa/PaddleOCR本篇技术指南以langchain-paddleocr集成包为核心讲解如何在 LangChain 生态中通过PaddleOCRVLLoader加载器调用百度 PaddleOCR-VL 系列视觉语言模型将本地或远程的 PDF、图像文档解析为结构化文本与版面信息并转换为标准的 LangChainDocument对象。读完本文你将掌握该加载器的完整参数体系、底层 SDK 调用链、认证方式与常见问题排查方法可直接将其接入 RAG 检索与 LLM 应用流水线。一、包定位与适用场景langchain-paddleocr是一个将 PaddleOCR 能力桥接到 LangChain 生态的 Python 集成包源码位于 langchain-paddleocr 目录。它解决的痛点非常明确让 LLM 应用直接读懂文档类非结构化数据。从PDF 与图像文件如 JPG、PNG 扫描件中提取文本内容同时输出版面布局信息标题、段落、表格、图表、印章等区块并组织为 Markdown支持本地文件与远程 URL两种输入来源结果以标准langchain_core.documents.Document形式产出天然适配 LangChain 的链式处理、向量化与检索流程。从pyproject.toml的元数据langchain-paddleocr/pyproject.toml可以看到该包当前版本为 0.2.2遵循 Apache License 2.0要求 Python ≥ 3.10核心依赖为paddleocr3.7.0、langchain-core1.2.5,2.0.0与pydantic2.0.0,3.0.0——也就是说它并非在本机跑推理而是通过 PaddleOCR 官方 SDK 调用云端文档解析 API。二、快速安装pip install langchain-paddleocr安装会同时拉取上述三个核心依赖。如果你想在项目中使用uv管理依赖仓库根目录还提供了 uv.lock 锁定文件开发与测试则可通过 Makefile 与pyproject.toml中声明的lint、typing、test等依赖组完成。三、快速上手五分钟跑通第一个文档解析langchain-paddleocr对外只暴露一个核心类PaddleOCRVLLoader见init.py 的导出列表这是 README 给出的最简用法from langchain_paddleocr import PaddleOCRVLLoader from pydantic import SecretStr loader PaddleOCRVLLoader( file_pathpath/to/document.pdf, base_urlyour-api-endpoint, modelPaddleOCR-VL-1.5, access_tokenSecretStr(your-access-token) # 如果使用环境变量 PADDLEOCR_ACCESS_TOKEN则此项为可选 ) docs loader.load() for doc in docs[:2]: print(fContent: {doc.page_content[:200]}...) print(fSource: {doc.metadata[source]}) print(---)这段代码做了三件事构造PaddleOCRVLLoader指定待解析文件、API 端点、模型名与访问令牌调用load()或lazy_load()执行解析遍历返回的Document列表读取page_content解析出的 Markdown 文本与metadata含source来源字段。下面逐层拆解其中每个环节的原理与可调参数。四、核心 API 详解PaddleOCRVLLoader 参数体系PaddleOCRVLLoader继承自langchain_core.document_loaders.BaseLoader源码见 document_loaders/paddleocr_vl.py构造函数的完整签名非常丰富参数可归为五类。4.1 基础参数参数类型默认值说明file_pathstr或Iterable[str]必填单个 PDF/图像路径或 URL也可传入可迭代对象批量处理多个文档access_tokenSecretStr \| NoneNoneAPI 访问令牌不传则读取环境变量PADDLEOCR_ACCESS_TOKENbase_urlstr \| None官方服务地址API 服务基础地址默认https://paddleocr.aistudio-app.commodelstr \| Model \| NoneNone由服务端决定PaddleOCR-VL 模型名或paddleocr.Model枚举值timeoutint300轮询等待超时秒关于base_url的默认值单元测试 test_paddleocr_vl_loader.py 中test_default_base_url明确断言未显式传入时loader._base_url https://paddleocr.aistudio-app.comtest_custom_base_url则验证自定义地址会被原样保留。4.2 文档预处理开关参数类型说明use_doc_orientation_classifybool是否启用文档方向分类自动判断 0/90/180/270 度use_doc_unwarpingbool是否启用文档去畸变矫正拍摄弯曲/透视变形use_layout_detectionbool是否启用版面分析use_chart_recognitionbool是否启用图表识别use_seal_recognitionbool是否启用印章识别use_ocr_for_image_blockbool是否对版面中的图像区块执行 OCR其中use_doc_orientation_classify与use_doc_unwarping的默认值为False且这两个默认开关会被显式写入options见源码第 154-190 行的构造逻辑与测试test_options_include_default_flags其余开关默认为None不传。4.3 版面检测参数参数类型说明layout_thresholdfloat \| dict[int, float]版面检测置信度阈值可按版面类别 ID 分别设置layout_nmsbool是否对版面检测框做非极大值抑制NMSlayout_unclip_ratiotuple[float,float] \| dict[int, tuple] \| float检测框扩边比例支持按类别设置layout_merge_bboxes_modestr \| dict[str, float]版面框合并模式layout_shape_modestr版面形状模式4.4 VLM 生成参数采样控制参数类型说明prompt_labelstr传给 VLM 的提示标签format_block_contentbool是否在 JSON 结果中保存格式化后的 Markdown 区块内容repetition_penaltyfloat重复惩罚系数抑制生成重复文本temperaturefloat采样温度控制随机性top_pfloat核采样阈值min_pixels/max_pixelsint预处理阶段允许的最小/最大像素数控制送入 VLM 的图像分辨率范围max_new_tokensintVLM 单次生成的最大 token 数vlm_extra_argsdict透传给服务端的额外 VLM 参数4.5 Markdown 输出与导出参数参数类型说明merge_layout_blocksbool是否跨栏合并版面块markdown_ignore_labelslist[str]在 Markdown 中忽略的版面标签如[image]prettify_markdownbool是否美化 Markdown 输出show_formula_numberbool是否在 Markdown 中显示公式编号restructure_pagesbool是否跨页重组解析结果merge_tablesbool是否跨页合并表格relevel_titlesbool是否重新调整标题层级return_markdown_imagesbool是否返回 Markdown 引用的图像output_formatslist[str]附加导出格式如docxvisualizebool是否包含可视化结果extra_optionsdict其他服务端选项原样透传4.6 参数如何传递到服务端源码第 154-192 行揭示了一个重要机制所有值为None的参数会被过滤掉只有非None的参数才会被组装成PaddleOCRVLOptions数据类若全部为None则_options为None不附加任何选项。随后PaddleOCRVLOptions.to_payload()实现在 paddleocr/_api_client/models.py会把字段名转换为驼峰命名并剔除None值其中extra_options中的键值对会被平铺合并进最终请求体——参数映射测试 test_paddleocr_vl_param_mapping.py 验证了extra_options{futureOption: enabled}最终会出现在to_payload()的顶层。五、支持哪些模型加载器的model参数可接受字符串或paddleocr.Model枚举。从 models.py 的枚举定义可见PaddleOCR 官方 API 的 VL 系列模型包括枚举值字符串名Model.PADDLE_OCR_VLPaddleOCR-VLModel.PADDLE_OCR_VL_15PaddleOCR-VL-1.5Model.PADDLE_OCR_VL_16PaddleOCR-VL-1.6同时该文件中还定义了_VL_MODELS集合用于判定模型是否为 VL 系列。在PaddleOCRVLLoader内部字符串会被_resolve_vl_model转换为枚举源码第 35-45 行若字符串非法则抛出ValueError(Unsupported model: ...)如果直接传入Model枚举则原样保留。测试test_custom_model_string印证了modelPaddleOCR-VL-1.5会被解析为Model.PADDLE_OCR_VL_15。需要说明的是模型默认值为None此时加载器不会在请求中携带model字段见测试test_parse_document_omits_model_by_default由服务端使用默认模型处理而底层 SDK 的PaddleOCRClient.parse_document若单独调用其默认模型是Model.PADDLE_OCR_VL_16见 client.py。六、返回结果Document 与原始响应lazy_load()为每个文件产出一个langchain_core.documents.Document源码第 244-264 行page_content所有页面的markdown_text按\n\f换页符拼接而成的纯文本即页面之间以换页符分隔metadata[source]文件路径或 URL 字符串metadata[model]若显式指定了模型则记录模型的字符串值metadata[paddleocr_vl_raw_response]完整的原始解析结果字典包含job_id任务 ID、data_info以及逐页的markdown_text、markdown_imagesMarkdown 引用图像、output_images输出图像、pruned_result裁剪后的结构化结果、input_image_url、exports如 docx 导出、markdown与raw字段——这对于需要深度使用版面结构化信息的 RAG 或文档问答场景非常有价值。若某文件未能提取出任何文本加载器会打印logger.warning提示但仍返回一个page_content为空的 Document不会中断整个批量流程源码第 249-255 行。七、底层原理一次文档解析的完整调用链PaddleOCRVLLoader只是门面真正的解析由 PaddleOCR 官方 SDK 完成。梳理 paddleocr_vl.py 的_process_file与 client.py 的实现调用链如下加载器判断输入是 URL 还是本地路径_is_url检查是否以http://或https://开头以上下文管理器方式创建PaddleOCRClient(token..., base_url..., client_platformlangchain, poll_timeout...)调用client.parse_document()——对 URL 传file_url参数对本地文件则先检查Path.exists()不存在时抛出ValueError(File not found: ...)测试test_lazy_load_raises_for_missing_file验证了该行为再传file_pathparse_document内部执行提交异步任务 → 轮询状态直至完成 → 拉取结果三步流程client.py 的类注释明确说明这是对官方异步任务 API 的同步封装返回DocParsingResult加载器从中提取各页markdown_text组装page_content并把job_id、data_info、逐页原始数据放入metadata。整个解析是异步任务模型提交后由Poller以poll_timeout即加载器的timeout参数默认 300 秒为上限轮询适合处理多页 PDF 等耗时较长的任务。SDK 还提供了AsyncPaddleOCRClient见 async_client.py供异步场景使用。八、认证与端点配置PaddleOCRClient的认证优先级client.py 第 48-70 行Token优先使用构造时传入的 token否则读取环境变量PADDLEOCR_ACCESS_TOKEN两者皆无则抛出AuthError(Token is required. ...)。在PaddleOCRVLLoader层面access_token以pydantic.SecretStr传入不传则同样回退到环境变量test_access_token_from_env验证了该回退逻辑。Base URL优先级为base_url参数 环境变量PADDLEOCR_BASE_URL SDK 内置默认地址。PaddleOCRVLLoader未传时使用其自身的默认地址https://paddleocr.aistudio-app.com。因此最省事的生产配置方式是导出环境变量export PADDLEOCR_ACCESS_TOKENyour-access-token然后构造加载器时完全省略access_token参数。若你部署了自建或代理的 PaddleOCR 服务再通过base_url覆盖默认端点即可。九、批量处理与 URL 输入file_path参数支持传入可迭代对象一次处理多个文档源码第 137-141 行会把单个字符串包装成列表Iterable 则原样保留lazy_load()会逐个文件产出 Documentfrom langchain_paddleocr import PaddleOCRVLLoader loader PaddleOCRVLLoader( file_path[ /data/docs/report.pdf, /data/docs/invoice.jpg, https://example.com/contract.pdf, # 远程 URL 同样支持 ], modelPaddleOCR-VL-1.5, ) for doc in loader.lazy_load(): # 惰性加载逐文件流式产出 print(doc.metadata[source], len(doc.page_content))使用lazy_load()而非load()的好处是多个文件逐个解析、逐个产出避免一次性把全部结果载入内存适合大批量文档处理。十、参数合法性校验服务端前的一道保险在请求真正发出前PaddleOCRVLOptions.to_payload()会调用_validate_vl_optionsmodels.py 第 184-202 行做参数校验违反规则会抛出InvalidRequestErrortop_p必须满足0 top_p 1temperature必须 0repetition_penalty必须 0min_pixels、max_pixels必须 0min_pixels不能大于max_pixels。这些约束对 VLM 采样与图像预处理直接生效构造加载器时若设置超出范围的数值会在请求阶段被 SDK 拦截而非等到服务端报错方便快速定位问题。十一、测试与质量保障仓库为langchain-paddleocr提供了完整的单元测试与集成测试骨架tests/unit_tests/document_loaders/test_paddleocr_vl_loader.py覆盖默认/自定义base_url、环境变量 token 回退、options 构建、缺失本地文件报错、默认模型省略、模型字符串映射、URL 输入等行为tests/unit_tests/document_loaders/test_paddleocr_vl_param_mapping.py验证加载器参数到PaddleOCRVLOptions的完整映射与extra_options的 payload 合并tests/integration_tests/document_loaders/真实调用服务的集成测试骨架配套测试数据位于 tests/data/含sample_pdf.pdf与sample_img.jpg工程上使用 ruffALL规则集 mypy strict 模式保证代码质量py.typed标记使包对类型检查器完全可见。十二、典型应用接入 RAG 流水线PaddleOCRVLLoader产出的Document可直接进入 LangChain 的标准检索链路——向量化后写入向量库供 RAG 检索metadata[paddleocr_vl_raw_response]中的版面结构标题、表格、公式、印章等标注还可用于构造更精细的段落切分或结构化索引。一个典型的组合用法from langchain_paddleocr import PaddleOCRVLLoader from langchain_text_splitters import RecursiveCharacterTextSplitter from langchain_core.vectorstores import InMemoryVectorStore from langchain_community.embeddings import ... # 按需选择 embedding 模型 loader PaddleOCRVLLoader( file_pathpath/to/document.pdf, modelPaddleOCR-VL-1.5, ) documents loader.load() # 基于 Markdown 标题结构切分保留版面语义 splitter RecursiveCharacterTextSplitter( chunk_size1000, chunk_overlap100, separators[\n\n, \n, , ] ) chunks splitter.split_documents(documents) # 向量化入库示意 vector_store InMemoryVectorStore.from_documents(chunks, embedding...) retriever vector_store.as_retriever(search_kwargs{k: 4})这样一份 PDF 或扫描件就变成了可被 LLM 精确检索的文本块打通了文档 → 结构化数据 → AI 应用的链路。十三、常见问题排查现象原因与解决AuthError: Token is required未配置访问令牌。设置环境变量PADDLEOCR_ACCESS_TOKEN或在构造时传入access_tokenSecretStr(...)ValueError: Unsupported model: xxxmodel参数既不是合法模型名也不是Model枚举值。请使用PaddleOCR-VL、PaddleOCR-VL-1.5、PaddleOCR-VL-1.6ValueError: File not found: ...本地文件路径不存在。确认路径拼写或改用远程 URLInvalidRequestError: top_p must be ...采样参数超出合法范围参见上文第十节的校验规则返回的page_content为空文档无可提取文本如纯图像页加载器会记录 warning 并返回空 Document可结合metadata[paddleocr_vl_raw_response]的原始数据定位原因长时间未返回多页 PDF 解析耗时较长可调大timeout参数默认 300 秒结语langchain-paddleocr通过一个继承BaseLoader的PaddleOCRVLLoader把 PaddleOCR-VL 系列模型的文档解析能力无缝接入 LangChain本地文件与远程 URL 皆可处理版面分析、表格/公式/印章识别、Markdown 化输出与原始结构化结果一并交付参数体系覆盖预处理、版面检测、VLM 采样与导出全链路。结合本仓库的源码与测试你可以精确掌握每个参数的去向与校验边界快速在 RAG、文档问答等 AI 应用中落地可靠的文档解析能力。完整的中英文使用说明可继续查阅 langchain-paddleocr/README_cn.md 与 langchain-paddleocr/README.md。【免费下载链接】PaddleOCRTurn any PDF or image document into structured data for your AI. A powerful, lightweight OCR toolkit that bridges the gap between images/PDFs and LLMs. Supports 100 languages.项目地址: https://gitcode.com/GitHub_Trending/pa/PaddleOCR创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考