LlamaIndex中的SimpleDirectoryReader

从本地文件系统加载文件到 LlamaIndex，最直接的方法就是通过 SimpleDirectoryReader。它就像一个“一站式”文件读取器，不需要复杂的配置就能快速读取多种格式。

默认情况下，SimpleDirectoryReader 会扫描指定目录下的所有文件，并尝试把它们当作纯文本直接读取。不过，它其实内置了对多种常见文件类型的支持，而且完全根据文件扩展名自动识别——你只需要把文件放在目录里，它就能自动搞定：

• .csv
  ：逗号分隔值

• .docx
  ：Microsoft Word

• .epub
  ：EPUB 电子书

• .hwp
  ：韩文文字处理器

• .ipynb
  ：Jupyter 笔记本

• .jpeg / .jpg
  ：JPEG 图像

• .mbox
  ：MBOX 电子邮件存档

• .md
  ：Markdown

• .mp3 / .mp4
  ：音频和视频

• .pdf
  ：便携式文档格式

• .png
  ：便携式网络图形

• .ppt / .pptm / .pptx
  ：Microsoft PowerPoint

如果你需要处理 JSON 文件，那就需要先安装专门的扩展：

pip install llama-index-readers-json

然后导入：

from llama_index.readers.json import JSONReader

最简单的用法：把目录路径传给 input_dir 参数，SimpleDirectoryReader 就会自动读取目录下所有支持格式的文件：

from llama_index.core import SimpleDirectoryReader

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

如果目录里文件很多，还可以通过并行处理来加速。需要注意的是，Windows 和 Linux/MacOS 在多线程性能上有差异——Windows 用户可能感受不到明显提升，但 Linux/MacOS 下速度会快不少：

documents = reader.load_data(num_workers=4)

从子目录中读取文件

设置 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():
    # 
    all_docs.extend(docs)

指定要读取的文件

如果你只想读取几个特定的文件，直接把文件路径列表传给 input_files 参数即可：

SimpleDirectoryReader(input_files=["path/to/file1", "path/to/file2"])

反过来，如果只想排除某些文件，用 exclude 参数：

SimpleDirectoryReader(input_dir="path/to/directory", exclude=["path/to/file1", "path/to/file2"])

还可以通过 required_exts 限定只读取某些扩展名，其他文件一律忽略：

SimpleDirectoryReader(input_dir="path/to/directory", required_exts=[".pdf", ".docx"])

甚至限制文件总数，避免一次性加载过多：

SimpleDirectoryReader(input_dir="path/to/directory", num_files_limit=100)

文件编码

默认编码是 UTF-8，如果遇到其他编码的文件，可以用 encoding 参数指定：

SimpleDirectoryReader(input_dir="path/to/directory", encoding="latin-1")

抽取元数据

很多时候我们不仅需要文件内容，还需要附带一些元数据（比如文件路径、自定义标签）。这时可以提供一个函数，file_metadata 参数会把它应用到每个文件上，结果会自动附加到 Document 对象中：

def get_meta(file_path):
    return {"foo": "bar", "file_path": file_path}

SimpleDirectoryReader(input_dir="path/to/directory", file_metadata=get_meta)

这个函数接收文件路径作为唯一参数，返回一个字典作为元数据。

扩展到其他文件类型

如果你有自定义的文件格式，可以先继承 BaseReader 实现一个读取类，然后通过 file_extractor 字典注册。举个例子，支持 .myfile 格式：

from llama_index.core import SimpleDirectoryReader
from llama_index.core.readers.base import BaseReader
from llama_index.core import Document

class MyFileReader(BaseReader):
    def load_data(self, file, extra_info=None):
        with open(file, "r") as f:
            text = f.read()
        # load_data returns a list of Document objects
        return [Document(text=text + "Foobar", extra_info=extra_info or {})]

reader = SimpleDirectoryReader(
    input_dir="./data", file_extractor={".myfile": MyFileReader()}
)

documents = reader.load_data()

注意：BaseReader 的 load_data 方法需要返回 Document 对象的列表。同时要记住，自定义的文件提取器会覆盖默认对该扩展名的处理方式，如果需要保留原有的 PDF、CSV 等支持，你需要把它们也显式加回来。

外部文件系统

如果你不想限制在本地磁盘，SimpleDirectoryReader 还支持通过 fs 参数访问远程文件系统。只要是实现了 fsspec 协议的对象都可以用——AWS S3、Azure Blob、Google Drive、SFTP 等都有开源实现。以 S3 为例：

from s3fs import S3FileSystem

s3_fs = S3FileSystem(key="...", secret="...")
bucket_name = "my-document-bucket"

reader = SimpleDirectoryReader(
    input_dir=bucket_name,
    fs=s3_fs,
    recursive=True,  # recursively searches all subdirectories
)

documents = reader.load_data()

这样一来，远程文件就像本地文件一样被加载到 LlamaIndex 中，省去了手动下载的麻烦。