MaterialSearch

用一句话搜出电脑里的照片和视频

开源 unknown 搜索知识

访问官网 ↗ GitHub ↗ 文档 ↗

GitHub 星标 ★ 1978

维护状态较活跃

是否开源是

定价模式 unknown

项目预览

项目数据

分类搜索知识

开发团队chn-lee-yumi

所属国家

官网地址http://materialsearch.gcc.ac.cn

GitHubhttps://github.com/chn-lee-yumi/MaterialSearch

定价模式unknown

价格说明定价信息待确认

访问状态

是否开源是

开源协议GPL-3.0

主要语言HTML

技术栈/模型

GitHub 星标★ 1978

30天Star增速

HF 下载量

上线时间2023-03-16 00:00:00

代码更新—

仓库体积—

本站数据更新—

维护状态较活跃

中文支持

访问方式

移动端支持

综合评分

收录时间2026-10-11

浏览次数0

项目介绍

MaterialSearch 是一个本地素材语义搜索工具，用自然语言就能找到电脑里的照片和视频。它解决的核心问题是：传统文件名搜索无法理解画面内容，找素材只能靠记忆和翻文件夹。项目通过 AI 模型把图片、视频帧转成向量，建立本地索引，之后输入「海边日落」「穿红衣服的人」这类描述，就能直接匹配到对应画面。它支持以图搜图、按文字描述搜图、按画面描述搜视频、视频帧级搜索，还能对视频做关键帧抽取后统一检索。所有处理都在本地完成，素材不上传云端，适合有隐私顾虑的用户。技术上是前后端一体的 Web 界面，启动后浏览器操作，索引一次后可反复快速搜索，适合个人素材库、剪辑师找镜头、摄影爱好者整理图库等场景。

Star 增长趋势

本站每日记录该项目 GitHub 星标变化，观测越久曲线越完整

正在加载星标数据…

技术标签

使用教程

—

难度：进阶约 15 分钟部署方式：Docker 6 步

环境要求

已安装 Docker 与 docker-compose
支持 amd64 架构（可选 GPU 加速）
准备好保存数据库的本地目录
准备好需要扫描的照片/视频本地路径
需要访问镜像仓库（国内可选用阿里云仓库）

安装与启动步骤

1获取项目文件

克隆仓库后进入目录，部署所需的 docker-compose.yml 在仓库中，文件内附有详细注释，建议先通读一遍再改。
```
git clone https://github.com/chn-lee-yumi/MaterialSearch.git
cd MaterialSearch
```
2确认镜像来源

镜像在 DockerHub 的 yumilee/materialsearch，国内用户推荐用阿里云香港仓库 registry.cn-hongkong.aliyuncs.com/chn-lee-yumi/materialsearch。镜像自带
3准备两类路径

启动前需确定：保存数据库的路径；本地要扫描的素材路径，以及它对应挂载到容器内的路径。两者要一一对应，后续在 compose 文件里配置。
4修改 compose 配置

编辑 docker-compose.yml 的 environment 与 volumes 两段，填入上一步的路径和参数；如需 GPU 加速，取消文件中 GPU 相关段的注释。
5可选：写 .env

推荐用项目根目录的 .env 或环境变量覆盖默认配置，未配置的项会使用 config.py 中的默认值。例如配置素材扫描路径与跳过路径。
6启动容器

在 docker-compose.yml 所在目录执行启动命令，容器会按配置扫描素材并建立索引，随后即可通过浏览器界面搜索。
```
docker-compose up -d
```

关键配置

配置项	必填	说明	示例
`ASSETS_PATH`	是	需要扫描的素材目录，多个路径用英文逗号分隔	`C:/Users/Administrator/Pictures,C:/Users/Administrator/Video`
`SKIP_PATH`	否	扫描时要跳过的目录，避免索引无关文件	`C:/Users/Administrator/AppData`
`IMAGE_EXTENSIONS`	否	当部分图片格式未被扫描时，把对应扩展名加到这里	`jpg,png,webp`
`VIDEO_EXTENSIONS`	否	当部分视频格式未被扫描时，把对应扩展名加到这里	`mp4,mov,mkv`
`IMAGE_MIN_WIDTH`	否	小图片扫不到时，调小该值即可被纳入索引	`100`
`TRANSFORMERS_OFFLINE`	否	Docker 镜像默认 1（不联网校验模型版本），要换默认模型需设为 0	`0`

如何确认成功

执行 docker-compose ps 看到容器处于 Up 状态，再按 compose 文件里的端口映射用浏览器打开 Web 界面并能发起搜索，即部署成功。

常见问题

Q：可以给容器设置内存上限吗？

A：不建议，README 明确提示限制内存可能引发奇怪的问题，官方 issue 中已有先例。

Q：想把容器里的默认模型换成别的模型？

A：镜像默认设置了 TRANSFORMERS_OFFLINE=1，不会联网检查模型版本。需要修改 .env 把它设为 0，才能更换模型。

Q：某些图片或视频格式没被扫描到怎么办？

A：把它们对应的扩展名补到 IMAGE_EXTENSIONS 或 VIDEO_EXTENSIONS 中；若确认代码里缺了已支持的扩展名，可以提 issue 或 PR。

Q：小尺寸图片搜不到是什么原因？

A：可能被最小尺寸过滤了，尝试调小 IMAGE_MIN_WIDTH 与 IMAGE_MIN_HEIGHT 后重新扫描。

Q：网络需要走代理怎么设置？

A：使用 http_proxy 和 https_proxy 两个变量，例如都指向 http://127.0.0.1:7070。

注意事项

所有素材处理都在本地完成，图片和视频不会上传到云端。
核心逻辑已拆分为独立的 pip 包 materialsearch-core，本仓库只保留前端代码。
仓库中部分源码做了混淆处理，仅为保护署名与版权，不影响 GPLv3 允许的正当使用。
不建议把 ASSETS_PATH 设为 SMB/NFS 等远程目录，会明显拖慢扫描速度。

核心亮点

支持自然语言描述搜图搜视频，不依赖文件名和标签
本地离线建索引与检索，素材不出本机，隐私友好
覆盖以图搜图、视频帧搜索等多种检索方式，素材类型兼容性好

不足之处

依赖本地算力与模型下载，首次建索引耗时较长
HTML 项目工程化程度有限，大规模素材库性能待验证

适用场景

剪辑师从海量素材中快速定位某个画面镜头
摄影爱好者按画面内容整理和查找历史照片
普通用户用文字描述找回记不清文件名的本地视频

替代项目

immich、clip-retrieval

上一篇：Understand-Anything

下一篇：collective-ai-tools