llamaindex SimpleDirectoryReader的使用

SimpleDirectoryReader

概念解释

SimpleDirectoryReader 是 LlamaIndex 中加载本地文件数据的最简单方式。对于生产用例，你可能更倾向于使用 LlamaHub 上提供的众多读取器之一，但 SimpleDirectoryReader 是开始使用的好方法。

支持的文件类型

默认情况下，SimpleDirectoryReader 会尝试读取它找到的任何文件，并将它们都视为文本文件。除了纯文本之外，它还明确支持以下文件类型，这些文件类型是根据文件扩展名自动检测的：

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

你可能期望在这里找到 JSON 文件类型；对于 JSON，我们建议你使用我们的 JSON 加载器。

使用方法

最基本的用法是传递一个 input_dir，它将加载该目录中的所有支持文件：

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)

从子目录读取

默认情况下，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)

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

通过这些详细的解释和示例，希望你能更好地理解和使用 LlamaIndex 中的 SimpleDirectoryReader 功能。