
بحث دلالي عبر الفيديوات باستخدام Gemini Embedding 2 أو Qwen3-VL.
بحث دلالي في مقاطع الفيديو. اكتب ما تبحث عنه، واحصل على مقطع مقصوص.
[!IMPORTANT] المصدر الرسمي: github.com/ssrajadh/sentrysearch هو الموطن الرسمي الوحيد لـ SentrySearch. المواقع الأخرى التي تعيد نشر هذا المشروع أو تعكسه ليست تابعة للقائم على صيانته ولا معتمدة منه، حمّل دائمًا من هذا المستودع.
اللغات: English · 简体中文
جديد: خلفية MLX لمعالجات Apple Silicon: تشغّل النموذج المحلي 2B بسرعة مضاعفة وبأقل من نصف الذاكرة، وبنفس الدقة
يقسّم SentrySearch مقاطع الفيديو الخاصة بك إلى أجزاء متداخلة، ويضمّن كل جزء كفيديو باستخدام Google's Gemini Embedding API أو Alibaba DashScope (qwen-cloud) أو نموذج Qwen3-VL المحلي، ويخزّن المتجهات في قاعدة بيانات ChromaDB محلية. عند البحث، يُضمَّن استعلامك النصي (أو الصورة، انظر البحث بالصورة) في نفس فضاء المتجهات ويُطابَق مع تضمينات الفيديو المخزّنة. تُقتطع أفضل مطابقة تلقائيًا من الملف الأصلي وتُحفظ كمقطع.
macOS/Linux:
curl -LsSf https://astral.sh/uv/install.sh | sh
Windows:
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
git clone https://github.com/ssrajadh/sentrysearch.git
cd sentrysearch
uv tool install .
يتطلب Python 3.11 أو 3.12 (لا تدعم حزم PyTorch بعد الإصدار 3.13+). إذا كان إصدار Python الافتراضي لديك أحدث، فثبّت إصدار 3.12 مُدارًا وثبّت الأداة عليه:
uv python install 3.12 uv tool install --python 3.12 .
--backend local أو --backend mlx أو --backend qwen-cloud مع DASHSCOPE_API_KEY في .env.sentrysearch init
سيطلب منك هذا مفتاح Gemini API الخاص بك، ويكتبه في .env، ويتحقق منه باستخدام تضمين اختباري.
sentrysearch index /path/to/footage
sentrysearch search "red truck running a stop sign"
يُشترط توفّر ffmpeg لتقسيم الفيديو واقتطاعه. وإذا لم يكن مثبتًا على مستوى النظام، فسيُستخدم imageio-ffmpeg المرفق تلقائيًا.
الإعداد اليدوي: إذا كنت تفضّل عدم استخدام
sentrysearch init، يمكنك نسخ.env.exampleإلى.envوإضافة مفتاحك من aistudio.google.com/apikey يدويًا.
$ 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 لمنع الإنفاق الزائد غير المقصود.
$ 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 — تحديد عدد الطلبات في الدقيقة لواجهة برمجة التطبيقات السحابية (التفاصيل أدناه)--backend local — استخدام نموذج محلي بدلاً من Gemini (التفاصيل أدناه)--backend mlx — استخدام النموذج المحلي عبر MLX على Apple Silicon، أسرع وأخف من local (التفاصيل أدناه)--dry-run — معاينة أعداد المقاطع لكل ملف والتكلفة التقديرية لـ Gemini دون أي استدعاءات لواجهة برمجة التطبيقات أو تحميل نموذج أو كتابة ملفات$ 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، أو 0.35 عند استخدام --backend mlx)، فسيُطلب منك التأكيد قبل التقليم:
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 فقط للتجاوز.
# 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 بالنتائج المرتّبة حسب التضمين بدلًا من إفشال البحث.