【RAG实战】LlamaIndex 深度集成:常用 Reader 全解析与自定义 Reader
LlamaIndex 深度集成常用 Reader 全解析与自定义 Reader 实战文章目录LlamaIndex 深度集成常用 Reader 全解析与自定义 Reader 实战LlamaIndex 深度集成常用 Reader 全解析与自定义 Reader 实战一、LlamaIndex Reader 体系架构1.1 BaseReader所有 Reader 的基座1.2 SimpleDirectoryReader 的核心调度逻辑二、LlamaIndex 常用 Reader 盘点2.1 SimpleDirectoryReader —— 目录批量读取2.2 DocxReader —— Word 文档读取2.3 PDFReader —— PDF 文件读取2.4 LlamaParseReader / LlamaParse —— 云端高质量解析2.5 BeautifulSoupWebReader —— 网页正文提取2.6 DatabaseReader —— 数据库读取2.7 其他常用 Reader三、Reader 对比与选型建议四、自定义 Reader 深度实战4.1 为什么需要自定义 Reader4.2 项目实战封装 LlamaParse 为 DOC/DOCX Reader4.3 注入 SimpleDirectoryReader 使用4.4 更简单的自定义 Reader 模板五、自定义 Reader 的规范与最佳实践5.1 必须继承 BaseReader5.2 load_data 签名规范5.3 元数据必须包含 file_path5.4 懒加载昂贵资源5.5 异常处理与日志5.6 通过 file_extractor 注入六、本项目文件读取架构总结七、总结LlamaIndex 深度集成常用 Reader 全解析与自定义 Reader 实战摘要在 RAG 应用中LlamaIndex 的 Reader 是数据入口。本文结合官方架构与项目实战从源码层面解析常用 Reader并给出自定义 Reader 的完整方案。一、LlamaIndex Reader 体系架构1.1 BaseReader所有 Reader 的基座# llama_index/core/readers/base.pyfromabcimportABC,abstractmethodfromtypingimportListfromllama_index.core.schemaimportDocumentclassBaseReader(ABC):abstractmethoddefload_data(self,*args:Any,**load_kwargs:Any)-List[Document]:加载数据并返回 Document 列表源码解读BaseReader是抽象基类只约束一个load_data方法Document是 LlamaIndex 的核心数据结构包含text和metadata任何自定义 Reader 只需实现load_data返回List[Document]1.2 SimpleDirectoryReader 的核心调度逻辑SimpleDirectoryReader是目录级入口它的核心作用是扫描目录递归或非递归收集文件扩展名匹配根据文件后缀选择 ReaderReader 分发通过file_extractor映射执行具体 ReaderDocument 组装合并所有 Reader 结果简化源码逻辑如下classSimpleDirectoryReader(BaseReader):def__init__(self,input_dir,file_extractorNone,...):self.input_dirinput_dir# 用户自定义的 Reader 映射self.file_extractorfile_extractoror{}def_get_default_file_extractor(self)-dict:默认的扩展名-Reader 映射return{.pdf:PDFReader(),.docx:DocxReader(),.txt:TextReader(),# ... 更多默认映射}defload_data(self,*args,**kwargs)-List[Document]:# 1. 收集文件filesself._get_files()# 2. 合并默认 自定义 file_extractorextractor{**self._get_default_file_extractor(),**self.file_extractor}documents[]forfileinfiles:extos.path.splitext(file)[1]readerextractor.get(ext)orself.default_reader# 3. 调用 Reader.load_datadocsreader.load_data(file)documents.extend(docs)returndocuments关键结论file_extractor优先级高于默认 Reader扩展名小写匹配如.docx、.pdf自定义 Reader 必须继承BaseReader二、LlamaIndex 常用 Reader 盘点2.1 SimpleDirectoryReader —— 目录批量读取概念SimpleDirectoryReader是 LlamaIndex 最常用的本地文件加载器支持自动识别多种格式。源码位置llama-index-core/llama_index/core/readers/file/base.py核心参数参数类型说明input_dirstr输入目录input_filesList[str]指定文件列表required_extsList[str]只读取指定后缀excludeList[str]排除文件支持通配符recursivebool是否递归子目录filename_as_idbool文件名作为 doc_idfile_extractordict自定义 Reader 映射使用方法fromllama_index.coreimportSimpleDirectoryReader documentsSimpleDirectoryReader(input_dir./knowledge_base,recursiveTrue,required_exts[.pdf,.docx,.txt],exclude[*.tmp,*.log],filename_as_idTrue,).load_data()源码级建议# file_extractor 的本质是一个字典# key: 文件扩展名带点如 .pdf# value: BaseReader 实例file_extractor{.pdf:PDFReader(),.docx:DocxReader(),.doc:MyCustomDocReader(),# 自定义 Reader}2.2 DocxReader —— Word 文档读取源码位置llama-index-readers-file/llama_index/readers/file/docs/base.py源码解读fromllama_index.readers.fileimportDocxReaderclassDocxReader(BaseReader):defload_data(self,file:Path,extra_info:Optional[Dict[str,Any]]None,**load_kwargs:Any,)-List[Document]:# 使用 python-docx 解析 docx# 将段落文本拼接为 Document...使用方法fromllama_index.readers.fileimportDocxReader readerDocxReader()docsreader.load_data(filereport.docx)深度集成建议简单 Word 文档可用复杂表格、图文混排建议使用LlamaParseReader可通过file_extractor注入2.3 PDFReader —— PDF 文件读取源码位置llama-index-readers-file/llama_index/readers/file/docs/base.py源码解读fromllama_index.readers.fileimportPDFReaderclassPDFReader(BaseReader):defload_data(self,file:Path,extra_info:Optional[Dict[str,Any]]None,**load_kwargs:Any,)-List[Document]:# 基于 PyPDF2 / pypdf 解析 PDF# 默认按页拆分 Document...使用方法fromllama_index.readers.fileimportPDFReader readerPDFReader()docsreader.load_data(filepaper.pdf)使用建议文字型 PDF 效果好扫描版、复杂排版效果差生产环境建议用LlamaParse或MinerU2.4 LlamaParseReader / LlamaParse —— 云端高质量解析源码位置llama-parse/llama_parse/__init__.py llama-cloud-services/llama_cloud_services/parse/__init__.py源码解读fromllama_parseimportLlamaParseclassLlamaParse:def__init__(self,api_key:str,result_type:strmarkdown,...):self.api_keyapi_key self.result_typeresult_typedefload_data(self,file_path:str)-List[Document]:# 上传文件到 LlamaParse 云端# 返回 Markdown/Text 结构使用方法fromllama_parseimportLlamaParsefromllama_cloud_services.parseimportResultType parserLlamaParse(api_keyyour-api-key,result_typeResultType.MD,verboseTrue,)documentsparser.load_data(complex.pdf)深度集成建议本项目将其包装为DocxLlamaParseReader和DocLlamaParseReader通过file_extractor注入SimpleDirectoryReader实现自动调用2.5 BeautifulSoupWebReader —— 网页正文提取源码位置llama-index-readers-web/llama_index/readers/web/beautiful_soup_web/base.py源码解读fromllama_index.readers.webimportBeautifulSoupWebReaderclassBeautifulSoupWebReader(BaseReader):defload_data(self,urls:List[str],custom_hostname:Optional[str]None,**kwargs:Any,)-List[Document]:# requests 获取 HTML# BeautifulSoup 提取正文使用方法fromllama_index.readers.webimportBeautifulSoupWebReader readerBeautifulSoupWebReader()docsreader.load_data(urls[https://example.com/article])使用建议网页 RAG 首选可配合爬虫框架批量抓取注意请求频率和反爬2.6 DatabaseReader —— 数据库读取源码位置llama-index-readers-database/llama_index/readers/database/base.py源码解读fromllama_index.readers.databaseimportDatabaseReaderclassDatabaseReader(BaseReader):def__init__(self,uri:str,query:str):self.uriuri self.queryquerydefload_data(self)-List[Document]:# 使用 SQLAlchemy 执行 SQL# 每行转换为 Document使用方法fromllama_index.readers.databaseimportDatabaseReader readerDatabaseReader(urimysqlpymysql://user:passlocalhost/db,querySELECT id, content FROM articles,)docsreader.load_data()2.7 其他常用 ReaderReader包名用途JSONReaderllama-index-readers-file读取 JSON 文件CSVReader/PandasCSVReaderllama-index-readers-file读取 CSV 文件MarkdownReaderllama-index-readers-file读取 Markdown 文件UnstructuredReaderllama-index-readers-file多格式复杂解析WikipediaReaderllama-index-readers-wikipedia维基百科SimpleWebPageReaderllama-index-readers-web简单网页读取NotionPageReaderllama-index-readers-notionNotion 页面GithubRepositoryReaderllama-index-readers-githubGitHub 仓库三、Reader 对比与选型建议Reader数据源优点缺点适用场景SimpleDirectoryReader本地目录批量、自动识别复杂版式弱本地文档批量入库DocxReader.docx轻量本地复杂排版差简单 WordPDFReader.pdf轻量本地扫描版差文字型 PDFLlamaParse多格式版式解析强需 API Key复杂文档BeautifulSoupWebReader网页自动正文提取受反爬限制网页 RAGDatabaseReader数据库对接业务数据需写 SQL企业数据JSONReader/CSVReader结构化文件简单易用需规范格式表格数据四、自定义 Reader 深度实战4.1 为什么需要自定义 Reader默认 Reader 不支持某些格式如.doc旧版 Word需要统一元数据如注入file_path、source需要接入外部解析服务如 LlamaParse、MinerU需要预处理文本如过滤页眉页脚、提取特定章节4.2 项目实战封装 LlamaParse 为 DOC/DOCX Reader本项目中的完整实现 DOCX 文件 LlamaParse 读取器适配 SimpleDirectoryReader 基于 llama_index.core.readers.base.BaseReader 实现 frompathlibimportPathfromtypingimportListfromllama_cloud_services.parseimportResultTypefromllama_index.core.readers.baseimportBaseReaderfromllama_index.core.schemaimportDocumentfromllama_parseimportLlamaParsefromutils.log_utilimportloggerdefcreate_llama_parser(result_type:ResultTypeResultType.MD,split_by_page:boolFalse):工厂函数创建 LlamaParse 解析器returnLlamaParse(api_keyyour-api-key,result_typeresult_type,verboseTrue,)classDocxLlamaParseReader(BaseReader): DOCX 文件读取器 通过 LlamaParse 官方 API 解析可被 SimpleDirectoryReader 通过 file_extractor 注入 def__init__(self,split_by_page:boolTrue,result_type:ResultTypeResultType.MD):self.split_by_pagesplit_by_page self.result_typeresult_type self._parser:LlamaParse|NoneNonedef_get_parser(self)-LlamaParse:懒加载解析器实例ifself._parserisNone:self._parsercreate_llama_parser(result_typeself.result_type,split_by_pageself.split_by_page,)returnself._parserdefload_data(self,file:Path,extra_info:dict|NoneNone,**load_kwargs)-List[Document]:file_pathstr(file)parserself._get_parser()logger.info(fDocxLlamaParseReader 开始读取:{file_path})documentsparser.load_data(file_path)# 注入元数据metadataextra_infoor{}metadata[file_path]file_path metadata[source]llamaparsefordocindocuments:doc.metadata.update(metadata)logger.info(fDocxLlamaParseReader 读取完成:{file_path}, 共{len(documents)}个 Document)returndocuments4.3 注入 SimpleDirectoryReader 使用fromllama_index.coreimportSimpleDirectoryReaderfrommodule_rag.rag_common.file_read.llamaParse_realize.docx_readerimportDocxLlamaParseReader# 自定义 file_extractorfile_extractor{.doc:DocLlamaParseReader(split_by_pageTrue),.docx:DocxLlamaParseReader(split_by_pageTrue),}readerSimpleDirectoryReader(input_dir./docs,required_exts[.doc,.docx],file_extractorfile_extractor,)documentsreader.load_data()4.4 更简单的自定义 Reader 模板frompathlibimportPathfromtypingimportListfromllama_index.core.readers.baseimportBaseReaderfromllama_index.core.schemaimportDocumentclassMyCustomReader(BaseReader):def__init__(self,encoding:strutf-8):self.encodingencodingdefload_data(self,file:Path,extra_info:dict|NoneNone,**load_kwargs,)-List[Document]:file_pathPath(file)# 1. 读取/处理文件withopen(file_path,r,encodingself.encoding)asf:textf.read()# 2. 构建元数据metadataextra_infoor{}metadata.update({file_path:str(file_path),file_name:file_path.name,file_ext:file_path.suffix,})# 3. 返回 Documentreturn[Document(texttext,metadatametadata)]# 使用readerMyCustomReader()docsreader.load_data(example.txt)五、自定义 Reader 的规范与最佳实践5.1 必须继承 BaseReaderfromllama_index.core.readers.baseimportBaseReaderclassMyReader(BaseReader):...5.2 load_data 签名规范defload_data(self,file:Path,extra_info:Optional[dict]None,**load_kwargs,)-List[Document]:...5.3 元数据必须包含 file_pathmetadataextra_infoor{}metadata[file_path]str(file_path)metadata[source]my_reader5.4 懒加载昂贵资源def_get_parser(self):ifself._parserisNone:self._parsercreate_parser()returnself._parser5.5 异常处理与日志try:documentsparser.load_data(file_path)exceptExceptionase:logger.error(f读取失败:{file_path}, 错误:{e})return[]5.6 通过 file_extractor 注入file_extractor{.doc:DocLlamaParseReader(),.docx:DocxLlamaParseReader(),.pdf:PDFReader(),}六、本项目文件读取架构总结module_rag/rag_common/file_read/ ├── __init__.py # 统一入口支持多种解析方式 ├── base_reader.py # 基于 SimpleDirectoryReader 的封装 ├── self_define/ # 本地 Reader 配置 └── llamaParse_realize/ # 基于 LlamaParse 的自定义 Reader ├── __init__.py # file_extractor 配置 ├── doc_reader.py # .doc 自定义 Reader └── docx_reader.py # .docx 自定义 Reader核心调用链common_read_file_content(file_path,read_methodLlamaParse)↓ _get_file_extractor_by_method(LlamaParse)↓ get_file_extractor()# 返回 {.doc: DocLlamaParseReader(), .docx: DocxLlamaParseReader()}↓ base_read_file(file_path,file_extractor)↓ SimpleDirectoryReader(input_files[file_path],file_extractorfile_extractor).load_data()↓ DocxLlamaParseReader.load_data(file)# 自定义 Reader↓ 返回 List[Document]七、总结Reader定位SimpleDirectoryReader本地目录批量加载入口DocxReader/PDFReader轻量本地文档解析LlamaParse复杂版式云端解析BeautifulSoupWebReader网页知识库DatabaseReader企业业务库自定义 Reader特殊格式和业务需求LlamaIndex 的 Reader 机制非常清晰继承BaseReader实现load_data通过file_extractor注入SimpleDirectoryReader。掌握这一点就能无缝扩展任意数据源深度集成 LlamaIndex。如果你需要我可以把文中示例整理成一个可运行的module_rag/rag_common/file_read/custom_reader_demo.py文件并接入你现有的file_read模块。

相关新闻

【2026年】实验室补风系统热平衡与节能设计

【2026年】实验室补风系统热平衡与节能设计

实验室排风量大、换气频繁,若不妥善处理补风,容易造成室内负压过大、空调负荷失衡,甚至影响安全。补风系统的热平衡设计,直接关系到实验室能否在高效排风的同时保持舒适安全、降低能耗。合理的补风方案是实验室通风设计中容易被忽…

2026/8/26 17:57:31 阅读更多 →
TVA与VLA双系统驱动的具身智能导航技术研究

TVA与VLA双系统驱动的具身智能导航技术研究

前沿技术探索:TVA智能体(简称TVA) TVA智能体(亦称“AI智能体视觉”或“TVA视觉智能体”)是依托Transformer架构与“因式智能体”理论构建的系统级视觉技术框架。它融合深度强化学习(DRL)、卷积…

2026/8/26 17:56:29 阅读更多 →
新课标英语写作不再只看成品!“过程写作法“家长必懂✏️

新课标英语写作不再只看成品!“过程写作法“家长必懂✏️

新课标有个重要变化:英语写作不再只看"写得好不好",而是关注"怎么写的"。这叫过程写作法——把写作拆成构思→起草→修改→定稿四个阶段,每个阶段都要教、都要练。但很多家长的感受是:孩子一写作文就发呆&…

2026/8/26 17:56:28 阅读更多 →

最新新闻

反转神经网络:Inverting CNNs窥探模型内部世界(XAI-papers图解教程)

反转神经网络:Inverting CNNs窥探模型内部世界(XAI-papers图解教程)

反转神经网络:Inverting CNNs窥探模型内部世界(XAI-papers图解教程) 【免费下载链接】XAI-papers 项目地址: https://gitcode.com/gh_mirrors/xa/XAI-papers 你是否好奇过,CNN 是如何从成千上万个像素中"认出"一…

2026/8/26 19:45:38 阅读更多 →
大型量产固件的工程实践(八):多款同类型芯片驱动的统一抽象

大型量产固件的工程实践(八):多款同类型芯片驱动的统一抽象

大型量产固件的工程实践(八):多款同类型芯片驱动的统一抽象 本文是《大型量产固件的工程实践》专栏第 8 篇。 上一篇:第 7 篇实战《日志打印实现源码与使用范例》 | 下一篇:第 9 篇《GPIO 模拟 SPI 驱动设计》 一、问题:几十款同类芯片怎么管 一个支持多产品线的固件,…

2026/8/26 19:45:37 阅读更多 →
LLM那些事 08:MCP——给所有工具配一个统一的插口

LLM那些事 08:MCP——给所有工具配一个统一的插口

1. 引言:每接一个新东西,就要重新连一遍 上一篇《RAG》的结尾,我留了一个问题:模型到这一步已经够全能了——会说话、看得懂长文、记得住上下文、能表示语义、能伸手调工具。可每次让它干一件新事,我都要单独给它写一套…

2026/8/26 19:45:37 阅读更多 →
5分钟让 Windows 拥有 Mac 级中文显示:PingFangSC 六字重双格式字体包

5分钟让 Windows 拥有 Mac 级中文显示:PingFangSC 六字重双格式字体包

5分钟让 Windows 拥有 Mac 级中文显示:PingFangSC 六字重双格式字体包 【免费下载链接】PingFangSC PingFangSC字体包文件、苹果平方字体文件,包含ttf和woff2格式 项目地址: https://gitcode.com/gh_mirrors/pi/PingFangSC 做 PPT 时是不是发现 W…

2026/8/26 19:45:37 阅读更多 →
ROS2 执行器(Executor)与回调组(Callback Group)

ROS2 执行器(Executor)与回调组(Callback Group)

ROS2 作为分布式机器人开发框架,其核心事件驱动模型依赖执行器(Executor) 驱动回调函数执行,而回调组(Callback Group) 则是控制回调并发策略的核心机制。 一、概念 1.1 执行器(Executor&#x…

2026/8/26 19:45:37 阅读更多 →
从Swift 2到4.2:SwiftyTimer版本演进史与Swifty API设计哲学

从Swift 2到4.2:SwiftyTimer版本演进史与Swifty API设计哲学

从Swift 2到4.2:SwiftyTimer版本演进史与Swifty API设计哲学 【免费下载链接】SwiftyTimer Swifty API for NSTimer 项目地址: https://gitcode.com/gh_mirrors/sw/SwiftyTimer SwiftyTimer 是一个用 Swift 编写的 NSTimer 定时器工具库,它提供 S…

2026/8/26 19:44:37 阅读更多 →

日新闻

Python random 模块常用函数详解:从入门到实战

Python random 模块常用函数详解:从入门到实战

目录 1. 引言2. 准备工作3. 基础随机函数4. 序列相关函数5. 随机种子与复现6. 实战案例7. 注意事项8. 常见问题与排查9. 总结 1. 引言 摘要: 本文系统介绍 Python 标准库 random 模块中最常用的随机数生成函数。内容涵盖基础随机函数(random()、unifor…

2026/8/26 0:00:40 阅读更多 →
《Microsoft Sql server 2008 Internals》读书笔记--第三章Databases and Database Files(2)

《Microsoft Sql server 2008 Internals》读书笔记--第三章Databases and Database Files(2)

《Microsoft Sql server 2008 Internals》索引目录: 《Microsoft Sql server 2008 Internals》读书笔记--目录索引 在上篇文章中,主要介绍了创建数据库的基本语法和FileGroup的初步知识。需要注意的是: 关于FileGroup 如果你的系统是用Raid设备直接存…

2026/8/26 1:18:18 阅读更多 →
政务AI智能体怎么建?三种模式、三步路径与四个误区

政务AI智能体怎么建?三种模式、三步路径与四个误区

政务AI智能体已经从概念试点阶段,转入了政务服务的常态化落地应用;在实际使用过程中,它能自主理解办事需求、辅助完成填报申报、开展材料预审,并联动多个系统协同作业,真正嵌入到政务办理的全流程当中。但在落地推进过…

2026/8/26 1:18:18 阅读更多 →

周新闻

[光学原理与应用-521]:对光的错误理解与纠偏

[光学原理与应用-521]:对光的错误理解与纠偏

首先光是一种能量的载体和形态,宏观上观察到的光是由无数个微观的光量子组成的,每个光子在产生的瞬间,其在真空的空间中以确定不变的速度沿着一个初始的方向一直向前,在微观层面,每个光量子的运动轨迹是以波函数所展现…

2026/8/26 14:45:33 阅读更多 →
SIP通话转接原理与REFER方法实战解析

SIP通话转接原理与REFER方法实战解析

1. 通话转接不是“挂断再拨号”,而是SIP会话的动态重定向你有没有遇到过这样的场景:客服坐席A正在和客户通电话,突然需要把这通对话无缝转给专家坐席B,客户完全感知不到中间的断连——既没听到忙音,也没被要求重新拨号…

2026/8/26 17:46:43 阅读更多 →
Kolla-ansible单节点OpenStack部署实战:从环境准备到排坑指南

Kolla-ansible单节点OpenStack部署实战:从环境准备到排坑指南

1. 为什么选择Kolla-ansible来部署单节点OpenStack?如果你正在寻找一种能把OpenStack从“概念”快速变成“可用的实验环境”的方法,那么Kolla-ansible几乎是当前最主流、最省心的选择。我见过太多人卡在手动编译依赖、配置服务、处理版本冲突的泥潭里&am…

2026/8/26 14:46:37 阅读更多 →

月新闻

免费解锁百度网盘SVIP加速:macOS用户必备的下载提速终极指南

免费解锁百度网盘SVIP加速:macOS用户必备的下载提速终极指南

免费解锁百度网盘SVIP加速:macOS用户必备的下载提速终极指南 【免费下载链接】BaiduNetdiskPlugin-macOS For macOS.百度网盘 破解SVIP、下载速度限制~ 项目地址: https://gitcode.com/gh_mirrors/ba/BaiduNetdiskPlugin-macOS 还在为百度网盘macOS版的龟速下…

2026/8/26 3:50:20 阅读更多 →
终极ncmdump指南:3分钟实现网易云NCM音乐解密与格式转换

终极ncmdump指南:3分钟实现网易云NCM音乐解密与格式转换

终极ncmdump指南:3分钟实现网易云NCM音乐解密与格式转换 【免费下载链接】ncmdump 项目地址: https://gitcode.com/gh_mirrors/ncmd/ncmdump 还在为网易云音乐下载的NCM格式文件无法在其他播放器播放而烦恼吗?ncmdump解密工具帮你轻松解决这个困…

2026/8/26 17:46:39 阅读更多 →
HarmonyOS 应用开发《掌上英语》第81篇: 智能体卡片:为英语学习 App 打造桌面级学习助手

HarmonyOS 应用开发《掌上英语》第81篇: 智能体卡片:为英语学习 App 打造桌面级学习助手

AgentCard 智能体卡片:为英语学习 App 打造桌面级学习助手适用平台:HarmonyOS 7.0 (API 26 Beta)一、引言 HarmonyOS 7.0(API 26 Beta)新增了 AgentCard 智能体卡片能力,这是继 HMAF(鸿蒙智能体框架&#x…

2026/8/26 1:24:05 阅读更多 →