LangChain

텍스트 분할기

langchain_text_splitters: RecursiveCharacterTextSplitter, 토큰 기반 분할, Markdown 헤더 분할

#rag#text-splitter#chunking#documents공식 문서

텍스트 분할기(Text Splitter)는 긴 문서를 임베딩·검색에 알맞은 청크(chunk)로 나눕니다. 별도 패키지 langchain-text-splitters(설치 버전 1.1.3)에 있습니다. 대부분의 경우 RecursiveCharacterTextSplitter로 시작합니다. 이 분할기는 ["\n\n", "\n", " ", ""] 순서로 구분자를 시도하며 문단 → 줄 → 단어 단위로 점점 잘게 자릅니다.

Import

python
from langchain_text_splitters import (
    RecursiveCharacterTextSplitter, CharacterTextSplitter, TokenTextSplitter,
    MarkdownHeaderTextSplitter, Language,
)

시그니처

python
TextSplitter(chunk_size: int = 4000, chunk_overlap: int = 200,
             length_function: Callable[[str], int] = len,
             keep_separator: bool | Literal["start", "end"] = False,
             add_start_index: bool = False, strip_whitespace: bool = True)

RecursiveCharacterTextSplitter(separators: list[str] | None = None,
                               keep_separator: bool | Literal["start", "end"] = True,
                               is_separator_regex: bool = False, **kwargs)  # kwargs → TextSplitter
RecursiveCharacterTextSplitter.from_language(language: Language, **kwargs)
RecursiveCharacterTextSplitter.from_tiktoken_encoder(encoding_name: str = "gpt2", model_name: str | None = None,
                                                     allowed_special=None, disallowed_special="all", **kwargs)

CharacterTextSplitter(separator: str = "\n\n", is_separator_regex: bool = False, **kwargs)
TokenTextSplitter(encoding_name: str = "gpt2", model_name: str | None = None, ..., **kwargs)
MarkdownHeaderTextSplitter(headers_to_split_on: list[tuple[str, str]], return_each_line: bool = False,
                           strip_headers: bool = True, custom_header_patterns: dict[str, int] | None = None)

파라미터

파라미터타입기본값설명
chunk_sizeint4000청크 최대 길이(length_function 단위).
chunk_overlapint200인접 청크가 겹치는 길이. chunk_size보다 작아야 합니다.
length_functionCallable[[str], int]len길이 계산 함수(기본 문자 수). 토큰 단위는 from_tiktoken_encoder 사용.
keep_separatorbool | "start" | "end"False(Recursive는 True)구분자를 청크에 남길지, 앞/뒤 어디에 붙일지.
add_start_indexboolFalsemetadata["start_index"]에 원문 내 시작 위치 기록.
strip_whitespaceboolTrue청크 앞뒤 공백 제거.
separatorslist[str] | NoneNone → ["\n\n", "\n", " ", ""](Recursive) 시도할 구분자 순서.
is_separator_regexboolFalse구분자를 정규식으로 해석.
languageLanguage(from_language) Language.PYTHON, Language.MARKDOWN, Language.JS 등 언어별 구분자.
encoding_name / model_namestr"gpt2" / Nonetiktoken 인코딩. OpenAI 최신 모델은 encoding_name="o200k_base" 또는 model_name 지정.
headers_to_split_onlist[tuple[str, str]]필수(Markdown) [("#", "h1"), ("##", "h2")] → 헤더 값을 메타데이터 키에 저장.

메서드와 반환값

메서드반환설명
split_text(text)list[str]문자열 분할.
create_documents(texts, metadatas=None)list[Document]문자열 리스트 → 청크 Document(메타데이터 복사).
split_documents(documents)list[Document]Document 리스트 분할(메타데이터 유지).
MarkdownHeaderTextSplitter.split_text(text)list[Document]헤더 구조를 메타데이터로 가진 문서. 길이 제한은 없으므로 이후 Recursive로 한 번 더 나눕니다.

예제

python
from langchain_core.documents import Document
from langchain_text_splitters import RecursiveCharacterTextSplitter

text = "LangGraph는 상태 그래프 런타임이다.\n\n" * 5 + "체크포인터는 상태를 저장한다. " * 20
splitter = RecursiveCharacterTextSplitter(chunk_size=200, chunk_overlap=40, add_start_index=True)

chunks = splitter.split_documents([Document(page_content=text, metadata={"source": "guide.md"})])
for c in chunks[:3]:
    print(len(c.page_content), c.metadata)

토큰 기준 분할과 Markdown 헤더 분할:

python
from langchain_text_splitters import MarkdownHeaderTextSplitter, RecursiveCharacterTextSplitter

md = "# 설치\npip install langgraph\n## 요구 사항\nPython 3.10+\n# 사용법\nStateGraph를 만든다."
by_header = MarkdownHeaderTextSplitter([("#", "h1"), ("##", "h2")]).split_text(md)
for d in by_header:
    print(d.metadata, "|", d.page_content)

token_splitter = RecursiveCharacterTextSplitter.from_tiktoken_encoder(
    encoding_name="o200k_base", chunk_size=50, chunk_overlap=10
)
print(len(token_splitter.split_text("토큰 단위로 자르기 " * 50)))

주의사항

주의

chunk_size는 기본적으로 문자 수입니다. 임베딩 모델의 토큰 한도(예: 8191 토큰)를 넘지 않게 하려면 토큰 기반 분할(from_tiktoken_encoder)을 쓰세요. 한국어는 문자 수 대비 토큰 수가 영어보다 많습니다.

주의

하나의 구분자 조각이 chunk_size보다 길면 경고와 함께 더 긴 청크가 나올 수 있습니다(CharacterTextSplitter). 재귀 분할기는 더 작은 구분자로 내려가 이 문제를 줄입니다.

팁

검색 품질은 청크 크기에 크게 좌우됩니다. 일반 문서는 5001,000자, overlap 1020%에서 시작해 평가 데이터로 조정하세요.

관련 문서