SentrySearch

비디오 영상에 대한 시맨틱 검색. 찾고 있는 것을 입력하면 잘라낸 클립을 돌려받습니다.

[!IMPORTANT] 공식 소스: github.com/ssrajadh/sentrysearch가 SentrySearch의 유일한 공식 홈입니다. 이 프로젝트를 재게시하거나 미러링하는 다른 사이트는 유지관리자와 제휴하거나 승인받지 않았으므로, 항상 이 저장소에서 다운로드하세요.

언어: English · 简体中文

새로운 기능: Apple Silicon용 MLX 백엔드: 로컬 2B 모델을 동일한 정확도로 절반 이하의 메모리에서 두 배 빠르게 실행합니다

작동 방식

SentrySearch는 비디오를 겹치는 청크로 분할하고, 각 청크를 Google의 Gemini Embedding API, Alibaba DashScope(qwen-cloud), 또는 로컬 Qwen3-VL 모델을 사용해 비디오로 임베딩한 뒤, 벡터를 로컬 ChromaDB 데이터베이스에 저장합니다. 검색할 때 텍스트 쿼리(또는 이미지, 이미지로 검색 참조)가 동일한 벡터 공간에 임베딩되어 저장된 비디오 임베딩과 매칭됩니다. 최상위 매치는 원본 파일에서 자동으로 잘라내어 클립으로 저장됩니다.

시작하기

uv를 설치합니다 (아직 없다면):

macOS/Linux:```bash curl -LsSf https://astral.sh/uv/install.sh | sh

**Windows:**```powershell
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

클론 및 설치:```bash git clone https://github.com/ssrajadh/sentrysearch.git cd sentrysearch uv tool install .

> **Python 3.11 또는 3.12가 필요합니다** (PyTorch 휠은 아직 3.13+를 지원하지 않습니다). 기본 Python이 더 최신 버전이라면, 관리되는 3.12를 설치하고 도구 설치 시 버전을 고정하세요:
> ```bash
> uv python install 3.12
> uv tool install --python 3.12 .
> ```

3. API 키를 설정하세요 (또는 [대신 로컬 모델을 사용하세요](#local-backend-no-api-key-needed)) — **기본 Gemini 백엔드에서만 필요합니다**; `--backend local`, `--backend mlx`, 또는 `.env`에 `DASHSCOPE_API_KEY`를 설정한 `--backend qwen-cloud`를 사용한다면 건너뛰세요.```bash
sentrysearch init

Gemini API 키를 입력하라는 메시지가 표시되면 .env에 기록하고 테스트 임베딩으로 검증합니다.

영상 자료를 인덱싱합니다:```bash sentrysearch index /path/to/footage

5. 검색:```bash
sentrysearch search "red truck running a stop sign"

ffmpeg는 비디오 청킹 및 트리밍에 필요합니다. 시스템 전역에 설치되어 있지 않다면, 번들로 제공되는 imageio-ffmpeg가 자동으로 사용됩니다.

수동 설정: sentrysearch init을 사용하지 않으려면, .env.example을 .env로 복사하고 aistudio.google.com/apikey에서 발급받은 키를 직접 추가하면 됩니다.

사용법

초기화```bash

$ sentrysearch init Enter your Gemini API key (get one at https://aistudio.google.com/apikey): **** Validating API key... Setup complete. You're ready to go — run sentrysearch index <directory> to get started.

키가 이미 구성되어 있으면 덮어쓸지 여부를 묻는 메시지가 표시됩니다.

> **팁:** 예상치 못한 과지출을 방지하려면 [aistudio.google.com/billing](https://aistudio.google.com/billing)에서 지출 한도를 설정하세요.

### 영상 인덱싱```bash
$ sentrysearch index /path/to/video/footage
Indexing file 1/3: front_2024-01-15_14-30.mp4 [chunk 1/4]
Indexing file 1/3: front_2024-01-15_14-30.mp4 [chunk 2/4]
...
Indexed 12 new chunks from 3 files. Total: 12 chunks from 3 files.

옵션:

--chunk-duration 30 — 청크당 초
--overlap 5 — 청크 간 겹침
--no-preprocess — 다운스케일링/프레임 레이트 감소 건너뛰기 (원본 청크 전송)
--target-resolution 480 — 전처리를 위한 목표 높이(픽셀)
--target-fps 5 — 전처리를 위한 목표 프레임 레이트
--no-skip-still — 시각적 변화가 없는 청크도 포함하여 모든 청크 임베딩
--rpm 10 — 클라우드 API에 대한 분당 요청 수 제한 (자세한 내용은 아래)
--backend local — Gemini 대신 로컬 모델 사용 (자세한 내용은 아래)
--backend mlx — Apple Silicon에서 MLX를 통해 로컬 모델 사용, local보다 빠르고 가벼움 (자세한 내용은 아래)

검색```bash

$ sentrysearch search "red truck running a stop sign" #1 [0.87] front_2024-01-15_14-30.mp4 @ 02:15-02:45 #2 [0.74] left_2024-01-15_14-30.mp4 @ 02:10-02:40 #3 [0.61] front_2024-01-20_09-15.mp4 @ 00:30-01:00

Saved clip: ./match_front_2024-01-15_14-30_02m15s-02m45s.mp4

최상의 결과의 유사도 점수가 신뢰 임계값(기본값 0.41, `--backend mlx`에서는 0.35) 미만이면, 트리밍 전에 프롬프트가 표시됩니다:```
No confident match found (best score: 0.28). Show results anyway? [y/N]:

--no-trim을 사용하면 낮은 신뢰도의 결과가 프롬프트 대신 참고 사항과 함께 표시됩니다.

옵션: --results N, --output-dir DIR, 자동 트리밍을 건너뛰는 --no-trim, 신뢰도 컷오프를 조정하는 --threshold 0.5, 최적의 일치 항목 하나만이 아니라 상위 N개의 클립을 저장하는 --save-top N, 결과가 더 높은 순위의 선택 항목과 얼마나 유사할 수 있는지(그 이상이면 제외됨)를 설정하는 --dedupe(기본적으로 켜져 있어 같은 순간의 겹치는 청크가 목록을 채우지 않음), 그리고 트리밍 전에 VLM에게 반환된 후보들의 순위를 다시 매기도록 요청하는 --rerank가 있습니다. 백엔드와 모델은 인덱스에서 자동 감지됩니다 — 재정의하려면 --backend 또는 --model을 전달하세요.```bash

Save top 5 clips, dropping only near-identical chunks

sentrysearch search "red truck" --save-top 5 --dedupe 0.95

Re-rank the top 10 embedding matches with a VLM before trimming

sentrysearch search "pedestrian crossing behind the car" --rerank --results 10

`--dedupe` 값은 코사인 유사도 상한(0–1)입니다. 이미 유지된 더 높은 순위의 결과와의 유사도가 이 값을 초과하는 결과는 제거됩니다. 값이 낮을수록 더 엄격합니다: `0.8`은 결과가 매우 뚜렷해야 함을 요구하고, `0.95`는 거의 동일한 청크만 제거합니다. 기본값은 `0.9`이며, 모든 결과를 유지하려면 `--dedupe 1`을 전달하세요. 검색은 중복 제거 시 추가 후보를 가져오므로, 요청한 개수만큼의 결과를 여전히 얻을 수 있습니다.

`--rerank`는 반환된 각 후보 클립을 추출하여 쿼리와 함께 VLM에 전송하고, 시각적으로 일치할 가능성이 높은 결과를 임베딩 전용 결과보다 앞에 정렬합니다. Gemini 및 qwen-cloud 검색은 재순위화에 Gemini 2.5 Flash를 사용하고, 로컬 검색은 로컬 Qwen3-VL Instruct 재순위화 모델을 사용합니다. 재순위화를 실행할 수 없거나 후보의 점수를 매길 수 없는 경우, SentrySearch는 검색을 실패시키는 대신 임베딩 순위 결과를 유지합니다.

### 이미지로 검색

참조 이미지를 쿼리로 사용하세요 — 장면을 말로 설명하기 어려울 때 "이것과 비슷하게 생긴 클립 찾기"에 유용합니다(특정 자동차의 스크린샷, 다른 비디오의 참조 프레임 등).```bash
$ sentrysearch img ~/Downloads/image.jpg
  #1 [0.72] 2026-03-12_10-44-17-left_repeater.mp4 @ 00:00-00:30
  #2 [0.69] 2026-03-12_10-44-17-left_repeater.mp4 @ 00:25-00:55
  #3 [0.67] 2026-02-12_20-02-15-front.mp4 @ 00:00-00:18

Saved clip: ./match_2026-03-12_10-44-17-left_repeater_00m00s-00m30s.mp4

이미지는 인덱싱된 비디오 청크와 동일한 벡터 공간에 임베딩되며 코사인 유사도로 순위가 매겨집니다. 이미지 검색은 --results, --threshold, --save-top, --dedupe, --overlay, --no-trim, --backend, --model을 지원합니다.

지원 형식: Gemini 백엔드에서는 JPG, PNG, WEBP, GIF, HEIC/HEIF이며, 로컬 백엔드는 추가로 PIL이 디코딩할 수 있는 모든 형식(BMP, TIFF 등)을 허용합니다.

참고: 이미지 검색은 시각적으로 유사한 일치 항목을 반환하며, 반드시 동일한 객체는 아닙니다. 빨간 세단을 쿼리하면 비슷한 형태의 다른 빨간 세단이 나타날 수 있으니 기대치를 적절히 조정하세요.

하이라이트

무엇을 검색해야 할지 모르겠다면? sentrysearch highlights는 인덱스에서 가장 이상치에 가까운 클립, 즉 임베딩이 다른 모든 것과 멀리 떨어져 있는 청크의 순위를 매기고 자동으로 트리밍합니다. 새로 확보한 영상 소재를 훑어볼 때 유용합니다.```bash $ sentrysearch highlights -n 3 #1 [0.165] 2026-02-12_20-02-15-back.mp4 @ 00:00-00:18 #2 [0.163] 2026-02-12_20-02-15-right_repeater.mp4 @ 00:00-00:18 #3 [0.149] 2026-02-12_20-02-15-front.mp4 @ 00:00-00:18 ...

스코어링 메서드 (`--method`):

- **`knn`** (기본값) — 청크의 *k*개 최근접 이웃까지의 평균 코사인 거리. 견고하며, 근접 쌍둥이가 없는 클립을 드러낸다.
- **`centroid`** — 인덱스 평균으로부터의 거리. 가장 저렴하지만, 과소 대표된 대상 쪽으로 편향된다.
- **`lof`** — Local Outlier Factor. 인덱스에 여러 개의 뚜렷한 "정상" 모드(주간 vs. 야간 vs. 차고)가 있을 때 가장 적합하다.

정제 옵션:

sentrysearch

인기