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模块。