SentrySearch 딥다이브
— "빨간 트럭이 정지신호 무시한 장면" 한 문장으로 영상을 찾는다

1프로젝트 한줄 요약

SentrySearch는 "찾고 싶은 장면을 자연어로 입력하면 영상에서 해당 구간만 잘라 클립으로 돌려주는" 시맨틱 영상 검색 CLI다. README 한 줄 설명 그대로 — "Type what you're looking for, get a trimmed clip back." 영상을 텍스트로 받아쓰는 STT나 프레임 캡셔닝 같은 중간 단계 없이, 영상 픽셀을 직접 벡터로 만들어 검색어 벡터와 비교한다.

2왜 주목받는가

기존 영상 검색 방식 비교

여기에 README가 강조하는 차별점이 더 있다. sentrysearch highlights로 이상 장면(anomaly)을 자동 추출하고, 정지 프레임을 감지해 건너뛰며, 거의 같은 결과를 자동 중복 제거(dedupe)한다. Tesla 메타데이터(속도·위치·시간) 오버레이, 멀티카메라 합성(SentryMerge)·얼굴 가림(SentryBlur) 연계까지 묶여 있다.

3기술 스택 전체 지도

언어 구성

임베딩 백엔드 (3종 선택)

벡터 DB · 검색

영상 처리 / 로컬 추론

4아키텍처 심화 분석

전체 파이프라인 구조도

핵심 설계 패턴 ①: 멀티모달 공동 임베딩 공간

핵심 설계 패턴 ②: 청킹 + 오버랩

한 시간짜리 영상을 통째로 임베딩할 수 없다. 모델 입력 한계도 있고 비용도 길이에 비례한다. 그래서 30초 단위로 자르되 5초씩 겹치게 자른다. 이벤트가 청크 경계에 걸쳐 어느 쪽에도 안 잡히는 일을 막는다.

핵심 설계 패턴 ③: 백엔드 추상화 (Strategy 패턴)

임베딩 생성을 하나의 인터페이스 뒤로 숨겨, --backend 플래그만 바꾸면 Gemini / DashScope / 로컬 Qwen이 갈아끼워진다. 인덱싱 코드와 검색 코드는 백엔드가 무엇인지 몰라도 된다. 민감 영상은 로컬, 공개 영상은 클라우드를 인덱스 단위로 선택할 수 있는 유연성이 여기서 나온다.

핵심 설계 패턴 ④: 정지 프레임 스킵 (비용 최적화)

대시캠·주차 영상은 차가 멈춰 화면이 거의 안 변하는 구간이 많다. SentrySearch는 JPEG 파일 크기 비교로 "이 구간은 정적"이라 판단하고 그 청크를 통째로 건너뛴다. 임베딩 호출 수 자체가 줄어 비용이 내려간다.

5디렉토리 구조 해부

핵심은 pyproject.toml이 extras로 설치 변형을 정의한다는 점이다. .[local](로컬 Qwen), .[local-quantized](4-bit NVIDIA), .[tesla](메타데이터 오버레이) — 무거운 의존성(PyTorch, bitsandbytes, geopy)을 필요한 사람만 선택 설치하게 분리했다. 초보자가 "왜 설치가 무거운가"를 배우기에 좋은 실전 예시다.

6학습 포인트 (기술별)

A. 멀티모달 임베딩과 벡터 검색

배울 것: 텍스트·영상을 같은 공간에 넣는 임베딩의 원리, 코사인 유사도로 의미 거리를 재는 법, 임계값(0.41)으로 "확신 없음"을 거르는 설계. 이 레포는 RAG·시맨틱 검색의 핵심 개념을 영상이라는 직관적 대상으로 보여준다.

B. 벡터 DB 다루기 (ChromaDB)

배울 것: 임베딩을 저장하고 "가장 비슷한 것"을 빠르게 찾는 벡터 DB의 사용법. MRL 차원 절단으로 768차원 통일 — 백엔드마다 다른 출력 차원을 한 공간에 맞추는 실전 트릭.

C. 청킹 + 오버랩 전략

배울 것: 긴 데이터를 조각내되 경계 손실을 막는 표준 패턴. 영상의 30초/5초 오버랩은 LLM에 긴 문서를 넣을 때의 청킹과 동일한 발상이다. 한 번 이해하면 모든 검색·RAG 파이프라인에 재활용된다.

D. 백엔드 추상화 (클라우드 vs 로컬)

배울 것: 같은 인터페이스 뒤에 Gemini/DashScope/로컬 Qwen을 갈아끼우는 Strategy 패턴. 프라이버시·비용·정확도의 트레이드오프를 코드 구조로 푸는 법을 배운다.

E. 현대적 파이썬 패키징 (uv + pyproject.toml)

배울 것: setup.py 없이 pyproject.toml 하나로 빌드·의존성·CLI 엔트리포인트·extras를 모두 선언하는 법. uv tool install로 CLI를 격리 환경에 까는 pipx 대안 워크플로.

F. 비용·성능 엔지니어링

배울 것: 480p/5fps 다운스케일, 정지 프레임 스킵(JPEG 크기 비교), 결과 dedupe 등 "같은 결과, 더 적은 비용"을 위한 실전 최적화. 프레임 단위 과금 모델을 직접 계산해보며 클라우드 AI 비용 감각을 기른다.

7하드웨어 / 시스템 요구사항

로컬 모드 — GPU 메모리별 자동 선택

8직접 해볼 수 있는 실습 과제

# 1. 클론 후 설치 (uv 필요) — Gemini 백엔드 기본
#    DashScope 백엔드 사용 시: uv tool install ".[qwen-cloud]"
git clone https://github.com/ssrajadh/sentrysearch
cd sentrysearch && uv tool install .

# 2. 환경 초기화 (.env에 API 키 입력)
sentrysearch init

# 3. 짧은 드라이빙 영상 인덱싱 + 검색
sentrysearch index ./clips --verbose
sentrysearch search "빨간 트럭" --results 3
sentrysearch stats

# app.py — SentrySearch를 서브프로세스/모듈로 호출
from fastapi import FastAPI
app = FastAPI()

@app.get("/search")
def search(q: str):
    # sentrysearch search "{q}" 결과를 JSON으로 반환
    return {"query": q, "clips": run_search(q)}

9관련 기술 심화 학습 로드맵

1주차: 임베딩과 벡터 검색의 기초

2주차: SentrySearch 분해

3주차: 백엔드와 프라이버시

4주차: 확장과 응용

10핵심 키워드 사전

11참고 링크

• GitHub 레포 — ssrajadh/sentrysearch
• README (영문) — 비용/하드웨어/CLI 표
• pyproject.toml — 의존성 & extras 정의
• Google Gemini Embedding 문서
• ChromaDB 공식 문서
• Qwen (Alibaba) 모델 소개
• uv 패키지 매니저 문서
• GIGAZINE — SentrySearch 소개 기사
• DEV.to — 동작 원리 해설
• Matryoshka Representation Learning (MRL) 개념