Add semantic image and text search

README.md

@@ -1,6 +1,6 @@
 # Pixhelf
 
-轻量的本地照片画廊，支持 JPEG、PNG、WebP、搜索和排序。
+轻量的本地照片画廊，支持 JPEG、PNG、WebP、自然语言文字搜图、随机探索和本地以图搜图。相似图片会直接显示在图片查看器下方的分页瀑布流中。
 
 ## Docker Compose
 
@@ -31,3 +31,88 @@ mkdir -p pic && docker run -d --name pixhelf --restart unless-stopped -p 3002:30
 ```
 
 照片放进 `./pic`，访问 <http://localhost:3002>。
+
+## 自然语言文字搜图
+
+可选的 Chinese-CLIP ViT-B/16 模型支持直接输入中文描述，例如“海边日落”“草地上的狗”或“夜晚城市街道”。图片与文字都在本机编码，Pixhelf 不会在运行时联网或自动下载模型。索引尚未完成时搜索框仍按文件名搜索；完成后自动切换到语义搜索，并保留文件名精确匹配优先级。
+
+下载并校验固定版本的官方模型与词表（模型约 753 MB）：
+
+```bash
+mkdir -p models/chinese-clip
+curl --proto '=https' --tlsv1.2 --fail --location \
+  https://huggingface.co/OFA-Sys/chinese-clip-vit-base-patch16/resolve/f4a64596bbcf9a2a94591b74b9dc39b2e4e77e3e/model.safetensors \
+  --output models/chinese-clip/model.safetensors
+curl --proto '=https' --tlsv1.2 --fail --location \
+  https://huggingface.co/OFA-Sys/chinese-clip-vit-base-patch16/resolve/f4a64596bbcf9a2a94591b74b9dc39b2e4e77e3e/vocab.txt \
+  --output models/chinese-clip/vocab.txt
+printf '%s  %s\n%s  %s\n' \
+  29cc0b2bcf6ff777f2e15742be92b110e4acbdb2068356e862c4637a4b15fe4f \
+  models/chinese-clip/model.safetensors \
+  45bbac6b341c319adc98a532532882e91a9cefc0329aa57bac9ae761c27b291c \
+  models/chinese-clip/vocab.txt | sha256sum --check -
+```
+
+Compose 服务增加模型目录挂载与启动参数：
+
+```yaml
+services:
+  pixhelf:
+    volumes:
+      - "./pic:/data/pic:ro"
+      - pixhelf-cache:/data/.pixhelf-cache
+      - "./models/chinese-clip:/models/chinese-clip:ro"
+    command:
+      - "--text-search-model"
+      - "/models/chinese-clip/model.safetensors"
+      - "--text-search-vocab"
+      - "/models/chinese-clip/vocab.txt"
+```
+
+本地运行：
+
+```bash
+pixhelf \
+  --text-search-model ./models/chinese-clip/model.safetensors \
+  --text-search-vocab ./models/chinese-clip/vocab.txt
+```
+
+文字搜图使用一个 CPU 后台任务建立 512 维图像索引，向量按模型与词表指纹保存在缩略图缓存中，每张约 552 字节。侧边栏会显示“文字索引”进度；更换模型文件前请先停止 Pixhelf。
+
+## 本地以图搜图
+
+默认模式不需要模型：相似度完全在本机计算，综合比较图片的构图、亮度、色彩分布和边缘纹理，并过滤明显无关的结果。特征描述符会保存在缩略图缓存卷中；升级已有图库时会在后台自动补齐，之后重启无需重新计算。
+
+如果希望识别“主体相近、构图和颜色不同”的图片，可以选择挂载 Meta 的 DINOv2 Small 官方权重。Pixhelf 不会联网或自动下载模型；开启后会用一个 CPU 后台任务建立 384 维语义索引，再与默认视觉特征混合排序。模型缺失或单张图片推理失败时会自动使用默认算法。
+
+先在宿主机下载并校验固定版本的模型（88.2 MB，Apache-2.0）：
+
+```bash
+mkdir -p models
+curl --proto '=https' --tlsv1.2 --fail --location \
+  https://huggingface.co/facebook/dinov2-small/resolve/ed25f3a31f01632728cabb09d1542f84ab7b0056/model.safetensors \
+  --output models/dinov2-small.safetensors
+printf '%s  %s\n' \
+  ae1e99fcefd534ed978cdeb8326f08030c96e28b7a81ffcbc98a857c84d14be1 \
+  models/dinov2-small.safetensors | sha256sum --check -
+```
+
+然后在 Compose 服务中增加只读挂载和启动参数：
+
+```yaml
+services:
+  pixhelf:
+    volumes:
+      - "./pic:/data/pic:ro"
+      - pixhelf-cache:/data/.pixhelf-cache
+      - "./models/dinov2-small.safetensors:/models/dinov2-small.safetensors:ro"
+    command: ["--semantic-model", "/models/dinov2-small.safetensors"]
+```
+
+本地运行时使用同一个参数：
+
+```bash
+pixhelf --semantic-model ./models/dinov2-small.safetensors
+```
+
+语义向量按模型指纹保存在缩略图缓存中，每张约 424 字节；侧边栏会显示“语义索引”进度。更换模型文件前请先停止 Pixhelf，替换后再启动。