SentrySearch

비디오 영상에 대한 의미론적 검색. 찾고 있는 것을 입력하면, 잘린 클립을 반환합니다.

[!IMPORTANT] 공식 소스: github.com/ssrajadh/sentrysearch는 SentrySearch의 유일한 공식 홈페이지입니다. 이 프로젝트를 재게시하거나 미러링하는 다른 사이트는 유지보수자와 관련이 없거나 보증되지 않습니다. 항상 이 저장소에서 다운로드하세요.

언어: 영어 · 简体中文

새로운: SentrySearch 코드베이스 둘러보기 영상

파이프라인:

SentrySearch (당신의 영상에서 이벤트 찾기)
SentryMerge (멀티캠 영상을 자동으로 잘라서 카메라 간 대상을 따라가는 하나의 비디오로 만들기)
SentryBlur (민감 정보 자동 블러 처리)

작동 방식

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`을 사용하거나 `.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.

Options:

--chunk-duration 30 — 청크당 시간(초)
--overlap 5 — 청크 간 중첩
--no-preprocess — 다운스케일링/프레임레이트 감소 생략 (원시 청크 전송)
--target-resolution 480 — 전처리를 위한 목표 높이(픽셀)
--target-fps 5 — 전처리를 위한 목표 프레임레이트
--no-skip-still — 시각적 변화가 없는 청크도 모두 포함
--backend local — Gemini 대신 로컬 모델 사용 (자세한 내용은 아래 참조)```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)보다 낮으면, 다듬기 전에 프롬프트가 표시됩니다:```
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 near-duplicates

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

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`가 적절한 기본값입니다.

`--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. 인덱스에 여러 개의 뚜렷한 "정상" 모드(주간 대 야간 대 차고)가 있을 때 가장 적합합니다.

세부 조정 옵션:

- `--against "<query>"` — 쿼리 *에 상대적인* 이상 점수 산정. `--against-mode within`(기본값)에서는 쿼리의 상위 일치 항목 중에서 이상치 순위를 매깁니다("보행자 클립 중 이상한 보행자"). `--against-mode global`에서는 쿼리와 일치하지만 나머지 인덱스와는 다른 클립을 찾습니다("이 유형의 드문 사건").
- `--dedupe 0.9` — 상위 순위 선택과 너무 유사한 결과 제거(기본값 코사인 유사도 0.9). 거의 중복된 프레임이 목록을 채우는 것을 방지합니다.
- `--exclude-baseline` — 인덱스에서 중심점에 가장 가까운 절반을 점수 산정 전에 제거. 반복적인 "지루한" 영상이 인덱스를 지배할 때 유용합니다.
- `-k, --neighbors 10` — `knn`/`lof`의 *k* 값.
- `--no-trim` — 클립을 쓰지 않고 순위 출력.

> **주의:** 통계적으로 이상하다고 흥미로운 것은 아닙니다. 센서 결함, 렌즈 플레어, 주로 주간 인덱스의 야간 프레임, 유일한 차고 클립은 모두 높은 순위를 차지합니다. `--exclude-baseline`과 `--dedupe`를 사용하여 노이즈를 필터링하거나, `--against`를 사용하여 주제별로 제한하세요.

### Qwen Cloud (Alibaba DashScope)

선택적 **qwen-cloud** 백엔드를 사용하여 [DashScope](https://www.alibabacloud.com/help/en/model-studio/qwen-api-via-dashscope) / Model Studio 멀티모달 임베딩을 활용합니다(기본 모델 `qwen3-vl-embedding`, `--dashscope-model` 또는 `DASHSCOPE_EMBEDDING_MODEL`로 재정의 가능):```bash
uv tool install ".[qwen-cloud]"
export DASHSCOPE_API_KEY=...
sentrysearch index /path/to/footage --backend qwen-cloud
sentrysearch search "your query" --backend qwen-cloud

비디오 업로드: 로컬 청크 파일은 API에서 사용하기 전에 공식 Python SDK가 DashScope에서 관리하는 임시 OSS로 전송됩니다 (HTTP API는 URL을 기대하며, SDK가 업로드를 처리합니다).

로컬 백엔드 (API 키 필요 없음)

Gemini API 대신 로컬 Qwen3-VL-Embedding 모델을 사용하여 인덱싱 및 검색합니다. 무료이며 비공개로 완전히 사용자 머신에서 실행됩니다. 최상의 검색 품질을 위해서는 Gemini 백엔드를 사용하세요 — 오프라인/비공개 검색이 필요할 때 로컬 8B 모델은 훌륭한 대안이며, 하드웨어가 8B를 지원할 수 없을 때 2B 모델이 대체 수단입니다.

모델은 하드웨어에서 자동 감지됩니다 — NVIDIA GPU 및 24 GB+ RAM의 Mac에서는 qwen8b, 더 작은 Mac 및 CPU 전용 시스템에서는 qwen2b가 사용됩니다. --model qwen2b 또는 --model qwen8b로 재정의할 수 있습니다. 하드웨어에 따라 설치를 선택하세요:

잘 작동하지 않음: Intel Mac 및 전용 GPU가 없는 머신. CPU에서 float32로 대체되어 실용적으로 사용하기에는 너무 느리고 메모리를 많이 소모합니다. 대신 Gemini API 백엔드 (기본값)를 사용하세요.

잘 모르겠다면? Mac에서는 ".[local]"을 사용하세요. NVIDIA에서는 ".[local-quantized]"를 사용하세요 — 4비트 양자화는 최소한의 품질 손실로 가장 넓은 범위의 NVIDIA 하드웨어에서 작동합니다. (bitsandbytes는 CUDA가 필요하며 Mac/MPS에서는 작동하지 않습니다.)

Python 버전: PyTorch 휠은 새로운 Python 릴리스를 뒤따르므로 로컬 백엔드는 Python 3.11 또는 3.12가 필요합니다. 기본 Python이 3.13+인 경우 관리형 3.12를 설치하고 도구 설치를 해당 버전에 고정하세요:```bash uv python install 3.12 uv tool install --python 3.12 ".[local]"

**Mac 전제 조건:** 시스템 FFmpeg을 설치하세요 (로컬 모델의 비디오 프로세서가 필요로 합니다 — Gemini 백엔드는 번들된 ffmpeg을 대신 사용합니다):```bash
brew install ffmpeg

--backend local로 인덱싱하고 검색하세요 — 추가 플래그가 필요하지 않습니다:```bash sentrysearch index /path/to/footage --backend local sentrysearch search "car running a red light"

검색 명령은 색인할 때 사용한 백엔드와 모델을 자동으로 감지합니다. 또한 `--model`을 약어로 사용할 수 있습니다 — 이는 `--backend local`을 의미합니다:```bash
sentrysearch index /path/to/footage --model qwen2b   # same as --backend local --model qwen2b
sentrysearch search "car running a red light"          # auto-detects local/qwen2b from index

Options:

--model qwen2b — 더 작은 모델, 품질은 낮지만 약 6GB 메모리만 필요 (전체 HuggingFace ID도 허용)
--quantize / --no-quantize — 4비트 양자화 강제 on/off (기본값: bitsandbytes 설치 여부에 따라 자동 감지)

참고:

첫 실행 시 모델을 다운로드합니다 (8B 약 16GB, 2B 약 4GB).
로컬 --rerank는 임베딩 모델 외에 별도의 Qwen3-VL Instruct 모델(Qwen/Qwen3-VL-8B-Instruct 또는 Qwen/Qwen3-VL-2B-Instruct)을 다운로드합니다.
서로 다른 백엔드와 모델의 임베딩은 호환되지 않습니다. 각 백엔드/모델 조합은 자체 격리된 인덱스를 가지므로 실수로 섞이지 않습니다. 인덱싱된 데이터가 없는 모델로 검색하면 실제로 사용된 모델이 무엇인지 알려줍니다.
속도는 GPU 코어 수에 따라 다릅니다 — 기본 M 시리즈 칩은 Pro/Max보다 느리지만 동일한 결과를 생성합니다.

로컬 모델이 빠른 이유

로컬 백엔드는 몇 가지 기술이 결합되어 빠르고 메모리 효율적으로 유지됩니다:

전처리로 청크가 모델에 도달하기 전에 크기를 줄입니다. 각 30초 청크는 임베딩 전에 ffmpeg를 통해 480p, 5fps로 다운스케일됩니다. 약 19MB의 블랙박스 청크가 약 1MB가 됩니다 — 모델이 처리해야 할 픽셀이 95% 감소합니다. 모델 추론 시간은 동영상 길이가 아닌 픽셀 수에 비례하므로, 이것이 가장 큰 속도 향상입니다.
낮은 프레임 샘플링. 비디오 프로세서는 청크당 최대 32프레임만 모델로 전송합니다(fps=1.0, max_frames=32). 30초 청크는 약 30프레임을 생성합니다 — 수백 개가 아닙니다.
MRL 차원 절단. Qwen3-VL-Embedding은 Matryoshka Representation Learning을 지원합니다. 각 임베딩의 처음 768개 차원만 유지하고 L2 정규화하여 ChromaDB에서 저장 공간과 거리 계산을 줄입니다.
자동 양자화. 제한된 VRAM의 NVIDIA GPU에서 8B 모델은 자동으로 4비트(bitsandbytes)로 로드되어 약 18GB에서 약 6-8GB로 줄어들며 품질 손실이 최소화됩니다. 4090(24GB)은 bf16 모델을 여유 있게 실행합니다.
정지 프레임 건너뛰기. 시각적 변화가 없는 청크(예: 주차된 자동차)는 샘플링된 프레임 간의 JPEG 파일 크기를 비교하여 감지되고 완전히 건너뛰며, 청크당 한 번의 전체 순방향 패스를 절약합니다.

이 모든 것을 통해 A100에서 청크당 약 2-5초, T4에서 약 3-8초가 예상됩니다. 4090에서 bf16의 8B 모델은 청크당 낮은 한 자릿수 초가 되어야 합니다.

Tesla 메타데이터 오버레이

트리밍된 클립에 속도, 위치 및 시간을 오버레이:```bash sentrysearch search "car cutting me off" --overlay

Tesla 대시캠 파일에 내장된 텔레메트리(속도, GPS)를 추출하여 HUD 오버레이를 렌더링합니다. 오버레이는 다음을 표시합니다:

- **상단 중앙:** 밝은 회색 카드에 속도와 MPH 레이블
- **카드 아래:** 날짜와 시간 (12시간제, 오전/오후)
- **좌측 상단:** 도시와 도로명 (역지오코딩 사용)

![tesla overlay](https://assets.kitploit.com/production/public/readmes/12784/6bacffb39f1503cd7f92f2326d60919b14d1bfcd6ee9b8244a9d1bfb4b26e58e.png)

요구 사항:

- Tesla 펌웨어 2025.44.25 이상, HW3+
- SEI 메타데이터는 주행 영상에만 존재합니다 (주차/센트리 모드 제외)
- 역지오코딩은 geopy를 통해 [OpenStreetMap의 Nominatim API](https://nominatim.openstreetmap.org/)를 사용합니다 (선택 사항)

Tesla 오버레이 지원으로 설치:```bash
uv tool install ".[tesla]"

geopy가 없어도 오버레이는 작동하지만 도시/도로 이름은 생략됩니다.

출처: teslamotors/dashcam

SentryMerge로 스티칭

SentryMerge는 SentrySearch 결과에서 하나의 이벤트에 대한 단일 크로스카메라 비디오를 자동으로 잘라내는 자매 도구입니다. sentrysearch search가 실행될 때마다 결과 목록을 ~/.sentrysearch/last_search.json에 캐시합니다; SentryMerge는 --last를 통해 이를 가져와 최상의 멀티카메라 클립 세트를 선택하고, VLM에 카메라별 서브초 가시성 범위를 요청한 후, 카메라 간에 대상을 따라가는 프레임 정확한 하나의 비디오로 스티칭합니다:```bash sentrysearch search "" sentrymerge --last # → merge.mp4

`--last`는 검색을 다시 실행하지 않고 작동합니다; `sentrymerge --query "..."`는 내부적으로 검색을 다시 실행합니다. 설치 지침, VLM 백엔드 옵션(Gemini / OpenAI / 로컬 Qwen) 및 Tesla가 아닌 대시캠을 위한 모듈식 cam-config 시스템에 대해서는 [SentryMerge README](https://github.com/ssrajadh/sentrymerge#readme)를 참조하세요.

### SentryBlur로 필터링

[SentryBlur](https://github.com/ssrajadh/sentryblur)은 로컬에서 얼굴, 번호판 및 자연어 기반 비디오 필터링을 위한 형제 도구입니다. `sentrysearch search`가 클립을 저장할 때마다 경로를 `~/.sentrysearch/last_clip.json`에 캐시합니다; SentryBlur은 `--last`를 통해 이를 읽어오므로, 검색 후 필터링은 두 개의 명령어로 경로 전달 없이 수행됩니다:```bash
sentrysearch search "car cuts me off"
sentryblur prompt --last "road signs"   # → match_<...>_blurred.mp4

sentryblur faces --last 및 sentryblur plates --last는 같은 방식으로 작동합니다. 빠른 CPU 감지를 위해 faces 또는 plates를 선택하세요. 임의의 객체(휴대폰 화면, 모니터, 명찰)에는 prompt "<text>"를 사용하세요. prompt는 NVIDIA GPU 또는 Apple Silicon이 필요합니다. 설치 지침 및 하드웨어 참고 사항은 SentryBlur README를 참조하세요.

인덱스 관리```bash

Show index info (files marked [missing] no longer exist on disk)

sentrysearch stats

Remove specific files by path substring

sentrysearch remove path/to/footage

Wipe the entire index

sentrysearch reset

#### 실패한 청크 및 재시도

재시도 후에도 청크를 임베딩할 수 없으면 SentrySearch는 이를 데드 레터 큐(DLQ)에 기록합니다(`~/.sentrysearch/dlq.json`). 그런 다음 나머지 영상 인덱싱을 계속합니다. 청크가 DLQ에 들어가는 일반적인 이유는 반복적인 일시적 API/백엔드 오류, 특정 파일에 대한 디코더 오류, 파일 누락, 메모리 부족 오류 등입니다. 파일 누락, 디코딩 오류, OOM과 같은 영구적으로 보이는 오류는 즉시 기록됩니다. 동일한 설정으로 동일한 청크를 재시도해도 도움이 되지 않을 가능성이 높기 때문입니다.

실패한 청크 확인:```bash
sentrysearch dlq list

다음 인덱스 실행 시 재시도하세요:```bash sentrysearch index /path/to/footage --retry-failed

재시도 없이 DLQ 비우기:```bash
sentrysearch dlq clear

기본적으로 이후 sentrysearch index 실행은 이미 DLQ에 있는 청크를 건너뛰므로 실패에 대해 반복적으로 비용을 지불하거나 기다리지 않습니다. 소스 문제를 해결하거나 모델/백엔드 설정을 변경하거나 메모리를 확보한 후에는 --retry-failed를 사용하세요.

캐시 및 상태 파일

SentrySearch는 ~/.sentrysearch/ 아래에 로컬 상태를 유지합니다:

상세 모드

두 명령에 --verbose를 추가하면 디버그 정보(임베딩 차원, API 응답 시간, 유사도 점수)를 볼 수 있습니다.

이것이 어떻게 가능한가?

Gemini Embedding 2와 Qwen3-VL-Embedding 모두 기본적으로 비디오를 임베딩할 수 있습니다. 원시 비디오 픽셀이 텍스트 쿼리와 동일한 벡터 공간으로 투영됩니다. 전사, 프레임 캡션, 텍스트 중간 단계가 없습니다. "빨간 트럭이 정지 표지판에 있음"과 같은 텍스트 쿼리는 벡터 수준에서 30초 비디오 클립과 직접 비교 가능합니다. 이것이 몇 시간 분량의 영상에 대해 1초 미만의 의미론적 검색을 실용적으로 만듭니다.

비용

Gemini

Gemini의 임베딩 API로 1시간 분량의 영상을 인덱싱하는 데 약 $2.84가 소요됩니다(기본 설정: 30초 청크, 5초 중첩):

1시간 = 3,600초의 비디오 = 모델이 처리하는 3,600프레임. 3,600프레임 × $0.00079 = ~$2.84/시간

Gemini API는 업로드된 비디오에서 파일의 실제 프레임 속도와 관계없이 초당 정확히 1프레임을 기본적으로 추출하고 토큰화합니다. 전처리 단계(ffmpeg를 통해 청크를 480p, 5fps로 축소)는 로컬/대역폭 최적화로, 페이로드 크기를 작게 유지하여 API 요청이 빠르고 시간 초과되지 않도록 합니다. 하지만 API가 처리하는 프레임 수는 변경하지 않습니다.

두 가지 내장 최적화 기능이 다양한 방식으로 비용 절감에 도움을 줍니다:

전처리 (기본적으로 켜짐) — 청크를 업로드 전에 480p, 5fps로 축소합니다. API는 어차피 1fps로 처리하므로 업로드 크기와 전송 시간만 줄어들고 청구되는 프레임 수는 줄어들지 않습니다. 주로 속도를 개선하고 요청 시간 초과를 방지합니다.
정지 프레임 건너뛰기 (기본적으로 켜짐) — 의미 있는 시각적 변화가 없는 청크(예: 주차된 자동차)를 완전히 건너뜁니다. 이는 실제 API 호출을 절약하고 비용을 직접적으로 줄입니다. 절감액은 영상 내용에 따라 다릅니다. 몇 시간의 유휴 시간이 있는 센트리 모드 녹화가 가장 큰 혜택을 보는 반면, 액션이 많은 주행 영상은 건너뛸 내용이 없을 수 있습니다.

검색 쿼리는 미미합니다(텍스트 임베딩만 해당).

Qwen Cloud (DashScope, Qwen3-VL-Embedding)

DashScope는 멀티모달 임베딩을 CNY/1,000 입력 토큰 단위로 모달리티별로 청구합니다. 기본 모델 qwen3-vl-embedding의 경우 Alibaba의 게시된 요금(아래 문서에서 지역 및 업데이트 확인)은 대략 다음과 같습니다:

텍스트 입력: 약 ¥0.0007 / 1k 입력 토큰
이미지/비디오 입력: 약 ¥0.0018 / 1k 입력 토큰

인덱싱은 비디오 청크(비디오 모달리티)를 보냅니다. 각 search/img 쿼리는 주로 텍스트 또는 이미지 토큰으로, 토큰당 비디오보다 저렴합니다. 실제 비용은 각 API 호출에 대해 DashScope가 반환하는 토큰 수(해상도, 지속 시간, DASHSCOPE_VIDEO_FPS와 같은 샘플링 등에 따라 다름)에 따라 달라집니다. Gemini의 게시된 USD/프레임 요율처럼 고정된 "영상 시간당 $"는 없습니다. 워크로드를 측정해야 합니다.

Alibaba는 또한 무료 토큰 허용량(예: 활성화 후 제한된 기간 동안 100만 토큰)을 문서화하고 있습니다. DashScope 멀티모달 임베딩 계량 및 청구 페이지와 Model Studio/청구 콘솔에서 확인하세요. 가격, 지역, 프로모션은 변경됩니다.

인덱싱 튜닝 (두 백엔드 모두)

다음 플래그는 Gemini 및 qwen-cloud 모두에 대한 청킹 및 전처리에 영향을 줍니다:

--chunk-duration / --overlap — 더 긴 청크와 더 적은 중첩 = 더 적은 API 호출 = 더 낮은 비용
--no-skip-still — 아무 일도 일어나지 않더라도 모든 청크를 임베딩
--target-resolution / --target-fps — 전처리 품질 조정
--no-preprocess — 원시 청크를 API에 전송

알려진 경고 (무해함)

로컬 백엔드는 인덱싱 및 검색 중에 경고를 출력할 수 있습니다. 이는 외관상의 문제이며 결과에 영향을 미치지 않습니다:

MPS: nonzero op is not natively supported — Apple Silicon에서 알려진 PyTorch 제한 사항입니다. 작업이 CPU로 대체되어 한 단계를 처리하고 나머지는 GPU에서 유지됩니다. 출력 품질에 영향 없음.
video_reader_backend torchcodec error, use torchvision as default — torchcodec이 macOS에서 호환되는 FFmpeg를 찾을 수 없습니다. 비디오 프로세서가 자동으로 torchvision으로 대체됩니다. 이는 예상된 동작이며 동일한 결과를 생성합니다.
You are sending unauthenticated requests to the HF Hub — 모델이 토큰 없이 Hugging Face에서 다운로드됩니다. 다운로드 속도가 약간 낮을 수 있지만 모델은 잘 로드됩니다. 귀찮다면 HF_TOKEN 환경 변수를 설정하여 이 메시지를 없앨 수 있습니다.

한계 및 향후 작업

정지 프레임 감지는 휴리스틱 기반 — 샘플링된 프레임 간의 JPEG 파일 크기 비교를 사용합니다. 미세한 움직임이 있는 청크를 가끔 건너뛰거나 실제로 정적인 청크를 임베딩할 수 있습니다. 모든 청크를 인덱싱해야 하는 경우 --no-skip-still로 비활성화하세요.
검색 품질은 청크 경계에 따라 달라짐 — 이벤트가 두 청크에 걸쳐 있는 경우 중첩 창이 도움이 되지만 완벽하지는 않습니다. 더 스마트한 청킹(예: 장면 감지)이 이를 개선할 수 있습니다.
Gemini Embedding 2는 미리보기 상태 — API 동작 및 가격이 변경될 수 있습니다.

호환성

이는 Tesla 센트리 모드뿐만 아니라 .mp4 및 .mov 영상과 함께 작동합니다. 디렉토리 스캐너는 폴더 구조에 관계없이 두 파일 형식을 재귀적으로 찾습니다.

요구 사항

Python 3.11+
PATH에 ffmpeg가 있거나 imageio-ffmpeg를 통해 번들 ffmpeg 사용 (기본적으로 설치됨)
Gemini 백엔드: Gemini API 키 (무료로 받기)
로컬 백엔드:
- CUDA 또는 Apple Metal을 지원하는 GPU (VRAM/RAM 요구 사항은 하드웨어 표 참조)
- macOS: brew install ffmpeg (비디오 디코더에 필요)
- Linux/Windows: 추가 시스템 종속성 없음

Apple Silicon, 24 GB+ RAM	`uv tool install ".[local]"`	qwen8b	MPS를 통한 전체 float16
Apple Silicon, 16 GB RAM	`uv tool install ".[local]"`	qwen2b	8B는 비용이 맞지 않음; 2B는 약 6 GB 사용
Apple Silicon, 8 GB RAM	`uv tool install ".[local]"`	qwen2b	빡빡함 — 로드 시 스왑 발생 가능; 대신 Gemini API 권장
NVIDIA, 18 GB+ VRAM	`uv tool install ".[local]"`	qwen8b	전체 bf16 정밀도 (Linux/Windows에서 CUDA 휠 자동 다운로드)
NVIDIA, 8–16 GB VRAM	`uv tool install ".[local-quantized]"`	qwen8b	4비트 양자화 (~6–8 GB)

`db/`	`sentrysearch index`	임베딩된 영상의 ChromaDB 벡터 인덱스.	예, 하지만 인덱스가 삭제됩니다. 검색 전에 `sentrysearch index <dir>`을 다시 실행하세요.
`.env`	`sentrysearch init`	기본 백엔드용 Gemini API 키를 저장합니다.	예, 하지만 Gemini 기반 명령을 실행하면 키를 다시 구성하라는 메시지가 표시됩니다.
`dlq.json`	실패한 `sentrysearch index` 청크	`sentrysearch dlq list`로 검사하고 `--retry-failed`로 재시도하는 데드 레터 큐.	예. 삭제하면 실패한 청크를 잊어버리므로 이후 인덱스 실행 시 새 작업으로 다시 시도할 수 있습니다.
`last_clip.json`	클립을 저장하는 명령어 (`search`, `img`, `highlights`, `overlay`)	SentryBlur가 `sentryblur ... --last`로 가장 최근 저장된 클립을 사용할 수 있게 합니다.	예. `--last` 핸드오프만 손실됩니다. 저장된 MP4 파일은 삭제되지 않습니다.
`last_search.json`	`sentrysearch search`, `img`, `highlights`	SentryMerge가 `sentrymerge --last`로 가장 최근 결과 목록을 사용할 수 있게 합니다.	예. `--last` 핸드오프만 손실됩니다. 검색 인덱스는 변경되지 않습니다.
`history`	`sentrysearch shell`	대화형 셸의 Readline 명령 기록.	예. 셸이 다음에 빈 기록으로 시작됩니다.

sentrysearch

인기