Quivr V2

연속적인 콘텐츠 스트림을 검색 및 모니터링할 수 있도록 변환하는 오픈소스 엔진입니다.

Quivr V2는 콘텐츠를 안정적으로 흡수(ingest)하고, 몇 초 만에 검색 가능하게 만들며, 백그라운드에서 이를 풍부화(enrich)하여 시간이 지남에 따라 특정 주제를 추적할 수 있게 합니다. 핵심은 일반적인 구조를 유지합니다: 형식(formats), AI 모델, 비즈니스 규칙은 플러그인에 속하므로, 플랫폼을 포크(forking)하지 않고도 Quivr를 원하는 도메인에 맞게 조정할 수 있습니다.

상태: 평가 단계입니다. API는 v0이며 예고 없이 변경될 수 있습니다. 아직 프로덕션 환경에서 실행하지 마십시오.

Quivr V2의 장점

• 속도보다 안정성(Durable before fast). 쓰기 작업은 커밋되는 순간에만 승인됩니다. 서비스 중단이 발생하면 처리가 지연될 뿐, 콘텐츠를 손실하거나 조용히 실패하지 않습니다.
• 모든 곳에서 동일성 유지(Idempotent everywhere). 모든 쓰기 작업에는 동일성 키(idempotency key)가 포함됩니다. 재실행은 동일한 결과를 반환하며, 변경된 재실행은 충돌로 간주되고, 수정 사항은 기록을 덮어쓰는 대신 새로운 불변 버전(immutable Versions)을 생성합니다.
• 초기 유용성, 후기 풍부함(Useful early, richer later). 텍스트는 분할되는 즉시 어휘적으로 검색 가능해지며, 임베딩 및 기타 풍부화 작업은 이를 차단하지 않고 나중에 도착합니다. 하이브리드 검색은 키워드 결과를 유지하면서 벡터를 재구축하고 영향을 받은 코퍼스(Cpora)를 보고합니다.
• 재구축 가능한 인덱스(Rebuildable indexes). PostgreSQL과 S3가 표준 데이터(canonical data)를 보유하며, 검색 인덱스는 안정적인 아티팩트로부터 재구축될 수 있는 투영(projection)입니다.
• 정직한 검색(Honest search). 모든 검색 결과는 표준 저장소에서 재활성화되고 재권한 부여됩니다. 종속성 서비스 중단은 빈

빠른 시작하기 (Quickstart)

요구 사항: Linux x86_64 또는 Apple Silicon을 사용하는 macOS에서 make dev 실행 시 다음이 필요합니다. Go 1.27.2, Compose v2가 포함된 Docker, venv를 사용한 Python 3, Node.js 22+ 및 jq. 첫 실행 시 고정된 이미지와 E5 모델(~1 GB)을 다운로드합니다.

make dev      # 의존성 시작, 마이그레이션 실행, API + 워커 구동
make check    # Docker 없이 문서(docs), 계약(contracts), vet 및 단위 테스트 실행 (약 2분); 푸시 전에 실행
make verify   # make check를 수행한 후 격리된 스택에서 종단 간 여정(end-to-end journeys)을 검증
...

make verify는 모든 기능의 수용 테스트 스위트와 하나로 구성된 모니터링 여정을 격리된 스택에서 실행합니다. 실패하거나 Ctrl+C를 누른 후에도 해당 프로젝트만 제거합니다. 그런 다음 어떤 단계가 실패했는지, 고정된 버전과 의존성 목록을 명시하는 report.md 파일의 경로를 출력합니다. 이는 CI와 마찬가지로 Linux x86_64에서만 실행되므로 남은 제한 사항(remaining limits)을 참조하세요.

make dev는 API 주소와 임시 로컬 키를 담고 있는 생성된 config.json 파일의 경로를 출력합니다. eval "$(make -s env)"는 해당 주소, 키 및 웹훅 목적지를 내보냅니다. 그런 다음 빠른 시작하기(Quickstart)에 따라 Corpus를 생성하고, 아티클을 추가하며, 검색하고, 알림을 받는 과정을 make verify가 실제 스택에서 재현하는 명령어를 사용합니다.

동일한 API를 사용하는 브라우저 UI의 경우 make demo를 실행하고 http://127.0.0.1:5183에 접속하세요 (quivr-search/ 참조).

현재 작동하는 기능 (What works today)

• 하나의 Compose 파일, CPU 임베딩, 영구 저장소 및 선택적 데모 인터페이스를 사용하여 릴리스 이미지로 단일 머신에서 Quivr 실행하기가 가능합니다.

• 인증된 HTTPS, 영구 데이터 디스크 및 Idempotent Azure CLI 프로비저닝 예제를 사용하여 전용 호스트에서 벡터 인덱스 실행하기가 가능합니다.

• 개인 JSON 선언으로부터 설치 재설정 및 다시 로드하기 기능은 미리 보기와 불변(idempotent) 공개 API 리플레이를 제공합니다.

• 로컬 추론, 자체 모델 서버 또는 호스팅된 API를 위한 임베딩 모델 선택하기가 가능하며, 재구축 요구 사항 및 실행 전용 튜닝을 지원합니다. 대규모 가져오기 실행하기 기능은 대량 작업자(bulk workers), 제공업체 용량, 데이터베이스 크기 지정 및 큐 모니터링을 다룹니다.

• 검색 기능은 과부하 또는 기타 검색 종속성 실패와는 별개로 재시도 가능한 503 model_unavailable 상태의 보고서 쿼리-모델 장애를 감지합니다. 검색 오류를 참조하세요.

• 작업자 자동 확장(Worker autoscaling)은 대량 또는 실시간 큐 백로그를 따라가며, KEDA, quivr-autoscaler 바이너리(Kubernetes 또는 Railway), 또는 수동으로 설정할 수 있습니다. 실시간 작업자는 별도의 용량을 유지합니다.

• 순차적인 애플리케이션 업그레이드는 추가적인 스키마 확장(additive schema expansions)을 사용하며, 파괴적인 정리 실행은 quivr migrate --contract를 통해서만 가능합니다. API 및 작업자 재시도 성능 지수 빌드(performance-index builds)는 백그라운드에서 진행되므로, 바쁜 인덱스 빌드가 시작을 지연시키지 않습니다. 이전 버전 바이너리의 인덱스 빌드는 완료되거나 중단될 때까지 여전히 마이그레이션 잠금(migration lock)을 유지할 수 있습니다. CI에서는 병합 기준점(merge-base) 바이너리를 확장과 비교하여 확인합니다. Quivr 업그레이드하기를 참조하세요.

• 릴리스 이미지 및 빌드 식별자. Release-please는 알파 릴리스 PR, 버전 및 변경 로그를 관리합니다. 릴리스를 게시하면 서명된 엔진과 퍼스트파티 플러그인 이미지가 GHCR에 생성되며, 여기에 서명된 SPDX 인벤토리와 취약점 검사가 포함됩니다. quivr --version, GET /v0/version, 시작 로그 및 프로세스 메트릭을 통해 빌드 정보를 확인할 수 있습니다. Quivr 배포 및 구성와 릴리스 보안를 참조하세요.

• 선언적 준수 사례(Declarative conformance cases): 일반적인 요구 사항을 기여하고 make conformance로 로컬에서 측정할 수 있습니다. 사례 형식 및 보고서. CI는 절대로 이 사례들을 실행하지 않습니다.

• 인증된 벡터 인덱스(Authenticated vector indexes): 선택적 weaviate_api_key를 사용하면 모든 인덱싱 요청에 베어러 키(bearer key)가 전송됩니다. 외부 인덱스를 사용할 때는 HTTPS를 사용하세요. 구성을 참조하세요.

• 아웃고잉 TLS (Outgoing TLS): Temporal, Weaviate, PostgreSQL, S3 및 플러그인에 대해 검증된 인증서와 구성 가능한 신뢰(trust)를 갖춘 아웃고잉 TLS가 제공됩니다. 인커밍 HTTPS는 사용자의 플랫폼에서 종료되므로 TLS 뒤에 Quivr 실행하기를 참조하세요.