CV / CLIP

CLIP ViT-B/32

reComputer RK3588

在 reComputer RK3576 和 RK3588 上通过 RKNN 加速的 OpenAI CLIP ViT-B/32 图文匹配模型。

36 次下载

精度

RKNN

选择你正在使用的设备，设置指南和文档将相应更新。

平台

推理引擎

快速开始

Armbian 26.8.7 Gnome 及更新版本（启用 OTA overlayroot）： 运行容器前请配置 Docker 存储以避免 overlay 挂载错误。

部署

sudo docker run --rm --privileged --net=host \
  -e PYTHONUNBUFFERED=1 -e RKNN_LOG_LEVEL=0 \
  -v /proc/device-tree/compatible:/proc/device-tree/compatible:ro \
  ghcr.io/seeed-projects/recomputer-rk-cv/rk3588-clip:latest

REST API

使用 REST API 进行推理。复制以下命令。

Curl

curl http://localhost:8080/v1/chat/completions -d '{
  "model": "clip-rknn",
  "messages": [{"role": "user", "content": "Hello"}]
}'

Python

import requests

resp = requests.post(
    "http://localhost:8080/v1/chat/completions",
    json={"model": "clip-rknn", "messages": [{"role": "user", "content": "Hello"}]},
)
print(resp.json())

模型详情

Armbian 26.8.7 Gnome 及更新版本（启用 OTA overlayroot）： 运行容器前请配置 Docker 存储以避免 overlay 挂载错误。

快速开始

1. 安装 Docker

在开发板上运行以下命令安装 Docker：

bash

# Download installation script
curl -fsSL https://get.docker.com -o get-docker.sh
# Install using Aliyun mirror source
sudo sh get-docker.sh --mirror Aliyun
# Start Docker and enable auto-start on boot
sudo systemctl enable docker
sudo systemctl start docker

2. 运行项目（一条命令，双模式预览）

本项目通过 Web 浏览器提供零样本图像分类和自然语言图像检索。图像编码器和文本编码器均作为 RKNN 模型运行。

步骤 A：拉取镜像

bash

sudo docker pull ghcr.io/Seeed-Projects/recomputer-rk-cv/rk3588-clip:latest
sudo docker pull ghcr.io/Seeed-Projects/recomputer-rk-cv/rk3576-clip:latest

步骤 B：一键运行

适用于 RK3588:

bash

sudo docker run --rm --privileged --net=host \
    -e PYTHONUNBUFFERED=1 \
    -e RKNN_LOG_LEVEL=0 \
    -v /proc/device-tree/compatible:/proc/device-tree/compatible:ro \
    ghcr.io/seeed-projects/recomputer-rk-cv/rk3588-clip:latest

访问地址： http://<Board_IP>:8000

适用于 RK3576:

bash

sudo docker run --rm --privileged --net=host \
    -e PYTHONUNBUFFERED=1 \
    -e RKNN_LOG_LEVEL=0 \
    -v /proc/device-tree/compatible:/proc/device-tree/compatible:ro \
    ghcr.io/seeed-projects/recomputer-rk-cv/rk3576-clip:latest

访问地址： http://<Board_IP>:8000

3. 命令行推理

使用候选提示词对图像进行分类：

bash

python inference.py --platform rk3576 --model_dir model \
    --file samples/dog_224x224.jpg \
    --prompts 'a photo of a dog|a photo of a cat'

使用自然语言查询对多张图像进行排序：

bash

python inference.py --platform rk3576 --model_dir model \
    --files image1.jpg image2.jpg --query 'a red car' --topk 2

在 RK3588 源目录中运行时，请使用 --platform rk3588。

🔌 API 文档

服务分别提供零样本分类和文本到图像检索的 REST 接口。交互式 OpenAPI 文档位于 http://<Board_IP>:8000/docs。

1. 零样本图像分类

端点： POST /api/models/clip/predict

请求参数（Multipart/Form-Data）：

file：必填图像文件。图像会预处理为 224 x 224。
prompts：必填候选标签，可使用 JSON 数组、换行分隔文本或 | 分隔文本。最多接受 32 个标签。
topk：可选返回标签数，范围为 1 至 32，默认值为 5。

使用示例：

bash

curl -X POST "http://127.0.0.1:8000/api/models/clip/predict" \
    -F 'file=@samples/dog_224x224.jpg' \
    -F $'prompts=a photo of a dog\na photo of a cat' \
    -F 'topk=2'

响应格式（JSON）：

json

{
  "success": true,
  "model": "clip",
  "platform": "rk3576",
  "inference_time_ms": 58.2,
  "result": {
    "mode": "classification",
    "image": {"width": 224, "height": 224},
    "candidate_count": 2,
    "predictions": [
      {"text": "a photo of a dog", "score": 0.97}
    ]
  }
}

2. 自然语言图像检索

端点： POST /api/models/clip/retrieve

请求参数（Multipart/Form-Data）：

files：必填重复字段，包含 1–32 张图像。
text：必填自然语言查询。
topk：可选返回匹配项数，范围为 1 至 32。

使用示例：

bash

curl -X POST "http://127.0.0.1:8000/api/models/clip/retrieve" \
    -F 'files=@image1.jpg' \
    -F 'files=@image2.jpg' \
    -F 'text=a red car' \
    -F 'topk=2'

转换后的文本编码器使用固定的 20 词元输入，因此提示词和查询应保持简洁。相似度使用归一化后的图像和文本特征计算。

3. 系统配置接口

获取当前配置

端点： GET /api/config
响应： {"topk": 5}

更新配置

bash

curl -X POST "http://127.0.0.1:8000/api/config" \
    -H 'Content-Type: application/json' \
    -d '{"topk": 3}'

使用 GET /api/health 检查当前平台、已加载的 RKNN 文件和运行时能力。

🛠️ 开发者指南（生产环境建议）

代码说明

web_service.py：
- Web API：提供浏览器界面、预测 API、检索 API、配置 API 和健康状态。
- 请求校验：将上传大小限制为 64 MB，检索图像数限制为 32 张。
task_runtime.py：
- 图像处理：将输入缩放为 224 x 224 并归一化图像特征。
- 文本处理：使用 clip_vocab.h 对提示词分词，并应用转换后模型固定的 20 词元输入。
- 排序：计算归一化余弦相似度，用于分类和检索。
inference.py：提供单次命令行分类和检索。

模型文件

组件	文件
图像编码器	`model/clip_images.rknn`
文本编码器	`model/clip_text.rknn`
词表	`model/clip_vocab.h`

修改模型

将兼容的图像和文本编码器 .rknn 文件放入 model/ 目录，并保留上表中的文件名。
两个编码器和词表应来自同一转换套件。
部署前确认替换后仍满足 224 x 224 图像输入和固定 20 词元文本输入约定。

上游项目目前为每个平台提供一套模型。这两个编码器是流水线组件，而不是可选的量化规格；此版本没有模型变体参数。

构建本地镜像

在 reComputer-RK-CV 根目录运行：

bash

docker build -f docker/rk3576/clip.dockerfile \
    -t rk3576-clip:local src/rk3576_clip

docker build -f docker/rk3588/clip.dockerfile \
    -t rk3588-clip:local src/rk3588_clip

输入与输出

输入：图像与候选提示词，或最多 32 张图像与文本查询。输出：归一化相似度分数和排序结果。