Chonkie

Chonkie (Chonkie)

RAG(Retrieval-Augmented Generation) 애플리케이션을 만들다 보면 문서를 잘게 쪼개서 임베딩하고 저장하는 작업이 반복적으로 필요해요. Chonkie는 그 과정을 아주 가볍고 빠르게 처리해 주는 chunking 라이브러리인데요, Qdrant와는 QdrantHandshake 클래스로 자연스럽게 이어져요. 덕분에 Chonkie SDK 안에서 벗어나지 않고도 텍스트를 chunking → embedding → 저장까지 한 번에 처리할 수 있어요.

출처: Qdrant 공식 문서 — chonkie

설정 (Setup)

Qdrant 지원을 포함해서 Chonkie를 설치해요.

pip install "chonkie[qdrant]"

기본 사용법 (Basic Usage)

QdrantHandshake는 청크를 저장하고 검색할 수 있는 간단한 인터페이스를 제공해요. 커스텀 임베딩 모델로 핸드셰이크를 초기화하면 되죠.

from chonkie import QdrantHandshake, SemanticChunker

# Initialize handshake with custom embedding model
handshake = QdrantHandshake(
    url="http://localhost:6333",
    collection_name="my_documents",
    embedding_model="sentence-transformers/all-MiniLM-L6-v2"
)

# Create and write chunks
chunker = SemanticChunker()
chunks = chunker.chunk("Your text content here...")
handshake.write(chunks)

# Search using natural language
results = handshake.search(query="your search query", limit=5)
for result in results:
    print(f"{result['score']}: {result['text']}")

먼저 SemanticChunker()로 텍스트를 의미 단위의 청크로 자르고, handshake.write()로 Qdrant에 저장해요. 검색은 별도 쿼리 언어 없이 자연어 그대로 handshake.search()로 수행할 수 있어요.

Qdrant Cloud 사용 시

로컬이 아니라 Qdrant Cloud를 쓸 때는 url에 클러스터 주소를 넣고 api_key를 전달하면 돼요.

handshake = QdrantHandshake(
    url="https://your-cluster.qdrant.io",
    api_key="your-api-key",
    collection_name="my_collection",
    embedding_model="BAAI/bge-small-en-v1.5"  # Change to your preferred model
)

완전한 RAG 파이프라인 (Complete RAG Pipeline)

Chonkie의 fluent Pipeline API를 쓰면 파일에서 문서를 읽어 Qdrant에 저장하는 end-to-end 파이프라인을 만들 수 있어요.

from chonkie import Pipeline

# Process documents and store in Qdrant with custom embedding model
docs = (
    Pipeline()
    .fetch_from("file", dir="./knowledge_base", ext=[".txt", ".md"])
    .process_with("text")
    .chunk_with("semantic", chunk_size=512)
    .store_in(
        "qdrant",
        collection_name="knowledge",
        url="http://localhost:6333",
        embedding_model="sentence-transformers/all-MiniLM-L6-v2"
    )
    .run()
)
print(f"Ingested {len(docs)} documents into Qdrant")

.fetch_from()으로 파일을 읽고, .process_with()로 가공한 뒤 .chunk_with()에서 chunking 전략을 정하고, 마지막 .store_in()으로 Qdrant에 저장해요. 마지막 .run()을 호출해야 실제로 전체 흐름이 실행돼요.

리파인(refinement)을 추가한 파이프라인

청크 사이에 문맥을 겹치게(overlap) 하거나 임베딩 모델을 바꾸고 싶다면 이렇게도 구성할 수 있어요.

from chonkie import Pipeline

# Advanced pipeline with overlapping context and custom embeddings
docs = (
    Pipeline()
    .fetch_from("file", dir="./docs")
    .process_with("text")
    .chunk_with("semantic", threshold=0.8)
    .refine_with("overlap", context_size=100)
    .store_in(
        "qdrant",
        url="https://your-cluster.qdrant.io",
        api_key="your-api-key",
        collection_name="knowledge_base",
        embedding_model="BAAI/bge-small-en-v1.5"
    )
    .run()
)

threshold=0.8은 청크를 나눌 의미적 유사도 기준이고, refine_with("overlap", context_size=100)은 앞뒤 청크의 내용을 100자 정도 겹치게 해서 문맥 손실을 줄여주는 설정이에요.

더 알아보기 (Learn more)