SimpleDirectoryReader#

SimpleDirectoryReader 是将本地文件加载到 LlamaIndex 中的最简单方式。在生产环境中，您更可能希望使用 LlamaHub 上提供的众多读取器之一，但 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；对于这种情况，我们建议您使用我们的 JSON Loader。

用法#

最基本的用法是传递一个 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")

提取元数据#

您可以指定一个函数，该函数将读取每个文件并提取元数据，然后将其附加到每个文件的 Document 对象上，方法是将该函数作为 file_metadata 参数传递：

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


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

该函数应该接受一个参数，即文件路径，并返回一个元数据字典。

扩展到其他文件类型#

您可以通过将文件扩展名的字典传递给 BaseReader 的实例来扩展 SimpleDirectoryReader 以读取其他文件类型，方法是将 file_extractor 作为参数传递。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 协议实现的文件系统对象。 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)

完整的示例笔记本可以在这里找到。