clip.cpp

纯 C/C++ 实现的 CLIP 推理，无额外依赖

说明

这是由 OpenAI 开发的知名 CLIP 模型的无依赖实现，得益于 GGML 的出色工作。你可以使用它来处理来自 OpenAI 和 LAION 的 Transformers 格式 CLIP 模型。

动机

CLIP 被广泛应用于语义图像搜索、零样本图像分类等多种任务。它也是 Stable Diffusion 以及新兴的大规模多模态模型（LMM）领域的一部分。本仓库旨在为基于此类模型的应用程序提供支持，特别是在计算或内存受限的设备上运行。经过 4 位量化后的 CLIP 模型仅需 85.6 MB！

特性

• 借助 ggml，实现无依赖、轻量级的推理。
• 支持 4 位、5 位和 8 位量化。
• 支持 仅文本、仅视觉 以及 双塔 模型变体的推理。在某些情况下，例如用于大型多模态模型的编码器，或者构建和搜索语义图像数据库时，单独使用某一模态可能更为合适。
• 无依赖的 Python 绑定，无需任何大型第三方库。不需要 NumPy、TensorFlow、PyTorch、ONNX 等，实际上仅需标准 Python 库即可。

与大型机器学习框架相比，clip.cpp 的启动时间更短，因此非常适合冷启动问题较为突出的无服务器部署场景。

最新动态

• 2024年1月27日：Clojure 绑定可用，详见 clip.clj。
• 2023年9月27日：clip.cpp 现在采用 GGUF 格式的全新模型文件结构。这是一个破坏性变更，请参阅下方了解更多信息。
• 2023年9月14日：所有函数现已兼容 C 语言。zsl 示例已更新，以匹配 Hugging Face 零样本管道中的行为。
• 2023年9月11日：引入 Python 绑定。
• 2023年7月12日：支持批量图像编码推理。
• 2023年7月11日：直接在 C++ 中实现语义图像搜索示例，详情见 [examples/image-search/README.md]。

破坏性变更

自 2023年9月27日起，clip.cpp 使用 GGUF 格式的全新模型文件结构。与旧版 .bin 文件兼容的最新提交是 05f2efd8081b8695e8174dea7a82116ece2fdf63。我们将不再提供对旧模型的向后兼容支持，建议您更新至新代码及模型文件。新结构不仅支持现有的 16 位浮点精度和 4 位量化，还新增了 32 位浮点精度、5 位和 8 位量化，并且可以分别存储仅文本和仅视觉的模型文件。

关于图像预处理的说明

PIL 在进行带抗锯齿的双通道卷积双三次插值缩放时，会应用抗锯齿处理。而在 PyTorch 中，抗锯齿是可选的。要实现与它们结果数值一致的预处理逻辑，需要特别注意。不过，我发现线性插值对于比较本实现与其他 Transformers 实现的嵌入向量，以及比较本实现与其它实现的嵌入向量来说，已经足够好。因此，在我们开发出合适的双三次插值之前，暂时就使用线性插值吧。

预转换模型

预转换模型可在 Hugging Face 上标记为 clip-cpp-gguf 的仓库中找到。如果您出于某种原因希望自行进行转换，请参阅下文。否则，您可以从上述链接下载所需的模型，然后直接跳转到编译部分。

模型转换

您可以将 OpenAI 和 LAION 提供的 Transformers 格式 CLIP 模型进行转换。据称，LAION 的模型在多项基准测试中表现优于 OpenAI 的模型，因此推荐使用 LAION 的模型。

1. 从 Hugging Face Hub 克隆模型仓库：

git lfs init

git clone https://huggingface.co/laion/CLIP-ViT-B-32-laion2B-s34B-b79K

2. 克隆本仓库：

git clone --recurse-submodules https://github.com/monatis/clip.cpp.git

cd clip.cpp/models

3. 如果尚未安装 PyTorch 和 Transformers 库，请先安装；否则可跳过此步骤：

pip install -r requirements.txt

4. 使用 models/convert_hf_to_gguf.py 将其转换为 GGUF 格式：

python convert_hf_to_gguf.py -m ../../CLIP-ViT-B-32-laion2B-s34B-b79K

输出的 CLIP-ViT-B-32-laion2B-s34B-b79K_ggml-model-f16.bin 文件位于上述命令中指定的模型目录中。

如需查看转换脚本的其他选项，请运行：

python convert_hf_to_gguf.py --help

编译

git clone --recurse-submodules https://github.com/monatis/clip.cpp.git

cd clip.cpp

mkdir build

cd build

cmake -DCLIP_NATIVE=ON ..

make

编译生成的二进制文件位于 ./bin 目录中。

注意：部分 Mac 设备报告的架构为 x86_64 而不是 arm64。如果遇到这种情况，请参阅 此处 的讨论。我在自己的 MacBook M2 Pro 上未能复现该问题，因此无法提供更多帮助。如果您知道可以在 CMakeLists.txt 中加入的解决方案，请在此处联系我：issues/24。

量化

clip.cpp 支持 q4_0、q4_1、q5_0、q5_1 和 q8_0 五种量化类型。您可以使用 ./bin/quantize 二进制工具，将 f32（推荐）或 f16 格式的模型量化为其中任意一种类型。

用法：./bin/quantize /path/to/ggml-model-f32.gguf /path/to/ggml-model-quantized.gguf type                              
  type = 2 - q4_0                                                                                                       
  type = 3 - q4_1                                                                                                       
  type = 6 - q5_0                                                                                                       
  type = 7 - q5_1                                                                                                       
  type = 8 - q8_0                                                                                                       

例如，您可以运行以下命令将模型量化为 q5_1：

./bin/quantize ./CLIP-ViT-B-32-laion2B-s34B-b79K/ggml-model-f32.gguf ./CLIP-ViT-B-32-laion2B-s34B-b79K/ggml-model-q5_1.gguf 7

现在您可以像使用 f16 格式的模型一样使用 ggml-model-q5_1.gguf。

使用方法

目前我们有4个示例：main、zsl 和 image-search。

1. main 仅用于演示 API 的使用，并可选择性地输出详细的计时信息。它简单地计算通过命令行参数传入的一张图片与一段文本之间的相似度。

用法：./bin/main [选项]

选项：  -h, --help：显示此消息并退出
  -m <路径>, --model <路径>：模型路径。默认值：models/ggml-model-f16.gguf
  -t N, --threads N：用于推理的线程数。默认值：4
  --text <文本>：要编码的文本。至少需要指定一个文本。
  --image <路径>：图像文件的路径。至少需要指定一个图像路径。
  -v <级别>, --verbose <级别>：控制详细程度。0 = 最低，2 = 最高。默认值：1

2. zsl 是一个零样本图像标注示例。它会根据提供的标签对一张图像进行标注。 命令行参数与 main 相同， 但必须指定多个 --text 参数来定义标签。

3. image-search 是一个基于 USearch 的语义图像搜索示例。 编译时需启用 CLIP_BUILD_IMAGE_SEARCH 选项，依赖项将由 CMake 自动下载：

mkdir build

cd build

cmake -DCLIP_BUILD_IMAGE_SEARCH=ON ..

make

更多信息和使用方法请参阅 examples/image-search/README.md。

4. extract 是一个工具，用于将向量提取为 NumPy 格式的 *.npy 文件。它同样无需任何依赖，即不需要安装 NumPy。 命令行参数与 main 和 zsl 相同，但可以传递一个或多个 --text 和/或 --image 参数。两者均可单独使用，也可组合使用。

注意：支持处理 *.txt 文件和图像目录的功能正在开发中。

Python 绑定

您可以在 Python 中使用 clip.cpp，而无需任何第三方库（除了标准 Python 库之外没有其他依赖）。 它使用 ctypes 加载动态链接库 (DLL)，以实现与 C/C++ 实现的接口。

如果您使用的是 X64 架构的 Linux 发行版，可以直接通过 Pip 安装并获得 AVX2 支持：

pip install clip_cpp

提供 Colab 笔记本以便快速实验：

如果您使用的是其他操作系统或架构， 或者希望利用 AVX2 以外的指令集支持（例如 AVX512）， 您可以从源代码编译。

您只需使用 -DBUILD_SHARED_LIBS=ON 选项进行编译，即可生成所需的 DLL。

mkdir build

cd build

cmake -DBUILD_SHARED_LIBS=ON ..

make

编译完成后，您将在 build 目录中找到 libclip.so 二进制文件。 更多信息和使用方法请参阅 examples/python_bindings/README.md。

基准测试

您可以使用基准测试工具比较不同检查点和量化类型的表现。

用法：./bin/benchmark <模型路径> <图像目录> <每个子目录的图像数量> [输出文件]

模型路径：GGML 格式的 CLIP 模型路径
图像目录：包含按类别命名的子目录的图像目录
每个子目录的图像数量：从每个子目录中最多读取的图像数量。如果为 0，则读取所有文件
输出文件：可选。如果指定，则将输出转储到该文件，而不是标准输出

有关基准测试的更多信息，请参阅 tests/README.md。

未来工作

• 集成最新版本的 GGML，并支持多种后端。

• [ ]

clip.cpp 快速上手指南

clip.cpp 是一个无依赖、轻量级的 CLIP 模型推理工具，基于 C/C++ 和 GGML 库实现。它支持 4-bit/5-bit/8-bit 量化，模型文件极小（4-bit 版本仅约 85.6 MB），非常适合在计算或内存受限的设备上运行，也适用于对冷启动敏感的 Serverless 部署。

环境准备

• 操作系统: Linux, macOS, Windows (需构建环境)
• 编译器: 支持 C++11 的编译器 (如 gcc, clang, msvc)
• 构建工具: cmake, make (Windows 下可用 nmake 或 mingw32-make)
• 模型转换依赖 (可选): 若需自行转换模型，需安装 Python 及 torch, transformers 库。

  pip install torch transformers
  

• Git LFS: 下载大模型文件时需要。

安装步骤

1. 克隆项目

git clone --recurse-submodules https://github.com/monatis/clip.cpp.git
cd clip.cpp

2. 编译构建

创建构建目录并编译：

mkdir build
cd build
cmake -DCLIP_NATIVE=ON ..
make

编译完成后，可执行文件位于 ./bin 目录中。

注意: 若在 macOS M1/M2 等设备上遇到架构识别问题，请参考项目 Issue 讨论调整 CMake 配置。

3. 获取模型

你可以直接从 HuggingFace 下载已转换好的 GGUF 格式模型（推荐），或自行转换。

• 下载预转换模型: 访问 HuggingFace Models 搜索带有 clip-cpp-gguf 标签的模型并下载 .gguf 文件。

• 自行转换模型 (可选): 若需使用特定模型，可先将 HuggingFace 上的 Transformers 格式模型转换为 GGUF 格式：

  # 假设已克隆目标模型仓库到 ../../CLIP-ViT-B-32-laion2B-s34B-b79K
  python models/convert_hf_to_gguf.py -m ../../CLIP-ViT-B-32-laion2B-s34B-b79K
  

4. 模型量化 (可选)

为了进一步减小体积和提升速度，可将模型量化为 4-bit/5-bit/8-bit：

# 用法：./bin/quantize <输入模型> <输出模型> <类型>
# 类型代码：2=q4_0, 3=q4_1, 6=q5_0, 7=q5_1, 8=q8_0
./bin/quantize ./ggml-model-f32.gguf ./ggml-model-q5_1.gguf 7

基本使用

编译后的 bin 目录包含多个示例工具，最常用的是 main（计算图文相似度）和 zsl（零样本图像分类）。

示例 1：计算图像与文本的相似度 (main)

计算一张图片与一段文本的匹配程度：

./bin/main \
  -m ../models/ggml-model-f16.gguf \
  --text "a photo of a dog" \
  --image ../images/dog.jpg

参数说明:

• -m: 模型路径 (默认 models/ggml-model-f16.gguf)
• --text: 需要编码的文本
• --image: 图片文件路径
• -t: 线程数 (默认 4)
• -v: 详细程度 (0-2)

示例 2：零样本图像分类 (zsl)

从多个标签中选择最符合图片内容的标签：

./bin/zsl \
  -m ../models/ggml-model-f16.gguf \
  --text "cat" \
  --text "dog" \
  --text "bird" \
  --image ../images/animal.jpg

注意：必须提供多个 --text 参数作为候选标签。

示例 3：提取向量 (extract)

将图像或文本编码为向量并保存为 NumPy 格式 (.npy)，无需安装 NumPy：

./bin/extract \
  -m ../models/ggml-model-f16.gguf \
  --text "hello world" \
  --image ../images/test.png

生成的向量文件可用于后续的语义搜索或其他任务。

Python 绑定 (可选)

clip.cpp 提供无第三方依赖的 Python 绑定。

• 直接安装 (Linux x64):

  pip install clip_cpp
  

• 源码编译启用共享库: 若需自定义指令集或在其他平台使用，编译时需开启共享库选项：

  cmake -DBUILD_SHARED_LIBS=ON ..
  make
  

  随后通过 ctypes 加载生成的 libclip.so (或对应平台的动态库) 即可在 Python 中调用。具体用法参见 examples/python_bindings/。