使用 Ultralytics 构建基于 CLIP 的语义图像检索VisualAISearch 与 SearchApp 全解析【免费下载链接】ultralyticsUltralytics YOLO26, YOLO11, YOLOv8 — object detection, instance segmentation, semantic segmentation, image classification, pose estimation, object tracking项目地址: https://gitcode.com/GitHub_Trending/ul/ultralytics本文围绕 Ultralytics 仓库中ultralytics/solutions/similarity_search.py模块的 API 参考文档展开系统讲解基于 OpenAI CLIP 的零样本语义图像检索解决方案。你将掌握VisualAISearch与SearchApp两个类的设计原理、全部核心方法与参数学会用几行代码把本地图片目录变成可按自然语言检索的语义搜索引擎含 Flask Web 界面并通过仓库源码与测试用例理解其底层实现机制。模块定位一个类打通「图像嵌入 相似度检索 Web 界面」在 Ultralytics 的 solutions 家族中similarity_search.py承担的是跨模态语义检索职责——它不同于目标检测、分割等定位类任务而是解决「给一句自然语言描述找到图片库里语义最匹配的图像」这一类问题。从源码结构看similarity_search.py 定义了两个对外类类定位源码行号VisualAISearch语义检索的核心后端负责 CLIP 嵌入生成、索引构建与余弦相似度检索VisualAISearch 定义SearchApp基于 Flask 的 Web 前端封装为检索能力提供可视化交互界面SearchApp 定义两个类都在 ultralytics/solutions/init.py 中被导出因此用户可以直接通过from ultralytics import solutions后以solutions.VisualAISearch、solutions.SearchApp方式调用无需关心具体导入路径。工作原理CLIP 多模态嵌入 NumPy 余弦相似度similarity_search.py的模块级 docstring 明确定义了这套系统的核心思想利用 OpenAI CLIP 同时为图像与文本生成高质量嵌入使二者对齐到同一个语义空间再用 NumPy 余弦相似度完成快速检索见 VisualAISearch 类注释。整个检索链路可以拆成三个阶段编码阶段CLIP对图片目录中的每一张图调用 CLIP 视觉编码器生成图像嵌入对自然语言查询调用 CLIP 文本编码器生成文本嵌入。两类向量被投影到同一多模态语义空间因此可以直接做向量比较。索引阶段NumPy所有图像嵌入以float32堆叠成一个二维数组并做行级 L2 归一化后保存为embeddings.npy图像文件名保存为paths.npy。归一化后向量内积即等价于余弦相似度无需引入任何额外的向量数据库。检索阶段矩阵乘法一次查询嵌入与全量图像嵌入的矩阵乘法即可算出全部相似度分数排序后返回 Top-k 结果。模型加载链路build_text_model 与 CLIP 编码器VisualAISearch.__init__在构造时通过build_text_model(clip:ViT-B/32, deviceself.device)加载 CLIP 模型见 构造方法实现。其中build_text_model是 Ultralytics 在 ultralytics/nn/text_model.py 中提供的统一文本模型工厂variant 采用base:size格式解析如clip:ViT-B/32、mobileclip:s0当base clip时实例化CLIP(size, device)实际通过clip.load(size, devicedevice, download_root...)加载 OpenAI CLIP 预训练权重见 text_model.py 中的 CLIP 实现支持clip、mobileclip、mobileclip2三种 base其他取值会抛出ValueError。因此VisualAISearch的图像特征提取方法extract_image_feature与文本特征提取方法extract_text_feature本质上是对 CLIP 编码器的薄封装前者对Image.open(path)编码后者先tokenize再encode_text并统一.detach().cpu().numpy()转成 NumPy 向量见 相似度搜索方法实现。构造参数与环境依赖VisualAISearch的构造签名接受关键字参数官方 API 文档与 guides 指南给出的可配置项如下参数类型默认值说明datastrimages待索引与检索的图片目录路径devicestrcpuCLIP 推理设备如cpu、cuda、0强约束需要 PyTorch ≥ 2.4构造方法的第一条语句是硬性断言见 构造方法assert TORCH_2_4, fVisualAISearch requires torch2.4 (found torch{TORCH_VERSION})即VisualAISearch只有在 torch ≥ 2.4 时才可用。仓库测试用例同样通过pytest.mark.skipif(not TORCH_2_4, ...)对这一前提做条件跳过见 tests/test_solutions.py说明这是该功能既定的版本门槛而非可选建议。图片目录缺失时的自动下载当传入的data目录不存在时模块不会直接报错而是从 Ultralytics 官方资源地址下载示例图片集images.zip并解压到本地images目录后继续构建索引见 自动下载逻辑方便用户零准备体验完整检索流程。图片格式过滤load_or_build_index在遍历目录时会以IMG_FORMATS集合定义于 ultralytics/data/utils.py过滤非图片后缀文件并对单张图片编码失败的情况以LOGGER.warning跳过而非中断整个流程见 索引构建实现。核心 API 方法逐一解析extract_image_feature / extract_text_feature分别提取图像与文本的 CLIP 嵌入向量二者返回的 NumPy 数组经过 L2 归一化后可直接用于相似度比较见 特征提取方法。load_or_build_index索引缓存与重建机制这是性能设计的关键一环见 load_or_build_index 实现命中缓存直接加载如果当前目录下已存在embeddings.npy与paths.npy直接np.load载入打印Loading existing embeddings...并返回未命中则全量构建遍历data_dir中所有符合IMG_FORMATS的图片逐张提取特征向量与文件名无有效向量即报错若全部失败抛出RuntimeError(No image embeddings could be generated.)归一化后落盘np.vstack堆叠为float32二维数组经_normalize行级 L2 归一化分别np.save保存索引与路径打印Indexed N images.。由于默认缓存文件名是工作目录下的embeddings.npy/paths.npy首次构建后再次实例化同一目录数据会直接跳过耗时的编码阶段。_normalize让内积等于余弦相似度_normalize是静态方法将每行除以自身 L2 范数分母用np.maximum(..., 1e-12)防止除零注释明确说明归一化后「inner products equal cosine similarity」见 归一化方法。search(query, k, similarity_thresh)语义检索主入口search方法将一次检索压缩为三步线性代数运算见 search 实现def search(self, query: str, k: int 30, similarity_thresh: float 0.1) - list[str]: text_feat self._normalize(self.extract_text_feature(query).astype(float32)) scores self.index text_feat[0] # 余弦相似度嵌入已 L2 归一化 top_k np.argsort(scores)[::-1][: max(k, 0)] results [(self.image_paths[i], float(scores[i])) for i in top_k if scores[i] similarity_thresh] ...需要特别指出的是文档中search的三参数签名k30、similarity_thresh0.1来自模块 docstring 与源码实现而公开参数表仅列出data与device。k控制返回的最大结果数量similarity_thresh控制相似度下限过滤二者共同决定最终结果的精度与召回。检索结束后会把每条命中的文件名 | Similarity: 分数以 4 位小数格式打印到日志返回值是按相似度降序排列的图片文件名列表。类还实现了__call__因此searcher(a dog sitting on a bench)与searcher.search(...)两种写法等价见 直接调用接口。实战一以编程方式执行语义检索按官方 API 文档与指南的标准用法创建检索器并直接传入自然语言查询from ultralytics import solutions searcher solutions.VisualAISearch( dataimages, # 替换为你要索引的本地图片目录 devicecpu, # 可改为 cuda 或设备编号 0 以加速编码 ) results searcher(a dog sitting on a bench) # 日志输出示例 # Ranked Results: # - 000000546829.jpg | Similarity: 0.3269 # - 000000549220.jpg | Similarity: 0.2899 # - 000000517069.jpg | Similarity: 0.2761 # - 000000029393.jpg | Similarity: 0.2742 # - 000000534270.jpg | Similarity: 0.2680首次运行时若无images目录会自动下载示例图片集若已有该目录则自动构建并缓存索引。从这段代码可见整个「零样本、无需标注、无标签体系」的检索能力全部被封装在类内部——这正体现了零样本语义检索的核心优势不需要针对你的数据集做任何训练或打标签。仓库中的端到端测试验证了这一用法见 test_similarity_search_complete在临时目录生成两张随机224×224测试图构造检索器后以a red and white object查询并断言返回结果非空。另一条测试则使用包含 4 张狗的示例图片包进行真实语义查询见 test_similarity_search。实战二一键启动 Flask 语义检索 Web 应用SearchApp把上述后端能力封装为可直接运行的 Web 服务见 SearchApp 实现from ultralytics import solutions app solutions.SearchApp( dataimages, # 建议使用绝对路径详见下方注意事项 devicecpu, ) app.run(debugFalse) # 测试阶段可改为 debugTrueSearchApp的初始化过程值得展开构造时通过check_requirements(flask3.0.1)校验 Flask 版本再延迟导入flask内部创建VisualAISearch实例作为检索后端属性searcher以templates为模板目录、以图片目录的绝对路径作为静态目录并设置static_url_path/images使检索结果可通过/images/文件名在页面中显示通过add_url_rule(/, ...)将根路由GET/POST绑定到index视图POST 请求从表单读取query字段交给检索器结果渲染进similarity-search.html模板见 index 方法。图片路径警告指南文档特别提示——若使用自有图片data参数务必传绝对路径。因为 Flask 静态文件服务存在路径解析限制相对路径可能导致图片无法在网页上正常显示。仓库自带的页面模板 ultralytics/solutions/templates/similarity-search.html 实现了完整交互包含居中搜索框、搜索结果瀑布网格以及「Top 5 / Top 10 / Top 30」三个动态过滤按钮默认显示 Top 10整体采用响应式卡片网格布局。如果你对默认界面不满意该模板完全可作为自定义前端React/Vue 等时参考的后端 API 返回契约——index视图实际只是把结果文件名列表交给模板渲染。SearchApp的初始化能力在测试中被覆盖见 test_similarity_search_app_init断言实例具备searcher与run属性。运行前提与限制根据源码、测试与官方指南使用本方案前需确认以下前提前提说明依据torch ≥ 2.4构造时硬断言不满足直接抛错构造方法断言CLIP 依赖安装首次导入时会校验并安装ultralytics/CLIP等模型依赖text_model.pyFlask ≥ 3.0.1仅SearchApp需要SearchApp 构造设备可用性device经select_device自动选择 CPU/GPUultralytics/utils/torch_utils.py自有图片建议绝对路径保证 Web 界面图片正常展示指南文档数据规模检索采用全量矩阵乘法的精确暴力搜索数千级嵌入可实时响应超大图库需自行评估索引与检索实现此外模块在文件顶部设置os.environ[KMP_DUPLICATE_LIB_OK] TRUE见 similarity_search.py用于规避部分系统上 OpenMP 库冲突导致的运行崩溃——这也是在多线程/多库环境中容易遇到的坑点。源码级速查关键实现位置如果你希望深入研读这套语义检索解决方案的实现细节可按以下路径在仓库内定位核心模块ultralytics/solutions/similarity_search.pyVisualAISearchL20-L166与SearchAppL169-L222顶层导出ultralytics/solutions/init.pySearchApp、VisualAISearch均在此注册文本模型工厂ultralytics/nn/text_model.pybuild_text_model(clip:ViT-B/32, ...)的解析逻辑Web 前端模板ultralytics/solutions/templates/similarity-search.html官方实战指南docs/en/guides/similarity-search.md包含完整上手步骤与问答FAQ测试覆盖tests/test_solutions.py三条用例分别验证后端检索、应用初始化和端到端查询。总结本文以ultralytics/solutions/similarity_search.py的 API 参考文档为主线完整拆解了VisualAISearch与SearchApp两个类前者以 CLIP 视觉-语言模型为核心、通过 L2 归一化与 NumPy 矩阵乘法实现零样本语义检索与索引缓存后者以 Flask 提供即时可用的 Web 交互界面。结合build_text_model的模型加载机制、load_or_build_index的缓存策略、search的阈值过滤逻辑以及仓库测试用例的验证你可以用「图片目录 一句话查询」的方式快速落地一套无需标注、无需训练的语义图像搜索引擎——把data指向自己的图片目录即可完成索引并在其上继续叠加仓库内其他 Ultralytics Solutions 能力扩展完整的计算机视觉工作流。【免费下载链接】ultralyticsUltralytics YOLO26, YOLO11, YOLOv8 — object detection, instance segmentation, semantic segmentation, image classification, pose estimation, object tracking项目地址: https://gitcode.com/GitHub_Trending/ul/ultralytics创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
使用 Ultralytics 构建基于 CLIP 的语义图像检索：VisualAISearch 与 SearchApp 全解析
使用 Ultralytics 构建基于 CLIP 的语义图像检索VisualAISearch 与 SearchApp 全解析【免费下载链接】ultralyticsUltralytics YOLO26, YOLO11, YOLOv8 — object detection, instance segmentation, semantic segmentation, image classification, pose estimation, object tracking项目地址: https://gitcode.com/GitHub_Trending/ul/ultralytics本文围绕 Ultralytics 仓库中ultralytics/solutions/similarity_search.py模块的 API 参考文档展开系统讲解基于 OpenAI CLIP 的零样本语义图像检索解决方案。你将掌握VisualAISearch与SearchApp两个类的设计原理、全部核心方法与参数学会用几行代码把本地图片目录变成可按自然语言检索的语义搜索引擎含 Flask Web 界面并通过仓库源码与测试用例理解其底层实现机制。模块定位一个类打通「图像嵌入 相似度检索 Web 界面」在 Ultralytics 的 solutions 家族中similarity_search.py承担的是跨模态语义检索职责——它不同于目标检测、分割等定位类任务而是解决「给一句自然语言描述找到图片库里语义最匹配的图像」这一类问题。从源码结构看similarity_search.py 定义了两个对外类类定位源码行号VisualAISearch语义检索的核心后端负责 CLIP 嵌入生成、索引构建与余弦相似度检索VisualAISearch 定义SearchApp基于 Flask 的 Web 前端封装为检索能力提供可视化交互界面SearchApp 定义两个类都在 ultralytics/solutions/init.py 中被导出因此用户可以直接通过from ultralytics import solutions后以solutions.VisualAISearch、solutions.SearchApp方式调用无需关心具体导入路径。工作原理CLIP 多模态嵌入 NumPy 余弦相似度similarity_search.py的模块级 docstring 明确定义了这套系统的核心思想利用 OpenAI CLIP 同时为图像与文本生成高质量嵌入使二者对齐到同一个语义空间再用 NumPy 余弦相似度完成快速检索见 VisualAISearch 类注释。整个检索链路可以拆成三个阶段编码阶段CLIP对图片目录中的每一张图调用 CLIP 视觉编码器生成图像嵌入对自然语言查询调用 CLIP 文本编码器生成文本嵌入。两类向量被投影到同一多模态语义空间因此可以直接做向量比较。索引阶段NumPy所有图像嵌入以float32堆叠成一个二维数组并做行级 L2 归一化后保存为embeddings.npy图像文件名保存为paths.npy。归一化后向量内积即等价于余弦相似度无需引入任何额外的向量数据库。检索阶段矩阵乘法一次查询嵌入与全量图像嵌入的矩阵乘法即可算出全部相似度分数排序后返回 Top-k 结果。模型加载链路build_text_model 与 CLIP 编码器VisualAISearch.__init__在构造时通过build_text_model(clip:ViT-B/32, deviceself.device)加载 CLIP 模型见 构造方法实现。其中build_text_model是 Ultralytics 在 ultralytics/nn/text_model.py 中提供的统一文本模型工厂variant 采用base:size格式解析如clip:ViT-B/32、mobileclip:s0当base clip时实例化CLIP(size, device)实际通过clip.load(size, devicedevice, download_root...)加载 OpenAI CLIP 预训练权重见 text_model.py 中的 CLIP 实现支持clip、mobileclip、mobileclip2三种 base其他取值会抛出ValueError。因此VisualAISearch的图像特征提取方法extract_image_feature与文本特征提取方法extract_text_feature本质上是对 CLIP 编码器的薄封装前者对Image.open(path)编码后者先tokenize再encode_text并统一.detach().cpu().numpy()转成 NumPy 向量见 相似度搜索方法实现。构造参数与环境依赖VisualAISearch的构造签名接受关键字参数官方 API 文档与 guides 指南给出的可配置项如下参数类型默认值说明datastrimages待索引与检索的图片目录路径devicestrcpuCLIP 推理设备如cpu、cuda、0强约束需要 PyTorch ≥ 2.4构造方法的第一条语句是硬性断言见 构造方法assert TORCH_2_4, fVisualAISearch requires torch2.4 (found torch{TORCH_VERSION})即VisualAISearch只有在 torch ≥ 2.4 时才可用。仓库测试用例同样通过pytest.mark.skipif(not TORCH_2_4, ...)对这一前提做条件跳过见 tests/test_solutions.py说明这是该功能既定的版本门槛而非可选建议。图片目录缺失时的自动下载当传入的data目录不存在时模块不会直接报错而是从 Ultralytics 官方资源地址下载示例图片集images.zip并解压到本地images目录后继续构建索引见 自动下载逻辑方便用户零准备体验完整检索流程。图片格式过滤load_or_build_index在遍历目录时会以IMG_FORMATS集合定义于 ultralytics/data/utils.py过滤非图片后缀文件并对单张图片编码失败的情况以LOGGER.warning跳过而非中断整个流程见 索引构建实现。核心 API 方法逐一解析extract_image_feature / extract_text_feature分别提取图像与文本的 CLIP 嵌入向量二者返回的 NumPy 数组经过 L2 归一化后可直接用于相似度比较见 特征提取方法。load_or_build_index索引缓存与重建机制这是性能设计的关键一环见 load_or_build_index 实现命中缓存直接加载如果当前目录下已存在embeddings.npy与paths.npy直接np.load载入打印Loading existing embeddings...并返回未命中则全量构建遍历data_dir中所有符合IMG_FORMATS的图片逐张提取特征向量与文件名无有效向量即报错若全部失败抛出RuntimeError(No image embeddings could be generated.)归一化后落盘np.vstack堆叠为float32二维数组经_normalize行级 L2 归一化分别np.save保存索引与路径打印Indexed N images.。由于默认缓存文件名是工作目录下的embeddings.npy/paths.npy首次构建后再次实例化同一目录数据会直接跳过耗时的编码阶段。_normalize让内积等于余弦相似度_normalize是静态方法将每行除以自身 L2 范数分母用np.maximum(..., 1e-12)防止除零注释明确说明归一化后「inner products equal cosine similarity」见 归一化方法。search(query, k, similarity_thresh)语义检索主入口search方法将一次检索压缩为三步线性代数运算见 search 实现def search(self, query: str, k: int 30, similarity_thresh: float 0.1) - list[str]: text_feat self._normalize(self.extract_text_feature(query).astype(float32)) scores self.index text_feat[0] # 余弦相似度嵌入已 L2 归一化 top_k np.argsort(scores)[::-1][: max(k, 0)] results [(self.image_paths[i], float(scores[i])) for i in top_k if scores[i] similarity_thresh] ...需要特别指出的是文档中search的三参数签名k30、similarity_thresh0.1来自模块 docstring 与源码实现而公开参数表仅列出data与device。k控制返回的最大结果数量similarity_thresh控制相似度下限过滤二者共同决定最终结果的精度与召回。检索结束后会把每条命中的文件名 | Similarity: 分数以 4 位小数格式打印到日志返回值是按相似度降序排列的图片文件名列表。类还实现了__call__因此searcher(a dog sitting on a bench)与searcher.search(...)两种写法等价见 直接调用接口。实战一以编程方式执行语义检索按官方 API 文档与指南的标准用法创建检索器并直接传入自然语言查询from ultralytics import solutions searcher solutions.VisualAISearch( dataimages, # 替换为你要索引的本地图片目录 devicecpu, # 可改为 cuda 或设备编号 0 以加速编码 ) results searcher(a dog sitting on a bench) # 日志输出示例 # Ranked Results: # - 000000546829.jpg | Similarity: 0.3269 # - 000000549220.jpg | Similarity: 0.2899 # - 000000517069.jpg | Similarity: 0.2761 # - 000000029393.jpg | Similarity: 0.2742 # - 000000534270.jpg | Similarity: 0.2680首次运行时若无images目录会自动下载示例图片集若已有该目录则自动构建并缓存索引。从这段代码可见整个「零样本、无需标注、无标签体系」的检索能力全部被封装在类内部——这正体现了零样本语义检索的核心优势不需要针对你的数据集做任何训练或打标签。仓库中的端到端测试验证了这一用法见 test_similarity_search_complete在临时目录生成两张随机224×224测试图构造检索器后以a red and white object查询并断言返回结果非空。另一条测试则使用包含 4 张狗的示例图片包进行真实语义查询见 test_similarity_search。实战二一键启动 Flask 语义检索 Web 应用SearchApp把上述后端能力封装为可直接运行的 Web 服务见 SearchApp 实现from ultralytics import solutions app solutions.SearchApp( dataimages, # 建议使用绝对路径详见下方注意事项 devicecpu, ) app.run(debugFalse) # 测试阶段可改为 debugTrueSearchApp的初始化过程值得展开构造时通过check_requirements(flask3.0.1)校验 Flask 版本再延迟导入flask内部创建VisualAISearch实例作为检索后端属性searcher以templates为模板目录、以图片目录的绝对路径作为静态目录并设置static_url_path/images使检索结果可通过/images/文件名在页面中显示通过add_url_rule(/, ...)将根路由GET/POST绑定到index视图POST 请求从表单读取query字段交给检索器结果渲染进similarity-search.html模板见 index 方法。图片路径警告指南文档特别提示——若使用自有图片data参数务必传绝对路径。因为 Flask 静态文件服务存在路径解析限制相对路径可能导致图片无法在网页上正常显示。仓库自带的页面模板 ultralytics/solutions/templates/similarity-search.html 实现了完整交互包含居中搜索框、搜索结果瀑布网格以及「Top 5 / Top 10 / Top 30」三个动态过滤按钮默认显示 Top 10整体采用响应式卡片网格布局。如果你对默认界面不满意该模板完全可作为自定义前端React/Vue 等时参考的后端 API 返回契约——index视图实际只是把结果文件名列表交给模板渲染。SearchApp的初始化能力在测试中被覆盖见 test_similarity_search_app_init断言实例具备searcher与run属性。运行前提与限制根据源码、测试与官方指南使用本方案前需确认以下前提前提说明依据torch ≥ 2.4构造时硬断言不满足直接抛错构造方法断言CLIP 依赖安装首次导入时会校验并安装ultralytics/CLIP等模型依赖text_model.pyFlask ≥ 3.0.1仅SearchApp需要SearchApp 构造设备可用性device经select_device自动选择 CPU/GPUultralytics/utils/torch_utils.py自有图片建议绝对路径保证 Web 界面图片正常展示指南文档数据规模检索采用全量矩阵乘法的精确暴力搜索数千级嵌入可实时响应超大图库需自行评估索引与检索实现此外模块在文件顶部设置os.environ[KMP_DUPLICATE_LIB_OK] TRUE见 similarity_search.py用于规避部分系统上 OpenMP 库冲突导致的运行崩溃——这也是在多线程/多库环境中容易遇到的坑点。源码级速查关键实现位置如果你希望深入研读这套语义检索解决方案的实现细节可按以下路径在仓库内定位核心模块ultralytics/solutions/similarity_search.pyVisualAISearchL20-L166与SearchAppL169-L222顶层导出ultralytics/solutions/init.pySearchApp、VisualAISearch均在此注册文本模型工厂ultralytics/nn/text_model.pybuild_text_model(clip:ViT-B/32, ...)的解析逻辑Web 前端模板ultralytics/solutions/templates/similarity-search.html官方实战指南docs/en/guides/similarity-search.md包含完整上手步骤与问答FAQ测试覆盖tests/test_solutions.py三条用例分别验证后端检索、应用初始化和端到端查询。总结本文以ultralytics/solutions/similarity_search.py的 API 参考文档为主线完整拆解了VisualAISearch与SearchApp两个类前者以 CLIP 视觉-语言模型为核心、通过 L2 归一化与 NumPy 矩阵乘法实现零样本语义检索与索引缓存后者以 Flask 提供即时可用的 Web 交互界面。结合build_text_model的模型加载机制、load_or_build_index的缓存策略、search的阈值过滤逻辑以及仓库测试用例的验证你可以用「图片目录 一句话查询」的方式快速落地一套无需标注、无需训练的语义图像搜索引擎——把data指向自己的图片目录即可完成索引并在其上继续叠加仓库内其他 Ultralytics Solutions 能力扩展完整的计算机视觉工作流。【免费下载链接】ultralyticsUltralytics YOLO26, YOLO11, YOLOv8 — object detection, instance segmentation, semantic segmentation, image classification, pose estimation, object tracking项目地址: https://gitcode.com/GitHub_Trending/ul/ultralytics创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
