ChonkieRecursiveDocumentSplitter

ChonkieRecursiveDocumentSplitter

ChonkieRecursiveDocumentSplitter는 Chonkie의 RecursiveChunker를 이용해 분할 규칙의 계층(hierarchy)으로 문서를 나누는 컴포넌트예요. 모든 청크가 설정한 크기 제약을 만족할 때까지 점점 더 세밀한 분할을 적용하므로, Markdown이나 코드처럼 구조화된 텍스트에 효과적입니다.

출처: 문서

본문

항목 내용
파이프라인에서의 일반적인 위치 인덱싱 파이프라인에서 Converters 이후, Embedders 이전
필수 run 변수 documents — 문서 리스트
출력 변수 documents — 문서 리스트
API reference Chonkie
GitHub link https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/chonkie

Overview

ChonkieRecursiveDocumentSplitter는 Chonkie의 RecursiveChunker를 감싸서, 분할 규칙을 단계별로 적용하며 문서를 나눠요. 한 단계에서 생성된 청크가 여전히 chunk_size를 초과하면 다음 단계의 규칙이 그 청크에 적용됩니다. 이 과정은 모든 청크가 크기 제한 안에 들어올 때까지 재귀적으로 계속돼요.

Chonkie의 RecursiveRules를 제공하면 분할 동작을 직접 커스터마이즈할 수 있습니다. 커스텀 규칙 정의에 대한 자세한 내용은 Chonkie 문서를 참고하세요.

각 출력 문서는 원본 문서의 메타데이터에 다음 정보를 더해 포함합니다:

  • source_id — 원본 문서의 ID
  • page_number — 원본 문서 내에서 청크가 있는 페이지 번호
  • split_id — 문서 내에서 청크의 인덱스
  • split_idx_start / split_idx_end — 원본 텍스트에서 청크의 문자 오프셋
  • token_count — 청크의 토큰 수

Installation

pip install chonkie-haystack

Configuration

Parameter Default Description
tokenizer "character" 사용할 토크나이저. 일반 옵션: "character", "gpt2", "cl100k_base". 모든 옵션은 Chonkie 문서 참고.
chunk_size 2048 청크당 최대 토큰 수.
min_characters_per_chunk 24 청크가 반드시 포함해야 하는 최소 문자 수.
rules None 분할 계층을 정의하는 커스텀 RecursiveRules. None이면 Chonkie 기본 규칙 사용.
skip_empty_documents True 빈 내용의 문서를 건너뛸지 여부.
page_break_character "\f" 페이지 번호를 추적할 때 페이지 나눔을 감지하는 데 쓰는 문자.

Usage

On its own

from haystack import Document
from haystack_integrations.components.preprocessors.chonkie import (
    ChonkieRecursiveDocumentSplitter,
)

chunker = ChonkieRecursiveDocumentSplitter(chunk_size=512)
documents = [
    Document(
        content="# Introduction\n\nHaystack is a framework.\n\n## Features\n\nIt supports RAG pipelines.",
    ),
]
result = chunker.run(documents=documents)
print(result["documents"])

With custom rules

from chonkie.types.recursive import RecursiveLevel, RecursiveRules
from haystack import Document
from haystack_integrations.components.preprocessors.chonkie import (
    ChonkieRecursiveDocumentSplitter,
)

rules = RecursiveRules(
    levels=[
        RecursiveLevel(delimiters=["\n\n"]),
        RecursiveLevel(delimiters=["\n"]),
        RecursiveLevel(delimiters=[". ", "! ", "? "]),
    ],
)

chunker = ChonkieRecursiveDocumentSplitter(chunk_size=256, rules=rules)
documents = [Document(content="First paragraph.\n\nSecond paragraph with more detail.")]
result = chunker.run(documents=documents)
print(result["documents"])

In a pipeline

from pathlib import Path

from haystack import Pipeline
from haystack.components.converters import TextFileToDocument
from haystack.components.preprocessors import DocumentCleaner
from haystack.components.writers import DocumentWriter
from haystack.document_stores.in_memory import InMemoryDocumentStore
from haystack_integrations.components.preprocessors.chonkie import (
    ChonkieRecursiveDocumentSplitter,
)

document_store = InMemoryDocumentStore()

p = Pipeline()
p.add_component("converter", TextFileToDocument())
p.add_component("cleaner", DocumentCleaner())
p.add_component("splitter", ChonkieRecursiveDocumentSplitter(chunk_size=512))
p.add_component("writer", DocumentWriter(document_store=document_store))

p.connect("converter.documents", "cleaner.documents")
p.connect("cleaner.documents", "splitter.documents")
p.connect("splitter.documents", "writer.documents")

files = list(Path("path/to/your/files").glob("*.md"))
p.run({"converter": {"sources": files}})

더 알아보기 (Learn more)