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

**ويندوز:**```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 qwen-cloud` مع `DASHSCOPE_API_KEY` في `.env`.```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 — تضمين جميع الأجزاء، حتى تلك التي لا يوجد بها تغيير بصري
--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 بنتائج مرتبة بالتضمين بدلاً من فشل البحث.

### البحث بالصورة

استخدم صورة مرجعية كاستعلام — مفيد لـ "البحث عن مقاطع تبدو هكذا" عندما يكون وصف المشهد بالكلمات صعبًا (لقطة شاشة لسيارة معينة، إطار مرجعي من فيديو آخر، إلخ).```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.

الصيغ المدعومة: JPG وPNG وWEBP وGIF وHEIC/HEIF على الواجهة الخلفية Gemini؛ بالإضافة إلى ذلك، تقبل الواجهة الخلفية المحلية أي شيء يمكن لـ 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`** (افتراضي) — متوسط مسافة جيب التمام إلى أقرب الجيران *ك* للقطعة. قوي؛ يعرض المقاطع التي ليس لها توأم قريب.
- **`centroid`** — المسافة من متوسط الفهرس. الأرخص، متحيز نحو ما هو ممثل بشكل ناقص.
- **`lof`** — عامل الشذوذ المحلي (Local Outlier Factor). الأفضل عندما يكون للفهرس عدة أنماط "طبيعية" متميزة (النهار مقابل الليل مقابل المرآب).

خيارات التحسين:

- `--against "<استعلام>"` — تسجيل الشذوذ *بالنسبة* إلى استعلام. مع `--against-mode within` (افتراضي)، يرتب الشذوذ بين أفضل المطابقات للاستعلام ("المشاة الغريبون في مقاطع المشاة"). مع `--against-mode global`، يجد مقاطع تطابق الاستعلام *ولكنها* تختلف عن بقية الفهرس ("الأحداث النادرة من هذا النوع").
- `--dedupe 0.9` — إسقاط النتائج المتشابهة جدًا لاختيار أعلى ترتيب (افتراضي تشابه جيب التمام 0.9). يمنع الإطارات المكررة تقريبًا من ملء القائمة.
- `--exclude-baseline` — إسقاط النصف الأقرب إلى المتوسط من الفهرس قبل التسجيل. مفيد عندما يهيمن على الفهرس لقطات "مملة" متكررة.
- `-k, --neighbors 10` — *ك* لـ `knn`/`lof`.
- `--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

تحميل الفيديو: يتم إرسال ملفات القطع المحلية إلى OSS المؤقت المُدار من DashScope عبر SDK Python الرسمي قبل أن تستهلكها واجهة API (تتوقع واجهة HTTP عنوان URL؛ ويتولى SDK معالجة التحميل نيابة عنك).

الواجهة الخلفية المحلية (لا حاجة لمفتاح API)

قم بفهرسة والبحث باستخدام نموذج Qwen3-VL-Embedding المحلي بدلاً من Gemini API. مجاني، خاص، ويعمل بالكامل على جهازك. للحصول على أفضل جودة بحث، استخدم الواجهة الخلفية لـ Gemini — يُعد النموذج المحلي 8B بديلاً قويًا عندما تحتاج إلى بحث غير متصل/خاص، والنموذج 2B هو خيار احتياطي عندما لا يدعم الجهاز 8B.

يتم اكتشاف النموذج تلقائيًا من أجهزتك — qwen8b لوحدات معالجة الرسومات NVIDIA وأجهزة Mac بذاكرة 24 جيجابايت فأكثر، qwen2b لأجهزة Mac الأصغر والأنظمة التي تعمل بوحدة المعالجة المركزية فقط. يمكنك التجاوز باستخدام --model qwen2b أو --model qwen8b. اختر تثبيتًا بناءً على أجهزتك:

لن تعمل جيدًا: أجهزة Mac Intel والأجهزة التي لا تحتوي على وحدة معالجة رسومات مخصصة. هذه تعود إلى وحدة المعالجة المركزية مع float32 — بطيئة جدًا وتستهلك ذاكرة كثيرة للاستخدام العملي. استخدم الواجهة الخلفية لـ Gemini API (الافتراضي) بدلاً من ذلك.

لست متأكدًا؟ على Mac، استخدم ".[local]". على NVIDIA، استخدم ".[local-quantized]" — يعمل التكميم 4-bit على أوسع نطاق من أجهزة 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"

أمر البحث يكتشف تلقائيًا الـ backend والـ model مما قمت بفهرسته. يمكنك أيضًا استخدام `--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 — نموذج أصغر، جودة أقل لكن حوالي 6 جيجابايت فقط من الذاكرة (يقبل أيضًا معرفات HuggingFace كاملة)
--quantize / --no-quantize — فرض التكميم بمقدار 4 بتات أو إيقافه (الافتراضي: الكشف التلقائي بناءً على تثبيت bitsandbytes)

ملاحظات:

التشغيل الأول يُحمّل النموذج (~16 جيجابايت لـ 8B، ~4 جيجابايت لـ 2B).
--rerank المحلي يُحمّل نموذج Qwen3-VL Instruct منفصل (Qwen/Qwen3-VL-8B-Instruct أو Qwen/Qwen3-VL-2B-Instruct) بالإضافة إلى نموذج التضمين.
التضمينات من الخلفيات والنماذج المختلفة غير متوافقة. كل مجموعة (خلفية/نموذج) تحصل على فهرس منفصل خاص بها، لذلك لا يمكنها الاختلاط عن طريق الخطأ. إذا بحثت بنموذج لا يحتوي على بيانات مفهرسة، سيتم إخبارك عن النموذج المستخدم فعليًا.
تختلف السرعة حسب عدد أنوية GPU — رقاقات سلسلة M الأساسية أبطأ من Pro/Max لكنها تنتج نتائج متطابقة.

لماذا النموذج المحلي سريع

تبقى الخلفية المحلية سريعة وفعالة من حيث الذاكرة بفضل عدة تقنيات تتراكم:

المعالجة المسبقة تُقلّص القطع قبل وصولها إلى النموذج. يتم تصغير كل قطعة مدتها 30 ثانية إلى 480p بمعدل 5 إطارات في الثانية عبر ffmpeg قبل التضمين. قطعة من كاميرا داش كام بحجم ~19 ميجابايت تصبح ~1 ميجابايت — تقليل بنسبة 95% من البكسلات التي يجب على النموذج معالجتها. يعتمد وقت استنتاج النموذج على عدد البكسلات وليس مدة الفيديو، لذا هذا هو أكبر تسريع منفرد.
أخذ عينات إطارات منخفضة. يرسل معالج الفيديو 32 إطارًا كحد أقصى لكل قطعة إلى النموذج (fps=1.0، max_frames=32). قطعة مدتها 30 ثانية تُنتج ~30 إطارًا — وليس مئات.
تقليص أبعاد MRL. يدعم Qwen3-VL-Embedding التعلم التمثيلي لماتريوشكا. يتم الاحتفاظ فقط بأول 768 بُعدًا من كل تضمين وتطبيعها بـ L2، مما يقلل مساحة التخزين وحساب المسافة في ChromaDB.
التكميم التلقائي. على وحدات NVIDIA GPU ذات الذاكرة العشوائية المحدودة، يتم تحميل النموذج 8B تلقائيًا بمقدار 4 بتات (bitsandbytes) — لينخفض من ~18 جيجابايت إلى ~6-8 جيجابايت مع فقدان جودة طفيف. تعمل 4090 (24 جيجابايت) بنموذج bf16 الكامل مع مساحة إضافية.
تخطي الإطارات الثابتة. يتم اكتشاف القطع التي لا تحتوي على تغيير بصري ذي معنى (مثل سيارة متوقفة) بمقارنة أحجام ملفات JPEG عبر الإطارات المأخوذة عينة، ويتم تخطيها — مما يوفر تمريرًا كاملاً للأمام لكل قطعة.

مع كل هذا، توقع ~~2-5 ثوانٍ لكل قطعة على A100 و~~3-8 ثوانٍ على T4. على 4090، يجب أن يكون النموذج 8B في bf16 ضمن نطاق الأرقام الفردية المنخفضة لكل قطعة.

تراكب بيانات تسلا الوصفية

حرق السرعة والموقع والوقت على المقاطع المقصوصة:```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 الوصفية موجودة فقط في لقطات القيادة (وليس في وضع الوقوف/وضع الحراسة)
- يستخدم التحديد الجغرافي العكسي [واجهة Nominatim API من OpenStreetMap](https://nominatim.openstreetmap.org/) عبر geopy (اختياري)

التثبيت بدعم تراكب 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 "..."` يعيد تشغيل البحث في الخلفية. راجع [SentryMerge README](https://github.com/ssrajadh/sentrymerge#readme) للحصول على تعليمات التثبيت، وخيارات النماذج الخلفية المرئية (Gemini / OpenAI / Qwen المحلي)، ونظام تكوين الكاميرا المعياري للكاميرات غير الموسومة بتقنية Tesla.

### التنقيح باستخدام 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 يعملان بنفس الطريقة. اختر faces أو plates لمكتشفات CPU السريعة؛ استخدم prompt "<text>" للأشياء العشوائية (شاشات الهواتف، الشاشات، بطاقات الأسماء) — يتطلب prompt وحدة معالجة رسومات NVIDIA أو 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` ويواصل فهرسة باقي اللقطات. عادةً ما تصل الأجزاء إلى هناك بسبب فشل عابر متكرر في واجهة برمجة التطبيقات/الخدمة الخلفية، أو أخطاء فك الترميز لملف معين، أو ملفات مفقودة، أو أخطاء نفاد الذاكرة. يتم تسجيل حالات الفشل الدائمة الظاهرية مثل الملفات المفقودة، وأخطاء فك الترميز، ونفاد الذاكرة فوراً، لأن إعادة محاولة نفس الجزء بنفس الإعدادات من غير المرجح أن تساعد.

افحص الأجزاء الفاشلة:```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

فهرسة ساعة واحدة من اللقطات تكلف حوالي 2.84 دولار أمريكي باستخدام API التضمين من Gemini (الإعدادات الافتراضية: قطع مدتها 30 ثانية، تداخل 5 ثوانٍ):

ساعة واحدة = 3600 ثانية من الفيديو = 3600 إطار تتم معالجتها بواسطة النموذج. 3600 إطار × 0.00079 دولار = ≈ 2.84 دولار/ساعة

يقوم Gemini API بشكل أصلي باستخراج وتقسيم إطار واحد بالضبط في الثانية من الفيديو المُرفع، بغض النظر عن معدل الإطارات الفعلي للملف. خطوة المعالجة المسبقة (التي تخفض القطع إلى دقة 480p بمعدل 5 إطارات في الثانية عبر ffmpeg) هي تحسين محلي/عرض نطاق — فهي تحافظ على صغر أحجام الحمولات بحيث تكون طلبات API سريعة ولا تنتهي مهلتها — لكنها لا تغير عدد الإطارات التي يعالجها API.

هناك تحسينان مدمجان يساعدان في تقليل التكاليف بطرق مختلفة:

المعالجة المسبقة (مُفعّلة افتراضيًا) — يتم خفض حجم القطع إلى 480p بمعدل 5 إطارات في الثانية قبل الرفع. نظرًا لأن API يعالج بمعدل إطار واحد في الثانية بغض النظر، فإن هذا يقلل فقط من حجم الرفع ووقت النقل، وليس عدد الإطارات التي يتم فوترتها. فهو يحسن السرعة بشكل أساسي ويمنع انتهاء مهلات الطلب.
تخطي الإطارات الثابتة (مُفعّل افتراضيًا) — يتم تخطي القطع التي لا تحتوي على تغيير بصري ذي معنى (مثل سيارة متوقفة) بالكامل. هذا يوفر استدعاءات API حقيقية ويقلل التكلفة بشكل مباشر. تعتمد التوفيرات على لقطاتك — تستفيد تسجيلات وضع Sentry Mode التي تحتوي على ساعات من وقت الخمول أكثر من غيرها، بينما قد لا تحتوي لقطات القيادة النشطة على شيء لتخطيه.

استعلامات البحث لا تذكر (تضمين نص فقط).

Qwen Cloud (DashScope، Qwen3-VL-Embedding)

يقوم DashScope بفوترة التضمين متعدد الوسائط باليوان الصيني لكل 1000 رمز إدخال، حسب الوسائط. للنموذج الافتراضي qwen3-vl-embedding، فإن الأسعار المنشورة من Alibaba (تحقق من المستند أدناه لمنطقتك وأي تحديثات) تكون على النحو التالي تقريبًا:

الإدخال النصي: حوالي ¥0.0007 لكل 1000 رمز إدخال
الإدخال الصوري/الفيديو: حوالي ¥0.0018 لكل 1000 رمز إدخال

ترسل الفهرسة قطع فيديو (وسائط الفيديو)؛ كل استعلام search / img هو في الغالب رموز نصية أو صورية، وهي أرخص لكل رمز من الفيديو. التكلفة الحقيقية هي عدد الرموز التي يعيدها DashScope لكل استدعاء API (يعتمد على الدقة، المدة، أخذ العينات مثل DASHSCOPE_VIDEO_FPS، إلخ) — لا يوجد معدل ثابت "دولار لكل ساعة من اللقطات" مثل سعر الدولار لكل إطار المنشور من Gemini بدون قياس عبء العمل الخاص بك.

كما توثق Alibaba بدل رموز مجاني (على سبيل المثال 1 مليون رمز ضمن فترة محدودة بعد التنشيط)؛ قم بالتأكيد في صفحة قياس وفوترة 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 — قيود معروفة في PyTorch على Apple Silicon. تعود العملية إلى CPU لخطوة واحدة؛ كل شيء آخر يبقى على GPU. لا تأثير على جودة المخرجات.
video_reader_backend torchcodec error, use torchvision as default — لا يمكن لـ torchcodec العثور على FFmpeg متوافق على macOS. يعود معالج الفيديو إلى torchvision تلقائيًا. هذا متوقع وينتج نتائج متطابقة.
You are sending unauthenticated requests to the HF Hub — يتم تنزيل النموذج من Hugging Face بدون رمز مميز. قد تكون سرعات التنزيل أقل قليلاً، لكن النموذج يتم تحميله بشكل جيد. قم بتعيين متغير البيئة HF_TOKEN لإسكات هذا إذا كان يزعجك.

القيود والعمل المستقبلي

اكتشاف الإطارات الثابتة هو استكشافي — يستخدم مقارنة حجم ملف JPEG عبر الإطارات المأخوذة. قد يتخطى أحيانًا القطع ذات الحركة الخفية أو يضمّن قطعًا ثابتة حقًا. قم بتعطيله باستخدام --no-skip-still إذا كنت بحاجة إلى فهرسة كل قطعة.
جودة البحث تعتمد على حدود القطع — إذا امتد حدث عبر قطعتين، فإن النافذة المتداخلة تساعد لكنها ليست مثالية. يمكن أن يؤدي التجزئة الأكثر ذكاءً (مثل اكتشاف المشاهد) إلى تحسين هذا.
Gemini Embedding 2 في مرحلة المعاينة — قد يتغير سلوك API والتسعير.

التوافق

يعمل هذا مع لقطات .mp4 و .mov، وليس فقط وضع Sentry Mode من Tesla. يقوم ماسح الدليل بالعثور تلقائيًا على كلا النوعين من الملفات بغض النظر عن هيكل المجلد.

المتطلبات

Python 3.11+
ffmpeg في PATH، أو استخدم ffmpeg المضمنة عبر imageio-ffmpeg (مثبتة افتراضيًا)
خلفية Gemini: مفتاح Gemini API (احصل على واحد مجانًا)
خلفية محلية:
- GPU مع CUDA أو Apple Metal (انظر جدول الأجهزة لمتطلبات VRAM/RAM)
- macOS: brew install ffmpeg (مطلوب من قبل مفكك الفيديو)
- Linux/Windows: لا توجد تبعيات نظام إضافية

Apple Silicon، 24 جيجابايت+ RAM	`uv tool install ".[local]"`	qwen8b	float16 كامل عبر MPS
Apple Silicon، 16 جيجابايت RAM	`uv tool install ".[local]"`	qwen2b	8B لن يتسع؛ 2B يستخدم ~6 جيجابايت
Apple Silicon، 8 جيجابايت RAM	`uv tool install ".[local]"`	qwen2b	ضيق — قد يحدث تبديل تحت الحمل؛ يُوصى باستخدام Gemini API بدلاً من ذلك
NVIDIA، 18 جيجابايت+ VRAM	`uv tool install ".[local]"`	qwen8b	دقة bf16 كاملة (يتم سحب عجلات CUDA تلقائيًا على Linux/Windows)
NVIDIA، 8–16 جيجابايت VRAM	`uv tool install ".[local-quantized]"`	qwen8b	تكميم 4-bit (~6–8 جيجابايت)

`db/`	`sentrysearch index`	فهرس ChromaDB المتجه للقطات المضمنة الخاصة بك.	نعم، لكن هذا يحذف الفهرس. أعد تشغيل `sentrysearch index <dir>` قبل البحث مرة أخرى.
`.env`	`sentrysearch init`	يخزن مفتاح API الخاص بـ Gemini للخلفية الافتراضية.	نعم، لكن الأوامر التي تعتمد على 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

الأكثر شعبية