lightonai/next-plaid

이 프로젝트가 무엇인가

LightOn AI가 구축한 두 가지 관련 도구:

NextPlaid — 텍스트의 다중 벡터 표현을 저장하고 REST API를 통해 검색 쿼리를 제공하는 검색 데이터베이스. 사용자 머신에서 로컬로 실행됩니다.
ColGREP — NextPlaid 위에 구축된 코드 검색 도구. "database connection pooling" 같은 질문을 입력하면 프로젝트에서 관련 코드를 찾아내며, 전통적인 정규식 매칭과 의미론적 순위를 결합합니다. 모든 것이 사용자 머신에서 실행되며, 코드가 외부로 나가지 않습니다.

둘 다 오픈소스(Apache-2.0)입니다.

ColGREP: 의미론적 코드 검색

ColGREP는 단일 Rust 바이너리입니다 — 서버 없음, API 없음, 의존성 없음. Homebrew 또는 셸 설치 프로그램으로 설치한 후:

colgrep init /path/to/project   # 인덱스를 한 번 구축
colgrep "database connection pooling"   # 검색

인덱스는 첫 사용 시 자동으로 구축되며 파일 변경 시 증분 업데이트됩니다.

두 가지 검색 모드:

직접 검색 — 코드베이스에 대한 의미론적 순위. 정규식과 결합할 수도 있습니다: colgrep -e "async.*await" "error handling"는 패턴과 의미로 결과를 좁힙니다.
에이전트 모드 — colgrep --agent "where is the database connection pool configured"는 하위 에이전트처럼 작동하는 소형 로컬 모델(일회성, 2.5 GB)을 다운로드합니다: 검색하고, 후보 파일을 읽고, 질문에 답하는 정확한 줄 번호를 반환합니다. 대형 코딩 모델은 이에 위임하여 자체 컨텍스트 창을 절약할 수 있습니다.

ColGREP가 코드를 인덱싱하는 방법

파싱 — Tree-sitter가 코드를 함수, 메서드, 클래스로 파싱합니다.
구조화 — 각 코드 단위는 구조화된 텍스트로 변환됩니다: 시그니처, 매개변수, 호출, docstring, 코드 본문.
임베딩 — 소형 모델(lightonai/LateOn-Code-edge, 1700만 매개변수)이 해당 구조화된 텍스트를 코드 단위당 여러 벡터(다중 벡터 임베딩)로 변환합니다. CPU에서 실행.
인덱스 — NextPlaid는 이러한 벡터를 양자화된 메모리 매핑 바이너리 인덱스에 저장합니다.

이 구조화된 표현은 원시 코드만으로보다 모델에 더 풍부한 신호를 제공합니다.

모델 전환

임베딩 모델을 교체할 수 있습니다(colgrep set-model, --model 플래그, colgrep status로 인덱스가 무엇으로 구축되었는지 확인). 각 (프로젝트, 모델) 쌍에는 자체 인덱스가 있으므로 전환해도 기존 인덱스가 손상되지 않습니다. 비공개 HuggingFace 모델은 HF_TOKEN으로 사용할 수 있습니다.

에이전트 통합

Claude Code(--install-claude-code), OpenCode, Codex, Hermes용 후크를 설치합니다. Claude는 완전한 후크 지원을 제공합니다. 나머지 세 개는 현재 기본 수준입니다.

벤치마크

Semble 공개 코드 검색 벤치마크(1,251개 쿼리 × 63개 저장소 × 19개 언어)에서 ColGREP는 LateOn-Code 모델로 NDCG@10 = 0.859, 더 작은 edge 모델로 0.846을 기록하며 이전 모델(semble potion-code-16M의 0.853)을 약간 앞섰습니다.

왜 다중 벡터인가?

전통적인 벡터 검색은 전체 문서를 하나의 임베딩으로 압축합니다 — 손실이 있는 요약입니다. 이는 단일 함수에 이름, 매개변수, docstring, 제어 흐름, 의존성이 있는 코드에는 부적합합니다.

다중 벡터 검색은 문서당 약 300개의 차원 128 임베딩을 유지합니다. 쿼리 시 각 쿼리 토큰은 모든 문서 토큰에서 최상의 일치를 찾습니다(MaxSim이라는 기법). 트레이드오프 — 더 많은 저장 공간 — 은 NextPlaid가 양자화와 메모리 매핑 인덱스로 해결합니다.

NextPlaid: 기본 엔진

NextPlaid는 REST API를 갖춘 범용 로컬 우선 다중 벡터 데이터베이스입니다. 기능:

내장 인코딩 — 원시 텍스트를 보내고 결과를 얻습니다. 별도의 추론 서버가 필요 없습니다. ColBERT 모델용 ONNX Runtime이 포함되어 있습니다.
메모리 매핑 인덱스 — 인덱스는 디스크에 있으며 필요 시 페이지 인되므로 RAM 사용량이 낮게 유지됩니다.
곱 양자화 — 2비트 또는 4비트 압축. 백만 개 문서가 메모리에 들어갑니다.
증분 업데이트 — 재구축 없이 문서 추가/삭제.
메타데이터 사전 필터링 — 내장 SQLite 저장소의 SQL WHERE 절이 점수 계산 전에 실행되므로 일치하는 문서만 점수가 매겨집니다.
CPU 최적화, 선택적 CUDA 지원.

FastPlaid와의 관계: FastPlaid는 대규모 단일 패스 워크로드를 위한 GPU 배치 인덱서입니다. NextPlaid는 동일한 알고리즘을 스트리밍 수집 및 서비스에 적합한 프로덕션 API로 래핑합니다.

빠른 시작: Docker 컨테이너(CPU 또는 CUDA 이미지)를 실행한 다음 Python 클라이언트(pip install next-plaid-client)를 사용하여 인덱스 생성, 문서 추가, 검색, 메타데이터 필터링, 삭제를 수행합니다. Swagger UI는 http://localhost:8080/swagger-ui에서 사용할 수 있습니다.

API 벤치마크

인코딩 시간을 포함한 엔드투엔드 측정(모델이 API 내부에서 실행). 설정: GTE-ModernColBERT-v1을 NVIDIA H100 80GB에서 사용, top_k=100. BEIR 데이터셋의 샘플 결과:

quora (522,931 문서): NDCG@10 = 0.8519, 인덱싱 속도 105 문서/초, GPU에서 약 21 QPS, CPU에서 약 18 QPS.
nfcorpus (3,633 문서): NDCG@10 = 0.3828, GPU에서 약 7 QPS.
scifact (5,183 문서): NDCG@10 = 0.7593.

전체 테이블은 6개 데이터셋을 다루며 MAP, NDCG@10/100, Recall@10/100, 처리량, 지연 시간 백분위수를 포함합니다.

모델

모든 HuggingFace ColBERT 스타일 모델은 pylate-onnx-export를 사용하여 ONNX 형식으로 내보낼 수 있습니다(기본적으로 FP32 및 INT8 변형. INT8은 약 4배 작고 빠르며 품질 손실이 최소). 바로 사용 가능한 모델:

모델	용도
`lightonai/LateOn-Code-edge`	코드 검색, 경량
`lightonai/LateOn-Code`	코드 검색, 정확
`lightonai/mxbai-edge-colbert-v0-32m-onnx`	텍스트 검색, 경량
`lightonai/answerai-colbert-small-v1-onnx`	텍스트 검색, 경량
`lightonai/GTE-ModernColBERT-v1`	텍스트 검색, 정확

결론

ColGREP는 단일 바이너리로 의미론적 코드 검색을 사용자 머신에 제공합니다. NextPlaid는 그 아래의 재사용 가능한 다중 벡터 데이터베이스입니다. 스트리밍 서비스 대신 대량 GPU 인덱싱이 필요하다면 자매 프로젝트 FastPlaid가 대안입니다.