SimpleDirectoryReader#

SimpleDirectoryReader 是将本地文件中的数据加载到 LlamaIndex 的最简单方法。对于生产用例，您可能更希望使用 LlamaHub 上提供的众多 Reader 之一，但 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():
    # <do something with the documents per file>
    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 会自动将一个 metadata 字典附加到每个 Document 对象。默认情况下，此字典包含以下条目：

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"])  # prints "bar"

日期和时间元数据#

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

为了确保一致性，时间戳已标准化为 UTC 时区。如果输出日期看起来与实际日期相差一天，这可能是由于与 UTC 午夜的偏移造成的。

扩展到其他文件类型#

您可以通过将文件扩展名到 BaseReader 实例的字典作为 file_extractor 参数传递，来扩展 SimpleDirectoryReader 以读取其他文件类型。 BaseReader 应该读取文件并返回文档列表。例如，要添加对 `.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()
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,  # recursively searches all subdirectories
)

documents = reader.load_data()
print(documents)

完整的示例笔记本可以在此处找到。