LlamaIndex 第六篇 SimpleDirectoryReader

SimpleDirectoryReader 是将本地文件数据加载到 LlamaIndex 的最简单方式。虽然在实际生产场景中，您更可能需要使用 LlamaHub 提供的多种数据读取器（Reader），但 SimpleDirectoryReader 无疑是快速入门的理想选择。

支持的文件类型

默认情况下，SimpleDirectoryReader 会尝试读取所有文件，并将其视为纯文本处理。除普通文本外，它还明确支持以下文件类型（通过文件扩展名自动识别）：

• .csv - comma-separated values

• .docx - Microsoft Word

• .epub - EPUB ebook format

• .hwp - Hangul Word Processor

• .ipynb - Jupyter Notebook

• .jpeg, .jpg - JPEG image

• .mbox - MBOX email archive

• .md - Markdown

• .mp3, .mp4 - audio and video

• .pdf - Portable Document Format

• .png - Portable Network Graphics

• .ppt, .pptm, .pptx - Microsoft PowerPoint

您可能会注意到这里缺少 JSON 文件类型——针对 JSON 格式，我们推荐使用专用的 JSON Loader 工具。

基本的用法

最基本的用法是传入一个 input_dir 参数，系统将自动加载该目录下所有支持的文件类型：

from llama_index.core import SimpleDirectoryReader

reader = SimpleDirectoryReader(input_dir="path/to/directory")
documents = reader.load_data()

子目录读取功能说明

默认情况下，SimpleDirectoryReader 仅读取目录顶层的文件。如需读取子目录中的文件，需设置参数 recursive=True：

SimpleDirectoryReader(input_dir="path/to/directory", recursive=True)

文件加载迭代处理

您还可以使用 iter_data() 方法在文件加载时进行迭代处理：

reader = SimpleDirectoryReader(input_dir="path/to/directory", recursive=True)
all_docs = []
for docs in reader.iter_data():
    # <do something with the documents per file>
    all_docs.extend(docs)

文件加载限制机制

除了加载目录中的所有文件，您还可以直接传入文件路径列表进行选择性加载：

# 通过明确路径列表加载特定文件
selected_files = [
    '/data/reports/Q1.pdf',
    '/data/notes/meeting.docx'
]
reader = SimpleDirectoryReader(
    input_files=selected_files  # 关键参数
)

或者，您可以通过 exclude 参数指定需要排除的文件路径列表：

reader = SimpleDirectoryReader(
    input_dir="./project_docs",
    exclude=[
        "temp/backup.pdf",      # 特定文件排除
        "drafts/",              # 整个目录排除
        "*.tmp"                # 通配符模式排除
    ]
)

您还可以通过设置 required_exts 参数，指定仅加载特定扩展名的文件：

reader = SimpleDirectoryReader(
    input_dir="./documents",
    required_exts=[".pdf", ".docx", ".pptx"],  # 白名单扩展名
    exclude=[".~lock.*"]  # 可搭配黑名单使用
)

您可以通过设置 num_files_limit 参数来限制最大文件加载数量：

reader = SimpleDirectoryReader(
    input_dir="./big_data",
    num_files_limit=1000,  # 最多加载1000个文件
    file_ordering="modified_desc"  # 按修改时间降序优先加载
)

指定文件编码

SimpleDirectoryReader 默认要求文件采用 UTF-8 编码，但您可以通过 encoding 参数自定义编码格式：

reader = SimpleDirectoryReader(
    input_dir="./text_data",
    encoding="utf-8",  # 默认编码
    fallback_encodings=["gbk", "iso-8859-1"]  # 备选编码
)