yurijmikhalevich/rclip

rclip – 影像的 grep

是什麼 – rclip 是一款命令列工具，讓您能使用自然語言、範例圖片或兩者的組合，在自己的電腦上搜尋影像檔案的內容。它會針對資料夾中的影像建立一個基於 CLIP 的本地嵌入索引，然後針對查詢進行結果排序，且完全不將任何數據傳送到雲端。

核心能力

• 僅限文字搜尋 – 例如 rclip "two parrots on a branch"
• 反向影像搜尋 – 提供本地路徑或 URL 並取得視覺上相似的圖片。
• 混合/算術查詢 – 結合或扣除文字與影像術語，並可選擇性地加權 (2:golden retriever + ./pool.jpg - fruit)。
• 增量索引 – 在後續執行時僅處理新增或變動的檔案，使重複搜尋變得快速。
• 互動式終端機 UI – 在支援 Kitty graphics 的終端機（Kitty, Ghostty, iTerm2, Konsole）中運作的縮圖網格。 鍵盤快捷鍵讓您無需離開 shell 即可瀏覽、複製、下載或開啟影像。
• 廣泛的格式支援 – JPEG/PNG/WebP/TIFF/GIF 以及 macOS/Windows 上的原生 HEIC；可透過 flag 進行實驗性的 RAW (arw, cr2, dng) 支援。
• 跨平台 – 以 Snap, AppImage, Homebrew formula, MSI installer, 以及 pip wheel 形式打包，支援 Linux, macOS (僅限 Apple Silicon), 以及 Windows。

運作原理

• 使用 OpenCLIP ViT-B/32 模型（與 OpenAI 的 CLIP 架構相同）將影像與文字都轉換為 512 維度的嵌入向量。
• 嵌入向量儲存在每個資料夾的本地簡單索引中；查詢結果是透過計算查詢嵌入向量與儲存的影像嵌入向量之間的餘弦相似度來獲得。
• 所有運算都在 CPU（或如果底層 PyTorch build 偵測到則使用 GPU）上進行，因此工具可以離線運作，並確保您的照片私密性。

典型工作流程

# First run – builds the index for the current folder
cd ~/Photos && rclip "sunset over lake"

# Subsequent runs are fast (only new files are indexed)
cd ~/Photos && rclip "two cats"

# Interactive UI with inline previews
rclip --interactive

# Image-to-image search
rclip ./example.jpg

此工具也可以輸出純文字檔案路徑 (-f)，以便將結果傳遞給其他命令（例如 xargs cp, feh, 或自定義腳本）。

安裝方式

• Linux – sudo snap install rclip (或下載 AppImage，或使用 PyTorch CPU wheel 進行 pip install rclip)。
• macOS – brew install yurijmikhalevich/tap/rclip (Apple Silicon) 或 pip install rclip。
• Windows – 從最新版本下載 MSI installer，或使用 pip install rclip。

授權方式 – MIT.

更多資訊 – README 中連結了部落格文章、YouTube 演示與一份短篇論文；歡迎透過 GitHub Discussions 頁面進行討論與貢獻。