Skip to main content
Open In ColabOpen on GitHub

如何创建一个自定义文档加载器

概述​

基于LLM的应用程序通常需要从数据库或文件（如PDF）中提取数据，并将其转换为LLM可以使用的格式。在LangChain中，这通常涉及创建Document对象，这些对象封装了提取的文本（page_content）以及元数据——一个包含文档详细信息的字典，例如作者的姓名或出版日期。

Document 对象通常被格式化为提示，输入到LLM中，使LLM能够使用Document中的信息生成所需的响应（例如，总结文档）。 Documents 可以立即使用，也可以索引到向量存储中以供将来检索和使用。

文档加载的主要抽象是：

组件描述
文档包含 text 和 metadata
BaseLoader用于将原始数据转换为Documents
Blob表示位于文件或内存中的二进制数据
BaseBlobParser解析Blob以生成Document对象的逻辑

本指南将演示如何编写自定义文档加载和文件解析逻辑；具体来说，我们将看到如何：

  1. 通过从BaseLoader子类化创建一个标准文档加载器。
  2. 使用BaseBlobParser创建一个解析器，并将其与Blob和BlobLoaders结合使用。这主要在处理文件时非常有用。

标准文档加载器​

文档加载器可以通过从BaseLoader子类化来实现，它提供了一个用于加载文档的标准接口。

接口​

方法名称说明
lazy_load用于懒加载文档。适用于生产代码。
alazy_loadlazy_load的异步变体
load用于将所有文档急切地加载到内存中。适用于原型设计或交互式工作。
aload用于将所有文档急切地加载到内存中。适用于原型设计或交互式工作。于2024-04添加到LangChain中。
  • load 方法是一个仅用于原型设计的便捷方法——它只是调用 list(self.lazy_load())。
  • alazy_load 有一个默认实现，它将委托给 lazy_load。如果您正在使用异步操作，我们建议覆盖默认实现并提供本地的异步实现。
important

在实现文档加载器时，不要通过lazy_load或alazy_load方法提供参数。

所有配置都期望通过初始化器（init）传递。这是LangChain做出的设计选择，以确保一旦文档加载器被实例化，它就拥有加载文档所需的所有信息。

实现​

让我们创建一个标准文档加载器的示例，该加载器加载文件并从文件中的每一行创建一个文档。

from typing import AsyncIterator, Iterator

from langchain_core.document_loaders import BaseLoader
from langchain_core.documents import Document


class CustomDocumentLoader(BaseLoader):
    """An example document loader that reads a file line by line."""

    def __init__(self, file_path: str) -> None:
        """Initialize the loader with a file path.

        Args:
            file_path: The path to the file to load.
        """
        self.file_path = file_path

    def lazy_load(self) -> Iterator[Document]:  # <-- Does not take any arguments
        """A lazy loader that reads a file line by line.

        When you're implementing lazy load methods, you should use a generator
        to yield documents one by one.
        """
        with open(self.file_path, encoding="utf-8") as f:
            line_number = 0
            for line in f:
                yield Document(
                    page_content=line,
                    metadata={"line_number": line_number, "source": self.file_path},
                )
                line_number += 1

    # alazy_load is OPTIONAL.
    # If you leave out the implementation, a default implementation which delegates to lazy_load will be used!
    async def alazy_load(
        self,
    ) -> AsyncIterator[Document]:  # <-- Does not take any arguments
        """An async lazy loader that reads a file line by line."""
        # Requires aiofiles (install with pip)
        # https://github.com/Tinche/aiofiles
        import aiofiles

        async with aiofiles.open(self.file_path, encoding="utf-8") as f:
            line_number = 0
            async for line in f:
                yield Document(
                    page_content=line,
                    metadata={"line_number": line_number, "source": self.file_path},
                )
                line_number += 1
API Reference:BaseLoader | Document

测试 🧪​

为了测试文档加载器，我们需要一个包含高质量内容的文件。

with open("./meow.txt", "w", encoding="utf-8") as f:
    quality_content = "meow meow🐱 \n meow meow🐱 \n meow😻😻"
    f.write(quality_content)

loader = CustomDocumentLoader("./meow.txt")
## Test out the lazy load interface
for doc in loader.lazy_load():
    print()
    print(type(doc))
    print(doc)

<class 'langchain_core.documents.base.Document'>
page_content='meow meow🐱 \n' metadata={'line_number': 0, 'source': './meow.txt'}

<class 'langchain_core.documents.base.Document'>
page_content=' meow meow🐱 \n' metadata={'line_number': 1, 'source': './meow.txt'}

<class 'langchain_core.documents.base.Document'>
page_content=' meow😻😻' metadata={'line_number': 2, 'source': './meow.txt'}
## Test out the async implementation
async for doc in loader.alazy_load():
    print()
    print(type(doc))
    print(doc)

<class 'langchain_core.documents.base.Document'>
page_content='meow meow🐱 \n' metadata={'line_number': 0, 'source': './meow.txt'}

<class 'langchain_core.documents.base.Document'>
page_content=' meow meow🐱 \n' metadata={'line_number': 1, 'source': './meow.txt'}

<class 'langchain_core.documents.base.Document'>
page_content=' meow😻😻' metadata={'line_number': 2, 'source': './meow.txt'}
tip

load() 在交互式环境（如 jupyter notebook）中非常有用。

避免在生产代码中使用它，因为急切加载假设所有内容都可以放入内存中，但这并不总是成立，尤其是对于企业数据。

loader.load()
[Document(page_content='meow meow🐱 \n', metadata={'line_number': 0, 'source': './meow.txt'}),
 Document(page_content=' meow meow🐱 \n', metadata={'line_number': 1, 'source': './meow.txt'}),
 Document(page_content=' meow😻😻', metadata={'line_number': 2, 'source': './meow.txt'})]

文件操作​

许多文档加载器涉及解析文件。这些加载器之间的区别通常源于文件的解析方式，而不是文件的加载方式。例如，你可以使用open来读取PDF或Markdown文件的二进制内容，但你需要不同的解析逻辑来将这些二进制数据转换为文本。

因此，将解析逻辑与加载逻辑解耦是有帮助的，这使得无论数据如何加载，都更容易重用给定的解析器。

BaseBlobParser​

一个BaseBlobParser是一个接口，它接受一个blob并输出一个Document对象列表。一个blob是表示数据的一种形式，这些数据可以存在于内存中或文件中。LangChain python有一个Blob原语，它受到了Blob WebAPI规范的启发。

from langchain_core.document_loaders import BaseBlobParser, Blob


class MyParser(BaseBlobParser):
    """A simple parser that creates a document from each line."""

    def lazy_parse(self, blob: Blob) -> Iterator[Document]:
        """Parse a blob into a document line by line."""
        line_number = 0
        with blob.as_bytes_io() as f:
            for line in f:
                line_number += 1
                yield Document(
                    page_content=line,
                    metadata={"line_number": line_number, "source": blob.source},
                )
API Reference:BaseBlobParser | Blob
blob = Blob.from_path("./meow.txt")
parser = MyParser()
list(parser.lazy_parse(blob))
[Document(page_content='meow meow🐱 \n', metadata={'line_number': 1, 'source': './meow.txt'}),
 Document(page_content=' meow meow🐱 \n', metadata={'line_number': 2, 'source': './meow.txt'}),
 Document(page_content=' meow😻😻', metadata={'line_number': 3, 'source': './meow.txt'})]

使用blob API还可以直接从内存加载内容，而不必从文件中读取！

blob = Blob(data=b"some data from memory\nmeow")
list(parser.lazy_parse(blob))
[Document(page_content='some data from memory\n', metadata={'line_number': 1, 'source': None}),
 Document(page_content='meow', metadata={'line_number': 2, 'source': None})]

Blob​

让我们快速浏览一下Blob API的一些内容。

blob = Blob.from_path("./meow.txt", metadata={"foo": "bar"})
blob.encoding
'utf-8'
blob.as_bytes()
b'meow meow\xf0\x9f\x90\xb1 \n meow meow\xf0\x9f\x90\xb1 \n meow\xf0\x9f\x98\xbb\xf0\x9f\x98\xbb'
blob.as_string()
'meow meow🐱 \n meow meow🐱 \n meow😻😻'
blob.as_bytes_io()
<contextlib._GeneratorContextManager at 0x743f34324450>
blob.metadata
{'foo': 'bar'}
blob.source
'./meow.txt'

Blob 加载器​

虽然解析器封装了将二进制数据解析为文档所需的逻辑，blob加载器则封装了从给定存储位置加载blob所需的逻辑。

目前，LangChain 仅支持 FileSystemBlobLoader。

你可以使用FileSystemBlobLoader来加载blob，然后使用解析器来解析它们。

from langchain_community.document_loaders.blob_loaders import FileSystemBlobLoader

blob_loader = FileSystemBlobLoader(path=".", glob="*.mdx", show_progress=True)
API Reference:FileSystemBlobLoader
parser = MyParser()
for blob in blob_loader.yield_blobs():
    for doc in parser.lazy_parse(blob):
        print(doc)
        break
  0%|          | 0/8 [00:00<?, ?it/s]
page_content='# Microsoft Office\n' metadata={'line_number': 1, 'source': 'office_file.mdx'}
page_content='# Markdown\n' metadata={'line_number': 1, 'source': 'markdown.mdx'}
page_content='# JSON\n' metadata={'line_number': 1, 'source': 'json.mdx'}
page_content='---\n' metadata={'line_number': 1, 'source': 'pdf.mdx'}
page_content='---\n' metadata={'line_number': 1, 'source': 'index.mdx'}
page_content='# File Directory\n' metadata={'line_number': 1, 'source': 'file_directory.mdx'}
page_content='# CSV\n' metadata={'line_number': 1, 'source': 'csv.mdx'}
page_content='# HTML\n' metadata={'line_number': 1, 'source': 'html.mdx'}

通用加载器​

LangChain 有一个 GenericLoader 抽象，它将 BlobLoader 与 BaseBlobParser 组合在一起。

GenericLoader 旨在提供标准化的类方法，使得使用现有的 BlobLoader 实现变得容易。目前，仅支持 FileSystemBlobLoader。

from langchain_community.document_loaders.generic import GenericLoader

loader = GenericLoader.from_filesystem(
    path=".", glob="*.mdx", show_progress=True, parser=MyParser()
)

for idx, doc in enumerate(loader.lazy_load()):
    if idx < 5:
        print(doc)

print("... output truncated for demo purposes")
API Reference:GenericLoader
  0%|          | 0/8 [00:00<?, ?it/s]
page_content='# Microsoft Office\n' metadata={'line_number': 1, 'source': 'office_file.mdx'}
page_content='\n' metadata={'line_number': 2, 'source': 'office_file.mdx'}
page_content='>[The Microsoft Office](https://www.office.com/) suite of productivity software includes Microsoft Word, Microsoft Excel, Microsoft PowerPoint, Microsoft Outlook, and Microsoft OneNote. It is available for Microsoft Windows and macOS operating systems. It is also available on Android and iOS.\n' metadata={'line_number': 3, 'source': 'office_file.mdx'}
page_content='\n' metadata={'line_number': 4, 'source': 'office_file.mdx'}
page_content='This covers how to load commonly used file formats including `DOCX`, `XLSX` and `PPTX` documents into a document format that we can use downstream.\n' metadata={'line_number': 5, 'source': 'office_file.mdx'}
... output truncated for demo purposes

自定义通用加载器​

如果你真的喜欢创建类，你可以子类化并创建一个类来将逻辑封装在一起。

你可以从这个类派生子类，以使用现有的加载器加载内容。

from typing import Any


class MyCustomLoader(GenericLoader):
    @staticmethod
    def get_parser(**kwargs: Any) -> BaseBlobParser:
        """Override this method to associate a default parser with the class."""
        return MyParser()
loader = MyCustomLoader.from_filesystem(path=".", glob="*.mdx", show_progress=True)

for idx, doc in enumerate(loader.lazy_load()):
    if idx < 5:
        print(doc)

print("... output truncated for demo purposes")
  0%|          | 0/8 [00:00<?, ?it/s]
page_content='# Microsoft Office\n' metadata={'line_number': 1, 'source': 'office_file.mdx'}
page_content='\n' metadata={'line_number': 2, 'source': 'office_file.mdx'}
page_content='>[The Microsoft Office](https://www.office.com/) suite of productivity software includes Microsoft Word, Microsoft Excel, Microsoft PowerPoint, Microsoft Outlook, and Microsoft OneNote. It is available for Microsoft Windows and macOS operating systems. It is also available on Android and iOS.\n' metadata={'line_number': 3, 'source': 'office_file.mdx'}
page_content='\n' metadata={'line_number': 4, 'source': 'office_file.mdx'}
page_content='This covers how to load commonly used file formats including `DOCX`, `XLSX` and `PPTX` documents into a document format that we can use downstream.\n' metadata={'line_number': 5, 'source': 'office_file.mdx'}
... output truncated for demo purposes

这个页面有帮助吗？