SimpleDirectoryReader#

SimpleDirectoryReader 是将本地文件数据加载到 LlamaIndex 的最简单方式。对于生产环境，您可能会更倾向于使用 LlamaHub 上提供的众多阅读器之一，但 SimpleDirectoryReader 是入门的绝佳选择。

支持的文件类型#

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

.csv - 逗号分隔值文件
.docx - Microsoft Word 文档
.epub - EPUB 电子书格式
.hwp - 韩文文字处理器文档
.ipynb - Jupyter Notebook
.jpeg, .jpg - JPEG 图像
.mbox - MBOX 邮件存档
.md - Markdown 文档
.mp3, .mp4 - 音频和视频文件
.pdf - 便携式文档格式
.png - 便携式网络图形
.ppt, .pptm, .pptx - Microsoft PowerPoint 演示文稿

您可能期望在此看到 JSON 文件类型；为此我们推荐使用 JSON 加载器。

使用方法#

最基本的用法是传入 input_dir 参数，它将加载该目录下所有支持的文件：

from llama_index.core import SimpleDirectoryReader

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

当需要从目录加载大量文件时，可以使用并行处理方式。请注意 Windows 与 Linux/MacOS 机器在使用 multiprocessing 时存在差异（详见 multiprocessing 文档）。最终，Windows 用户可能看不到性能提升，而 Linux/MacOS 用户在加载相同文件集时则会获得性能提升。

...
documents = reader.load_data(num_workers=4)

读取子目录#

默认情况下，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():
    # <对每个文件的文档进行处理>
    all_docs.extend(docs)

限制加载的文件#

除了加载所有文件，您还可以传入文件路径列表：

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"]
)

通过 num_files_limit 可以设置加载文件的最大数量：

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

指定文件编码#

SimpleDirectoryReader 默认期望文件采用 utf-8 编码，但您可以通过 encoding 参数覆盖此设置：

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

提取元数据#

SimpleDirectoryReader 会自动为每个 Document 对象附加一个 metadata 字典。默认情况下，该字典包含以下内容：

file_path：文件的完整系统路径（包含文件名，字符串类型）
file_name：文件名（包含后缀，字符串类型）
file_type：文件的 MIME 类型（通过 mimetypes.guess_type() 推测，字符串类型）
file_size：文件大小（字节为单位，整数类型）
creation_date, last_modified_date, last_accessed_date：文件的创建、修改和访问日期（已标准化为 UTC 时区）。详见下文日期时间元数据（字符串类型）

您可以通过自定义函数来替换元数据生成逻辑。创建一个接收文件路径字符串并返回字典的函数，然后将其作为 file_metadata 参数传递给 SimpleDirectoryReader 构造函数：

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


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

docs = reader.load_data()
print(docs[0].metadata["foo"])  # 输出 "bar"

日期时间元数据#

SimpleDirectoryReader 中的默认元数据函数将日期输出为格式为 %Y-%m-%d 的格式化字符串。

为确保一致性，时间戳会标准化为 UTC 时区。如果输出日期与实际日期相差一天，可能是由于与 UTC 午夜时差所致。

扩展支持其他文件类型#

您可以通过将文件扩展名与 BaseReader 实例的映射字典作为 file_extractor 参数传递，来扩展 SimpleDirectoryReader 支持其他文件类型。BaseReader 应读取文件并返回 Document 对象列表。例如，添加对 .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 返回 Document 对象列表
        return [Document(text=text + "Foobar", extra_info=extra_info or {})]


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

documents = reader.load_data()
print(documents)

注意：此映射将覆盖您指定文件类型的默认文件提取器，如需继续支持这些类型，需要重新添加它们。

外部文件系统支持#

与其他模块类似，SimpleDirectoryReader 接受可选的 fs 参数，可用于遍历远程文件系统。

这可以是任何实现 fsspec 协议的文件系统对象。该协议为多种远程文件系统提供开源实现，包括 AWS S3、Azure Blob & DataLake、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,  # 递归搜索所有子目录
)

documents = reader.load_data()
print(documents)

完整示例笔记本可在此处查看：链接。