ChonkieSemanticDocumentSplitter

ChonkieSemanticDocumentSplitter

ChonkieSemanticDocumentSplitter는 Chonkie의 SemanticChunker를 이용해 의미적 유사도에 따라 문서를 나누는 컴포넌트예요.

출처: 문서

본문

이 페이지는 Chonkie의 SemanticChunker를 감싸, 문장이 의미적으로 크게 달라지는 지점(토픽 전환 등)에서 문서를 분할하는 방법을 설명합니다. 순수한 문자·토큰 분할과 달리, 의미 단위로 담긴 텍스트를 더 자연스럽게 나누는 데 초점을 맞춰요.

Overview

ChonkieSemanticDocumentSplitter는 Chonkie의 SemanticChunker를 감싸며, 각 입력 문서의 임베딩·의미적 유사도를 기반으로 문장을 그룹화해 의미적으로 일관된 청크를 만듭니다. 동일한 토픽의 문장은 함께 묶이고, 의미 전환이 일어나는 지점에서 새 청크가 시작됩니다.

각 출력 문서는 원본 문서의 메타데이터에 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".
chunk_size 2048 청크당 최대 토큰 수.
chunk_overlap 0 연속된 청크 사이 겹치는 토큰 수.
embedder 제품 기본값 문장 임베딩에 쓰는 임베더.
min_sentences_per_chunk 1 각 청크에 반드시 포함되어야 하는 최소 문장 수.
min_characters_per_sentence 12 문장이 유효한 것으로 간주되는 최소 문자 수.
skip_empty_documents True 빈 내용의 문서를 건너뛸지 여부.
page_break_character "\f" 페이지 번호 추적 시 페이지 나눔을 감지하는 문자.

Usage

On its own

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

chunker = ChonkieSemanticDocumentSplitter(chunk_size=512)
documents = [Document(content="Haystack is a framework for building LLM applications. ...")]
result = chunker.run(documents=documents)
print(result["documents"])

In a pipeline

인덱싱 파이프라인에서는 Converters와 DocumentCleaner 이후, Embedders 이전에 배치해 의미적으로 일관된 청크를 생성한 뒤 임베딩·저장합니다:

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 (
    ChonkieSemanticDocumentSplitter,
)

document_store = InMemoryDocumentStore()
p = Pipeline()
p.add_component("converter", TextFileToDocument())
p.add_component("cleaner", DocumentCleaner())
p.add_component("splitter", ChonkieSemanticDocumentSplitter(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")
p.run({"converter": {"sources": list(Path("path").glob("*.txt"))}})

참고: 이 페이지는 페이지의 전체 파라미터 표와 세부 예시를 요약한 것입니다. 정확한 기본값과 Seq2Seq 임베딩 옵션 등은 원문 페이지를 참고하세요.

더 알아보기 (Learn more)