CocoIndex

CocoIndex (cocoindex)

CocoIndex는 AI용 데이터를 변환하는 고성능 ETL 프레임워크예요. 가장 큰 특징이 실시간 증분 처리(incremental processing) 인데요, 이 말은 바뀐 데이터만 다시 처리한다는 뜻이에요. 이 프레임워크에 Qdrant가 네이티브 벡터 데이터베이스로 내장되어 있어서, 임베딩을 저장하고 검색하는 일을 바로 처리할 수 있어요.

출처: Qdrant 공식 문서 — cocoindex

설치하기

CocoIndex를 설치하고, 상태(metadata) 저장소로 쓸 Postgres를 띄워볼게요.

pip install -U cocoindex

Postgres는 Docker Compose로 올려요.

docker compose -f <( curl -L https://raw.githubusercontent.com/cocoindex-io/cocoindex/refs/heads/main/dev/postgres.yaml ) up -d

여기서 잠깐, 왜 Postgres가 필요할까요? CocoIndex는 상태를 가진(stateful) ETL 프레임워크라서 변경된 데이터만 처리해요. 그런데 그러려면 '어디까지 처리했는지'를 기록해 둘 곳이 필요하고, 그 역할을 Postgres가 하는 거예요.

Qdrant로 데이터 내보내기

먼저 컬렉션을 만들 때 CocoIndex 쪽 벡터 필드 이름과 일치하는 벡터 이름으로 만들어 두고, 내보낼 때 setup_by_user=True를 설정해야 해요. 컬렉션 생성은 사용자가 직접 한다는 뜻이에요.

import cocoindex

doc_embeddings.export(
    "doc_embeddings",
    cocoindex.storages.Qdrant(
        collection_name="cocoindex",
        grpc_url="https://xyz-example.cloud-region.cloud-provider.cloud.qdrant.io:6334/",
        api_key="<your-api-key-here>",
    ),
    primary_key_fields=["id_field"],
    setup_by_user=True,
)

스펙에서 받는 필드를 정리하면 이래요.

  • collection_name (str, 필수): 데이터를 내보낼 컬렉션 이름이에요.
  • grpc_url (str, 선택): Qdrant 인스턴스의 gRPC URL이에요. 기본값은 http://localhost:6334/예요.
  • api_key (str, 선택): 요청 인증에 쓰는 API 키예요.

더 알아보기 (Learn more)