SentrySearch

映像フッテージをセマンティック検索。探しているものを入力すると、トリミングされたクリップが返されます。

[!IMPORTANT] 公式ソース: github.com/ssrajadh/sentrysearch は SentrySearch の唯一の公式ホームです。このプロジェクトを転載またはミラーリングする他のサイトはメンテナと提携しておらず、承認もされていません。必ずこのリポジトリからダウンロードしてください。

言語: 英語 · 简体中文

新着: SentrySearch コードベースウォークスルー動画

パイプライン:

1. SentrySearch (映像内のイベントを発見)
2. SentryMerge (マルチカメラ映像を被写体を追跡する単一の動画に自動カット)
3. SentryBlur (機密情報を自動編集)

目次

• 動作の仕組み
• はじめに
• 使い方
  • 初期化
  • 映像のインデックス化
  • 検索
  • 画像による検索
  • ハイライト
  • Qwen Cloud (Alibaba DashScope)
  • ローカルバックエンド (APIキー不要)
  • ローカルモデルが高速な理由
  • Tesla メタデータオーバーレイ
  • SentryMerge で結合
  • SentryBlur で編集
  • インデックスの管理
    • 失敗したチャンクと再試行
    • キャッシュと状態ファイル
  • 詳細モード
• なぜこれが可能なのか
• コスト
• 既知の警告 (無害)
• 制限事項と今後の課題
• 互換性
• 要件

動作の仕組み

SentrySearch は動画を重複するチャンクに分割し、各チャンクを Google の Gemini Embedding API、Alibaba DashScope (qwen-cloud)、またはローカルの Qwen3-VL モデルを使用して動画として埋め込み、ベクトルをローカルの ChromaDB データベースに保存します。検索時には、テキストクエリ (または画像、画像による検索 を参照) が同じベクトル空間に埋め込まれ、保存された動画埋め込みと照合されます。最上位の一致結果が元のファイルから自動的にトリミングされ、クリップとして保存されます。

はじめに

1. 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"

2. クローンしてインストール:```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に書き込み、テストエンベディングで検証します。

4. 映像をインデックス化してください:```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からキーを手動で追加できます。

使い方

Init```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 — 1チャンクあたりの秒数
• --overlap 5 — チャンク間のオーバーラップ
• --no-preprocess — ダウンスケール/フレームレート低減をスキップ（生のチャンクを送信）
• --target-resolution 480 — 前処理のターゲット高さ（ピクセル）
• --target-fps 5 — 前処理のターゲットフレームレート
• --no-skip-still — 視覚的変化がないチャンクもすべて埋め込む
• --backend local — Geminiの代わりにローカルモデルを使用（詳細は以下）

Search```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 (信頼度カットオフを調整), --save-top N (最良一致だけでなく上位N個のクリップを保存), --dedupe (より高ランクの選択と類似しすぎる結果を削除; 同じイベントのほぼ重複するチャンクがリストを埋めるのを防止), --rerank (トリム前にVLMに返された候補を再ランク付けさせる)。バックエンドとモデルはインデックスから自動検出されます — 上書きする場合のみ --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 は検索を失敗させる代わりに、埋め込みランク付けされた結果を保持します。

### 画像による検索

クエリとして参照画像を使用します — 言葉でシーンを説明するのが難しい場合（特定の車のスクリーンショット、別のビデオの参照フレームなど）、"find clips that look like this" のに便利です。```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 ...

Scoring methods (`--method`):

- **`knn`** (デフォルト) — チャンクの *k* 最近傍への平均コサイン距離。ロバストで、近い双子のないクリップを表面化します。
- **`centroid`** — インデックス平均からの距離。最も低コストで、過小評価されたものに偏ります。
- **`lof`** — 局所外れ値因子（Local Outlier Factor）。インデックスに複数の異なる「正常」モード（昼 vs 夜 vs ガレージ）がある場合に最適です。

洗練オプション:

- `--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モデルは堅実な代替手段であり、2Bモデルはハードウェアが8Bをサポートできない場合のフォールバックです。

モデルはハードウェアから自動検出されます。NVIDIA GPUおよび24GB以上の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のwheelは新しい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"

search コマンドは、インデックス作成時に使用したバックエンドとモデルを自動検出します。省略形として `--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 — smaller model, lower quality but only ~6 GB memory (also accepts full HuggingFace IDs)
• --quantize / --no-quantize — force 4-bit quantization on or off (default: auto-detect based on whether bitsandbytes is installed)

Notes:

• First run downloads the model (~16 GB for 8B, ~4 GB for 2B).
• Local --rerank downloads a separate Qwen3-VL Instruct model (Qwen/Qwen3-VL-8B-Instruct or Qwen/Qwen3-VL-2B-Instruct) in addition to the embedding model.
• Embeddings from different backends and models are not compatible. Each backend/model combination gets its own isolated index, so they can't accidentally mix. If you search with a model that has no indexed data, you'll be told which model was actually used.
• Speed varies by GPU core count — base M-series chips are slower than Pro/Max but produce identical results.

Why the local model is fast

The local backend stays fast and memory-efficient through a few techniques that compound:

• Preprocessing shrinks chunks before they hit the model. Each 30s chunk is downscaled to 480p at 5fps via ffmpeg before embedding. A ~19 MB dashcam chunk becomes ~1 MB — a 95% reduction in pixels the model has to process. Model inference time scales with pixel count, not video duration, so this is the single biggest speedup.
• Low frame sampling. The video processor sends at most 32 frames per chunk to the model (fps=1.0, max_frames=32). A 30-second chunk produces ~30 frames — not hundreds.
• MRL dimension truncation. Qwen3-VL-Embedding supports Matryoshka Representation Learning. Only the first 768 dimensions of each embedding are kept and L2-normalized, reducing storage and distance computation in ChromaDB.
• Auto-quantization. On NVIDIA GPUs with limited VRAM, the 8B model is automatically loaded in 4-bit (bitsandbytes) — dropping from ~18 GB to ~6-8 GB with minimal quality loss. A 4090 (24 GB) runs the full bf16 model with headroom to spare.
• Still-frame skipping. Chunks with no meaningful visual change (e.g. a parked car) are detected by comparing JPEG file sizes across sampled frames and skipped entirely — saving a full forward pass per chunk.

With all of this, expect ~2-5s per chunk on an A100 and ~3-8s on a T4. On a 4090, the 8B model in bf16 should be in the low single digits per chunk.

Tesla Metadata Overlay

Burn speed, location, and time onto trimmed clips:Options:

• --model qwen2b — より小さいモデル、品質は低いが約6GBのメモリで動作（フルHuggingFace IDも受け付け）
• --quantize / --no-quantize — 4ビット量子化を強制的にオン/オフ（デフォルト：bitsandbytesがインストールされているかどうかを自動検出）

Notes:

• 初回実行時にモデルをダウンロード（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ファイルサイズを比較することで検出され、完全にスキップされます。これにより、チャンクごとに1回のフォワードパスが節約されます。

これらすべてにより、A100ではチャンクあたり約2〜5秒、T4では約3〜8秒が期待できます。4090では、bf16の8Bモデルでチャンクあたり低い一桁台になるはずです。

Teslaメタデータオーバーレイ

トリミングされたクリップに速度、位置、時間を焼き付けます。```bash sentrysearch search "car cutting me off" --overlay

Teslaのダッシュカムファイルに埋め込まれたテレメトリ（速度、GPS）を抽出し、HUDオーバーレイをレンダリングします。オーバーレイには以下が表示されます：

- **上部中央：** 薄いグレーのカードに速度とMPHラベル
- **カードの下：** 日付と時刻（12時間制、AM/PM）
- **左上：** 市区町村と道路名（逆ジオコーディングによる）

![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の結果から1つのイベントに対する全カメラの動画を自動カットする兄弟ツールです。sentrysearch searchが実行されるたびに、結果リストが~/.sentrysearch/last_search.jsonにキャッシュされます。SentryMergeは--last経由でそれを取得し、最適なマルチカメラクリップセットを選択し、VLMにカメラごとのサブ秒単位の可視範囲を問い合わせ、カメラ間で被写体を追跡する1つのフレーム精度の動画にステッチします:```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` 経由でそれを取得するため、検索→編集は 2 つのコマンドで完了し、パスを渡す必要はありません。```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はそれを`~/.sentrysearch/dlq.json`のデッドレターキュー（DLQ）に記録し、残りの映像のインデックス作成を続行します。チャンクが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秒の動画クリップとベクトルレベルで直接比較できます。これにより、数時間の映像に対するサブ秒の意味検索が実用的になります。

コスト

Gemini

Geminiの埋め込みAPIを使用した1時間の映像のインデックス作成にかかるコストは約$2.84です（デフォルト設定：30秒チャンク、5秒オーバーラップ）：

1時間 = 3,600秒の動画 = モデルによって処理される3,600フレーム。 3,600フレーム × $0.00079 = ~$2.84/時間

Gemini APIは、アップロードされた動画からファイルの実際のフレームレートに関係なく、1秒あたり正確に1フレームを抽出しトークン化します。前処理ステップ（ffmpegを介してチャンクを480p、5fpsにダウンスケールする）は、ローカル/帯域幅の最適化です。ペイロードサイズを小さく保つことでAPIリクエストが高速になりタイムアウトしなくなりますが、APIが処理するフレーム数は変わりません。

2つの組み込み最適化が異なる方法でコスト削減に役立ちます：

• 前処理（デフォルトでオン）— チャンクはアップロード前に480p、5fpsにダウンスケールされます。APIは常に1fpsで処理するため、これによりアップロードサイズと転送時間のみが削減され、課金されるフレーム数は変わりません。主に速度を向上させ、リクエストのタイムアウトを防ぎます。
• 静止フレームスキップ（デフォルトでオン）— 意味のある視覚的変化がないチャンク（例：駐車中の車）は完全にスキップされます。これにより実際のAPI呼び出しが節約され、直接コストが削減されます。節約額は映像に依存します。何時間もアイドル状態のセントリーモード録画が最も効果的ですが、アクション満載の運転映像ではスキップするものが何もない場合があります。

検索クエリはごくわずかです（テキスト埋め込みのみ）。

Qwen Cloud (DashScope, Qwen3-VL-Embedding)

DashScopeはマルチモーダル埋め込みを1,000入力トークンあたりの人民元で、モダリティごとに請求します。デフォルトモデル qwen3-vl-embedding の場合、Alibabaの公開レート（お住まいの地域とアップデートについては以下のドキュメントを確認してください）は次のようなものです：

• テキスト入力: 1k入力トークンあたり約 ¥0.0007
• 画像/動画入力: 1k入力トークンあたり約 ¥0.0018

インデックス作成は動画チャンク（動画モダリティ）を送信します。各 search / img クエリは主にテキストまたは画像トークンであり、動画よりもトークン単価が安くなります。実際のコストは、各API呼び出しに対するDashScopeが返すトークン数（解像度、持続時間、DASHSCOPE_VIDEO_FPS などのサンプリング設定に依存）です。Geminiの公開されている1フレームあたりのUSDレートのように、ワークロードを測定せずに「映像1時間あたりの料金」を固定することはできません。

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の制限。操作は1ステップだけ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 で無効にします。
• 検索品質はチャンク境界に依存 — イベントが2つのチャンクにまたがる場合、オーバーラップウィンドウが役立ちますが完璧ではありません。よりスマートなチャンク分割（例：シーン検出）により改善できる可能性があります。
• Gemini Embedding 2 はプレビュー版 — APIの動作と価格は変更される可能性があります。

互換性

これはTesla Sentry Modeだけでなく、.mp4 および .mov の映像でも動作します。ディレクトリスキャナーはフォルダ構造に関係なく、両方のファイルタイプを再帰的に検出します。

必要条件

• Python 3.11以上
• ffmpeg がPATHに存在するか、imageio-ffmpeg 経由でバンドルされたffmpegを使用（デフォルトでインストール済み）
• Geminiバックエンド: Gemini APIキー（無料で取得）
• ローカルバックエンド:
  • CUDAまたはApple Metal対応GPU（VRAM/RAM要件はハードウェアテーブルを参照）
  • macOS: brew install ffmpeg（ビデオデコーダに必要）
  • Linux/Windows: 追加のシステム依存関係は不要