문서 한 개가 바뀌었다면 전체 RAG 인덱스를 다시 만들 필요는 없으며, CocoIndex는 변경된 원본과 그 파생 청크만 재계산하도록 설계됐습니다. 다만 메타데이터가 실제 벡터 DB 상태와 어긋나면 오래된 검색 결과가 조용히 남을 수 있어 정합성 검증이 핵심입니다.
CocoIndex 저장소는 소스, 변환, 타깃을 선언형 data flow로 정의하고, Rust 엔진이 변경 의존성을 추적합니다. 스프레드시트에서 한 셀이 바뀌면 연결된 수식만 다시 계산하는 것과 비슷합니다.
문서가 파싱되고 청크로 나뉘며 임베딩돼 벡터 DB에 들어가는 각 단계를 의존성으로 기록합니다. source의 추가, 수정, 삭제와 TTL 만료를 감지하면 관련된 파생 레코드만 upsert하거나 제거합니다. Postgres는 파이프라인 상태와 계보를 영속화하는 역할로 원문에 소개됩니다.
증분 처리의 이득은 문서 일부가 자주 바뀌고 임베딩 호출이 비싼 경우에 큽니다. 매번 입력 대부분이 바뀌거나 변환 함수가 전체 corpus 통계를 요구한다면 재계산 범위가 커져 이점이 줄어듭니다.
lineage에는 source ID만이 아니라 content hash, parser, chunker, embedding model과 transform code version을 포함해야 합니다. 문서 내용이 같아도 chunk size를 바꾸면 이후 모든 chunk ID와 vector가 달라질 수 있습니다. 반대로 파일 수정 시각만 바뀌었는데 content hash가 같다면 비싼 embedding을 건너뛸 수 있습니다. 어떤 field가 어느 파생 단계의 cache를 무효화하는지 명시합니다.
삭제는 추가보다 어렵습니다. 한 문서에서 만들어진 chunk, embedding, graph edge를 모두 찾아 제거해야 하며 다른 source와 공유하는 entity는 무작정 지우면 안 됩니다. source별 ownership과 target record ID를 lineage로 연결하고 tombstone이 target에 반영된 뒤에만 처리 완료로 표시합니다. TTL 만료와 사용자의 삭제 요청도 같은 감사 경로로 남깁니다.
원문은 S3 이벤트 같은 push와 주기적 pull을 모두 다루는 CDC 구조를 설명합니다. 이벤트가 중복되거나 순서가 뒤바뀌고, 타깃 write 뒤 metadata commit 전에 장애가 날 수 있습니다. 재시도 시 같은 upsert가 안전한지, 삭제가 누락되지 않는지 시험해야 합니다.
Postgres의 상태와 Qdrant, Neo4j, pgvector의 실제 레코드를 주기적으로 대조하는 reconciliation 작업이 필요합니다. 백업도 메타데이터와 타깃을 같은 시점으로 복구할 수 있어야 합니다.
예를 들어 vector upsert는 성공했는데 Postgres commit 전에 process가 죽으면 같은 event가 다시 실행됩니다. record key와 vector payload가 결정적이면 두 번째 upsert가 안전할 수 있지만, 임의 UUID를 만들면 duplicate가 남습니다. 반대로 metadata만 먼저 완료로 기록하면 target write 실패가 영구 누락됩니다. source event ID, transform version과 target key를 묶은 멱등 계약이 필요합니다.
event 순서도 확인합니다. v2 수정 뒤 늦게 도착한 v1 생성이 적용되지 않도록 source version이나 monotonic sequence를 비교합니다. version을 제공하지 않는 source는 최신 content를 다시 읽어 hash를 계산하고, 삭제, 재생성 경합을 별도 test로 둡니다. poison document 하나가 queue 전체를 막지 않도록 재시도 상한과 격리 queue를 운영합니다.
S3Source, chunk, OpenAI embedding과 QdrantTarget을 잇는 코드는 선언형 흐름을 설명하지만 패키지 버전, 인증, parse_pdf 정의와 오류 처리가 빠져 있습니다. 현재 CocoIndex API와 같은지 확인하지 않은 채 완전 실행법으로 쓰면 안 됩니다.
코드 인덱싱과 MCP는 cocoindex-code, Qdrant 연결은 기존 안내에서 원문이 참조합니다. 커밋되지 않은 로컬 코드를 색인한다면 비밀값과 생성 파일을 제외하는 규칙도 필요합니다.
평가할 때 문서 한 줄 수정, 파일 삭제, schema 변경, embedding model 교체를 각각 실행해 어떤 레코드가 다시 계산되는지 확인합니다. API 호출 수, 최신 상태 반영 시간, 실패 후 재시도와 stale record 수를 기준선 배치 파이프라인과 비교해야 합니다.
CocoIndex의 선언형 모델은 “어떻게”보다 “무엇을 파생할지”에 집중하게 하지만 프레임워크 lifecycle에 대한 학습과 Postgres 운영이 추가됩니다. 공식 사이트의 현재 범위를 확인하고, 전체 재색인 경로도 비상 복구용으로 남겨 두는 것이 안전합니다.
100~1,000개 문서의 golden corpus를 만들고 초기 full build 결과의 ID, chunk text, vector 수와 metadata를 snapshot으로 보관합니다. 이후 한 줄 수정, 중간 삽입, rename, 삭제, 같은 내용 재업로드와 out-of-order event를 적용합니다. 같은 최종 source 상태에서 clean rebuild한 결과와 증분 target을 비교해 missing, orphan, duplicate를 찾습니다.
평가표에는 변경 source 수 대비 다시 parse, chunk, embed한 수, embedding 호출, 비용, freshness lag, queue backlog, failure retry와 reconciliation 차이를 둡니다. query 품질도 대표 질문의 recall로 비교합니다. 호출량이 줄어도 오래된 vector가 검색되거나 새 chunk가 빠지면 증분 최적화는 실패입니다.
특히 문서 첫머리에 한 문단을 삽입해 뒤 chunk 경계가 모두 이동하는 경우와 고정 ID를 유지하는 chunker를 비교합니다. 재계산 수가 적어 보여도 새 문맥을 반영하지 못한 cache hit라면 오류이므로, 최종 chunk text와 source offset을 함께 대조해야 합니다.
transform schema나 embedding model 교체는 blue/green index로 처리할 수 있습니다. 새 version을 별도 namespace에 채우고 golden query와 record count를 검증한 뒤 alias를 전환합니다. 점진 update 중 서로 다른 vector dimension이나 model이 한 index에 섞이지 않게 합니다. rollback은 이전 index와 metadata checkpoint를 함께 가리켜야 합니다.
운영 중에는 metadata와 target의 source별 count, hash를 표본 또는 partition 단위로 대조합니다. 차이가 임계값을 넘으면 해당 partition을 rebuild하고 원인을 기록합니다. 전체 재색인은 패배가 아니라 lineage가 틀렸을 때 신뢰를 회복하는 필수 복구 수단입니다.
항상 그렇지 않습니다. chunk 경계, parser, embedding model이나 전체 corpus 의존 transform이 바뀌면 여러 record 또는 전체 rebuild가 필요할 수 있습니다.
아닙니다. event 중복, 순서 역전과 metadata, target 사이 부분 성공이 생길 수 있어 멱등 key, retry와 reconciliation이 필요합니다.
네. lineage 손상, schema나 model 대규모 변경, 복구 검증에는 clean rebuild가 필요하며 증분 결과와 비교하는 기준선 역할도 합니다.
←→ 키와 좌우 스와이프를 지원합니다. 읽던 페이지는 이 기기에 저장됩니다.