LangChain

문서 로더 개요

Document, BaseLoader, Blob/BaseBlobParser 인터페이스와 커스텀 로더 작성

#document-loaders#document#rag#ingestion공식 문서

문서 로더(Document Loader)는 파일·웹·DB 같은 원천에서 데이터를 읽어 Document(page_content, metadata) 리스트로 바꿉니다. 인터페이스는 langchain_core.document_loaders에 있고, 구체 로더(PDF, HTML, Notion 등) 대부분은 langchain-community나 파트너 패키지에 있습니다.

이 프로젝트의 강의 코드는 langchain_community를 쓰지 않으므로, 로더는 아래 인터페이스로 직접 작성하거나 파일 파싱 라이브러리(예: pypdf, beautifulsoup4)를 감싸서 씁니다.

Import

python
from langchain_core.documents import Document
from langchain_core.document_loaders import BaseLoader, BaseBlobParser, Blob, BlobLoader, LangSmithLoader

시그니처

python
class Document(BaseMedia):
    def __init__(self, page_content: str, *, id: str | None = None, metadata: dict = {}) -> None

class BaseLoader(ABC):
    def lazy_load(self) -> Iterator[Document]          # 서브클래스가 구현
    async def alazy_load(self) -> AsyncIterator[Document]
    def load(self) -> list[Document]                   # = list(self.lazy_load())
    async def aload(self) -> list[Document]
    def load_and_split(self, text_splitter: TextSplitter | None = None) -> list[Document]

class Blob(BaseMedia):
    # Blob.from_path(path, *, encoding="utf-8", mime_type=None, guess_type=True, metadata=None)
    # Blob.from_data(data, *, encoding="utf-8", mime_type=None, path=None, metadata=None)
    data: bytes | str | None; mimetype: str | None; encoding: str = "utf-8"; path: str | PurePath | None
    def as_string(self) -> str; def as_bytes(self) -> bytes

class BaseBlobParser(ABC):
    def lazy_parse(self, blob: Blob) -> Iterator[Document]   # 서브클래스가 구현
    def parse(self, blob: Blob) -> list[Document]

파라미터

파라미터타입기본값설명
page_contentstr필수문서 본문 텍스트.
metadatadict{}출처(source), 페이지 번호, 작성일 등. 검색 필터와 인용에 사용.
idstr | NoneNone문서 ID. 벡터 스토어 upsert 키로 쓰입니다.
text_splitterTextSplitter | NoneNone(load_and_split) 기본은 RecursiveCharacterTextSplitter().
data / pathbytes | str / 경로None(Blob) 원시 데이터 또는 파일 경로(지연 로드).

메서드와 반환값

메서드반환설명
lazy_load()Iterator[Document]메모리를 아끼는 스트리밍 로드. 대용량은 이것을 사용.
load()list[Document]전부 메모리로 로드.
load_and_split()list[Document]로드 후 분할. 소스 docstring에서 사실상 deprecated로 표시되어 있으므로 splitter.split_documents(loader.load())처럼 분리하세요.
BaseBlobParser.parse(blob)list[Document]바이트 → 문서 변환(로딩과 파싱 분리).

주요 외부 로더(참고, 별도 패키지):

원천패키지/클래스
PDF, Word, HTML 등 범용langchain-unstructured의 UnstructuredLoader
PDFlangchain-community의 PyPDFLoader, 또는 pypdf 직접 사용
웹 페이지langchain-community의 WebBaseLoader, 또는 httpx + beautifulsoup4
LangSmith 데이터셋langchain_core.document_loaders.LangSmithLoader

예제

커스텀 로더(디렉터리의 .md 파일):

python
import tempfile
from collections.abc import Iterator
from pathlib import Path
from langchain_core.document_loaders import BaseLoader
from langchain_core.documents import Document


class MarkdownDirLoader(BaseLoader):
    def __init__(self, root: str) -> None:
        self.root = Path(root)

    def lazy_load(self) -> Iterator[Document]:
        for path in sorted(self.root.rglob("*.md")):
            yield Document(
                page_content=path.read_text(encoding="utf-8"),
                metadata={"source": str(path.relative_to(self.root))},
                id=str(path.relative_to(self.root)),  # 재색인 시 upsert 키
            )


with tempfile.TemporaryDirectory() as d:
    Path(d, "a.md").write_text("# 휴가 규정\n연차 15일", encoding="utf-8")
    Path(d, "b.md").write_text("# 재택 규정\n주 2회", encoding="utf-8")
    for doc in MarkdownDirLoader(d).lazy_load():
        print(doc.id, doc.metadata, doc.page_content.splitlines()[0])

Blob 파서:

python
from collections.abc import Iterator
from langchain_core.document_loaders import BaseBlobParser, Blob
from langchain_core.documents import Document


class LineParser(BaseBlobParser):
    def lazy_parse(self, blob: Blob) -> Iterator[Document]:
        for i, line in enumerate(blob.as_string().splitlines()):
            if line.strip():
                yield Document(line, metadata={"line": i, "source": blob.source})


blob = Blob.from_data("첫 줄\n\n둘째 줄", path="memo.txt")
print(LineParser().parse(blob))

주의사항

주의

langchain_community는 유지보수 주기가 느리고 의존성이 무거워 이 프로젝트의 실행 예제에서는 금지되어 있습니다. 운영 코드에서도 로더 하나를 위해 전체를 설치하기보다 파트너 패키지나 파싱 라이브러리를 직접 감싸는 편이 안전합니다.

주의

웹·PDF 등 외부 문서는 신뢰할 수 없는 입력입니다. 문서 안의 "이전 지시를 무시하라" 같은 문장이 프롬프트 인젝션이 될 수 있으므로, 검색 결과를 시스템 프롬프트가 아닌 데이터로 취급하세요.

팁

metadata["source"]와 안정적인 id를 반드시 채우세요. 인용, 필터링, 재색인 시 중복 제거가 모두 이 값에 의존합니다.

관련 문서