Langchain-Chatchat 图片文档加载器 RapidOCRLoader源码原理与知识库接入实战【免费下载链接】Langchain-ChatchatLangchain-Chatchat原Langchain-ChatGLM基于 Langchain 与 ChatGLM, Qwen 与 Llama 等语言模型的 RAG 与 Agent 应用 | Langchain-Chatchat (formerly langchain-ChatGLM), local knowledge based LLM (like ChatGLM, Qwen and Llama) RAG and Agent app with langchain项目地址: https://gitcode.com/GitHub_Trending/la/Langchain-ChatchatRapidOCRLoader 是 Langchain-Chatchat 中专门负责图像文件 OCR 文本提取的自定义文档加载器它把本地图片PNG/JPG/JPEG/BMP中的文字识别出来并结构化成分块chunk文档供 RAG 知识库检索与问答使用。本文将以 myimgloader.md 为核心结合其对应源码与测试用例剖析 RapidOCRLoader 的完整实现链路、与 RapidOCR 引擎的耦合方式以及在知识库入库流水线中的真实接入位置帮助读者理解并复用这一能力。一、RapidOCRLoader 的定位与适用场景在 Langchain-Chatchat 的 RAG 流水线中不同文件格式由不同文档加载器Document Loader负责解析。图片无法像文本文件那样被直接读取必须借助 OCR光学字符识别把图像中的文字翻译回文本才能进入后续的文本分块、向量化与检索环节。RapidOCRLoader 正是为这一场景设计的它的输入是图像文件的路径输出是LangchainDocument对象列表严格来说是unstructured分块产生的元素列表每个元素携带page_content形式的识别文本。其适用场景包括截图、照片中的文字资料入库扫描件配图、产品说明书图片等内容的本地知识库构建与其他 OCR 加载器PDF/DOCX/PPT配合覆盖知识库中图片类附件的解析。从源码结构看它和RapidOCRPDFLoader、RapidOCRDocLoader、RapidOCRPPTLoader同属一组RapidOCR 家族加载器并统一从 document_loaders/init.py 导出。四者的核心区别仅在于前置解析PDF/DOCX/PPT 需要先把内部对象转成图片再走 OCR而图片加载器直接对图像文件本身执行识别。二、源码总览一个极简的 UnstructuredFileLoader 子类RapidOCRLoader 的全部实现位于 myimgloader.py代码非常精炼from typing import List from langchain_community.document_loaders.unstructured import UnstructuredFileLoader from chatchat.server.file_rag.document_loaders.ocr import get_ocr class RapidOCRLoader(UnstructuredFileLoader): def _get_elements(self) - List: def img2text(filepath): resp ocr get_ocr() result, _ ocr(filepath) if result: ocr_result [line[1] for line in result] resp \n.join(ocr_result) return resp text img2text(self.file_path) from unstructured.partition.text import partition_text return partition_text(texttext, **self.unstructured_kwargs)整个类不定义新的公开属性也不重写load()而是复用了父类UnstructuredFileLoader的加载框架只实现其钩子方法_get_elements()。UnstructuredFileLoader的load()流程会调用_get_elements()并把返回值包装成带元数据的文档对象因此调用方只需from chatchat.server.file_rag.document_loaders import RapidOCRLoader loader RapidOCRLoader(file_pathpath/to/image.jpg) docs loader.load() # docs 中每个元素含 page_content 属性代码末尾还附带了可直接运行的入口用于快速自测if __name__ __main__: loader RapidOCRLoader(file_path../tests/samples/ocr_test.jpg) docs loader.load() print(docs)从整体结构可以推断RapidOCRLoader 约定了图像路径 → OCR 识别 → 文本拼接 → 文本分区这一固定流水线其中真正与图像文件打交道的是img2text内部函数与get_ocr()工厂函数。三、底层引擎工厂 get_ocrPaddle 优先、ONNXRuntime 兜底img2text的第一步是调用get_ocr()获取 OCR 处理器实例其实现位于 ocr.pydef get_ocr(use_cuda: bool True) - RapidOCR: try: from rapidocr_paddle import RapidOCR ocr RapidOCR( det_use_cudause_cuda, cls_use_cudause_cuda, rec_use_cudause_cuda ) except ImportError: from rapidocr_onnxruntime import RapidOCR ocr RapidOCR() return ocr这里体现了两点关键设计双后端自动降级优先尝试导入基于 PaddlePaddle 的rapidocr_paddle包若环境中未安装该包触发ImportError则回退到更轻量的 ONNXRuntime 版本rapidocr_onnxruntime。这意味着只要安装了 RapidOCR 的任一后端图片加载功能即可工作。CUDA 开关透传Paddle 后端会把use_cuda分别透传给检测det、方向分类cls与识别rec三个阶段。get_ocr的默认值是True因此在未安装 CUDA 支持或不具备 GPU 的环境中使用 Paddle 后端时应显式传入use_cudaFalse即调用get_ocr(use_cudaFalse)否则可能引发运行时错误ONNXRuntime 兜底分支则不做 CUDA 配置天然适用于纯 CPU 场景。RapidOCR 引擎内部通常由文本检测det 方向分类cls 文字识别rec三个子模型组成其完整的多阶段流程预处理、检测、裁剪、识别、后处理对上层img2text完全透明——上层只拿到最终结果列表。四、img2text从图像到单行分隔的文本字符串img2text(filepath)是_get_elements内部定义的闭包函数负责最核心的图像→文本转换接受一个字符串类型的图片路径def img2text(filepath): resp ocr get_ocr() result, _ ocr(filepath) if result: ocr_result [line[1] for line in result] resp \n.join(ocr_result) return resp逐行解读其行为ocr(filepath)返回二元组(result, elapse)结构其中result是识别结果列表第二项通常为耗时信息此处用_丢弃从源码的[line[1] for line in result]写法可以推断result中每个元素是一个形如(文本框坐标, 识别文本, 置信度)的序列取下标1即得到该行的纯文本内容所有识别行用换行符\n连接拼成单一字符串返回。例如图像中包含第一行、第二行文字时返回值为第一行\n第二行若result为空例如图中没有文字函数返回空字符串不会抛异常后续partition_text处理空串也会安全返回空列表。文档中强调的注意点同样值得落实为工程约束filepath必须是真实存在且有效的图像文件路径否则识别过程可能失败同时 OCR 准确度受图片质量、文字清晰度、字体大小、版面复杂度等因素直接影响对低质量或极度复杂的图片需要接受一定的识别损失。五、_get_elements文本分区的二次结构化_get_elements()没有直接参数通过self.file_path读取图片路径、通过self.unstructured_kwargs读取分区参数text img2text(self.file_path) from unstructured.partition.text import partition_text return partition_text(texttext, **self.unstructured_kwargs)它完成两件事调用img2text(self.file_path)把__init__阶段传入的图片路径转换成纯文本调用unstructured库的partition_text(texttext, **self.unstructured_kwargs)对 OCR 得到的整段文本做分区partition——例如按段落、标题结构切成更细粒度的块使后续分块器text splitter和检索器拿到更干净的文本单元。self.unstructured_kwargs是UnstructuredFileLoader预留的透传参数字典最终由调用方知识库文件处理层传入。这解释了为什么模块文档要求确保self.unstructured_kwargs包含partition_text所需的全部参数——不同的分区策略例如是否按标题切分、语言模型参数等会直接改变返回元素的粒度与数量。处理完成后load()会把这些元素包装成带page_content与元数据的文档列表返回供上层使用。以一张包含文本Hello World! Welcome to OCR processing.且设置为按句分区的图片为例返回元素可能形如[Hello World!, Welcome to OCR processing.]完整load()输出的文档对象则类似[ Document(page_content这是通过OCR技术提取的文本内容。, metadata{...}) ]六、在知识库文件处理流水线中的真实接入位置理解了类本身还需要看清它在整个 Langchain-Chatchat 中是如何被自动调度的。这涉及 knowledge_base/utils.py 中的三处机制6.1 扩展名注册表 LOADER_DICTLOADER_DICT { ... RapidOCRPDFLoader: [.pdf], RapidOCRDocLoader: [.docx], RapidOCRPPTLoader: [.ppt, .pptx], RapidOCRLoader: [.png, .jpg, .jpeg, .bmp], ... } SUPPORTED_EXTS [ext for sublist in LOADER_DICT.values() for ext in sublist]RapidOCRLoader被显式声明为.png、.jpg、.jpeg、.bmp四种常见位图格式的加载器并由get_LoaderClass(file_extension)反查得到——这决定了知识库上传/同步这四类图片时会被自动路由到 RapidOCRLoader。6.2 加载器工厂 get_loader 的特殊导入分支def get_loader(loader_name: str, file_path: str, loader_kwargs: Dict None): ... if loader_name in [ RapidOCRPDFLoader, RapidOCRLoader, FilteredCSVLoader, RapidOCRDocLoader, RapidOCRPPTLoader, ]: document_loaders_module importlib.import_module( chatchat.server.file_rag.document_loaders ) else: document_loaders_module importlib.import_module( langchain_community.document_loaders )可以看到RapidOCR 系列及 FilteredCSVLoader 属于项目自定义加载器get_loader会优先从chatchat.server.file_rag.document_loaders模块动态导入其他格式则回落到langchain_community.document_loaders。如果导入异常函数会兜底回退到UnstructuredFileLoader避免文件处理流程整体崩溃。6.3 KnowledgeFile 的统一调度入口class KnowledgeFile: def __init__(self, filename, knowledge_base_name, loader_kwargs{}): ... self.document_loader_name get_LoaderClass(self.ext) self.text_splitter_name Settings.kb_settings.TEXT_SPLITTER_NAME def file2docs(self, refresh: bool False): if self.docs is None or refresh: loader get_loader( loader_nameself.document_loader_name, file_pathself.filepath, loader_kwargsself.loader_kwargs, ) if isinstance(loader, TextLoader): loader.encoding utf8 self.docs loader.load() else: self.docs loader.load() return self.docs因此一张图片进入知识库后的完整调用链为上传图片 →KnowledgeFile.file2docs()→get_loader()按扩展名选中RapidOCRLoader→loader.load()→_get_elements()→img2text()get_ocr()→ RapidOCR 引擎识别 → 返回 Document 列表 → 交给make_text_splitter()分块 → 向量化入库紧随其后的docs2texts()会调用配置指定的文本分块器如 ChineseRecursiveTextSplitter对 OCR 文本做最终切块再由文件模型层写入向量库实现完整的图片知识入库。七、测试用例一张样本图验证整条链路官方在 tests/document_loader/test_imgloader.py 中提供了针对 RapidOCRLoader 的单元测试是理解其行为契约的最佳入口test_files { ocr_test.jpg: str(root_path / tests / samples / ocr_test.jpg), } def test_rapidocrloader(): img_path test_files[ocr_test.jpg] from document_loaders import RapidOCRLoader loader RapidOCRLoader(img_path) docs loader.load() pprint(docs) assert ( isinstance(docs, list) and len(docs) 0 and isinstance(docs[0].page_content, str) )该测试揭示了 RapidOCRLoader 需要满足的三条行为契约load()必须返回list类型对包含文字的样本图返回列表非空首个元素的page_content必须是字符串即 OCR 文本已被正确提取并包装。测试所用的样本图为 tests/samples/ocr_test.jpg与 PDF/DOCX/PPTX 样本ocr_test.pdf、ocr_test.docx、ocr_test.pptx同属 OCR 测试样本族。需要说明的是该测试运行依赖环境已安装 RapidOCR 相关依赖rapidocr_paddle或rapidocr_onnxruntime测试通过 pprint 打印出的内容可直接肉眼核对 OCR 识别质量。八、在自定义代码中独立使用的完整示例脱离知识库框架开发者也可以把 RapidOCRLoader 当作普通文档加载器单独使用。以仓库内 OCR 测试样本为例from chatchat.server.file_rag.document_loaders import RapidOCRLoader # 1. 直接加载图片 loader RapidOCRLoader( file_pathtests/samples/ocr_test.jpg, unstructured_kwargs{}, # 可按需传入 partition_text 的参数 ) docs loader.load() # 2. 读取识别文本 for doc in docs: print(doc.page_content) # 3. 若在 CPU 环境使用 Paddle 后端注意关闭 CUDA见 ocr.py from chatchat.server.file_rag.document_loaders.ocr import get_ocr ocr get_ocr(use_cudaFalse)如需与 Langchain 生态进一步集成可直接把返回的文档列表交给TextSplitter、向量库或检索链使用行为与加载文本文件得到的Document完全一致。九、使用前提、注意事项与边界结合模块文档与源码使用 RapidOCRLoader 时需重点注意以下几点依赖前提环境中须安装 RapidOCR 的后端包rapidocr_paddle优先缺失时自动回退rapidocr_onnxruntime否则get_ocr()内部的两个导入分支都会失败CUDA 环境匹配Paddle 后端下get_ocr默认use_cudaTrue纯 CPU 或未装 CUDA 环境应调用get_ocr(use_cudaFalse)避免运行期错误ONNXRuntime 分支不受此参数影响输入限定图像文件该加载器面向位图图像PNG/JPG/JPEG/BMP不适用于其他类型文件对 PDF/DOCX/PPT 应分别使用同族的 RapidOCRPDFLoadermypdfloader.py、RapidOCRDocLoadermydocloader.py、RapidOCRPPTLoadermypptloader.py文件路径有效性file_path必须是磁盘上真实存在的图像文件load()内部不提供远程 URL 拉取能力识别质量边界OCR 效果受图片清晰度、文字字体与大小、版面复杂度等制约识别出的文字可能包含错字或漏字入库前的质量抽查类似测试中pprint打印人工核对是推荐实践文本完整性约定识别文本以换行符分隔合并为单个字符串后再分区这意味着图片中文字原本的段落、标题等版式信息可能在识别与拼接过程中被扁平化后续检索效果取决于分区与分块参数的合理配置。总体而言RapidOCRLoader 用极少的代码将OCR 识别 unstructured 分区两大能力缝合进了 Langchain-Chatchat 的知识库体系是理解该项目如何为图片类非结构化数据提供 RAG 能力的最佳切入点之一。读者既可以把它作为现成加载器在知识库中直接使用也可以以此为模板将其替换为其他 OCR 引擎来定制自己的图像文档加载方案。【免费下载链接】Langchain-ChatchatLangchain-Chatchat原Langchain-ChatGLM基于 Langchain 与 ChatGLM, Qwen 与 Llama 等语言模型的 RAG 与 Agent 应用 | Langchain-Chatchat (formerly langchain-ChatGLM), local knowledge based LLM (like ChatGLM, Qwen and Llama) RAG and Agent app with langchain项目地址: https://gitcode.com/GitHub_Trending/la/Langchain-Chatchat创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考