← 模型

VLM / Gemma 4

Gemma 4 E2B IT VLM

reComputer RK3588

Gemma 4 E2B IT VLM 将 RKLLM 语言模型与 RKNN 视觉编码器相结合，用于在 reComputer RK 开发板上进行图像理解。

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

快速开始

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

部署
sudo docker run --rm -d \
  --name recomputer-rk-vlm \
  --privileged \
  -p 8001:8001 \
  -v /dev:/dev \
  -e MODEL_KIND=vlm \
  ghcr.io/seeed-projects/recomputer-rk-llm/vlm/gemma-4-e2b-it:rk3588-w8a8

模型详情

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

在 reComputer RK 上部署 VLM

本通用指南适用于目录中列出的所有 VLM，包括 Qwen3.5。每个已发布的 VLM 镜像均包含与所选开发板和量化方式匹配的 RKLLM 语言模型和 RKNN 视觉编码器。

当前上游环境使用 RKLLM v1.3.1 和 RKNN 运行时 / Toolkit Lite 2 v2.5.0。新的或更新的模型定义必须先构建并发布，然后才能拉取其标签。请先构建环境镜像，然后重新构建所选模型镜像；请参阅上游仓库和 VLM 部署指南。

模型配置与 Gemma 4 预览

模型镜像会提供与其匹配的运行时设置。Qwen2.5-VL 和 Qwen3-VL 使用 VLM_IMAGE_SIZE=448。Gemma 4 使用 VLM_MODEL_FAMILY=gemma4、VLM_IMAGE_SIZE=480 和 RKLLM_EMBED_FLASH=1，并包含音频编码器。对于自定义构件，请遵循匹配的上游模型定义，不要混用模型配置或编码器文件。

Gemma 4 可以通过同一聊天补全端点接受 base64 WAV input_audio 内容部分。自定义 Gemma 4 部署必须通过 AUDIO_MODEL_FILE 或 AUDIO_MODEL_PATH 加载匹配的音频编码器；配置方法请参阅上游 VLM 部署指南。

已发布的镜像格式

text
ghcr.io/seeed-projects/recomputer-rk-llm/vlm/<model-id>:<platform>-<quantization>

W4A16-G128 镜像通常仅适用于 RK3576。RK3588 VLM 记录使用 W8A8。

要求

  • 运行 64 位 Linux 镜像的 reComputer RK3576 或 RK3588
  • 已安装 Docker 和 Docker Buildx
  • 可通过 /dev 访问 NPU
  • 开发板上的 8001 端口可用

VLM 镜像使用兼容 OpenAI 的 API，不提供终端交互式聊天。

运行已发布的 VLM

将 <model-id> 和 <quantization> 替换为所选的目录记录。

RK3576

bash
sudo docker run --rm -d \
  --name recomputer-rk-vlm \
  --privileged \
  -p 8001:8001 \
  -v /dev:/dev \
  -e MODEL_KIND=vlm \
  -e LOG_LEVEL=warning \
  ghcr.io/seeed-projects/recomputer-rk-llm/vlm/<model-id>:rk3576-<quantization>

RK3588

bash
sudo docker run --rm -d \
  --name recomputer-rk-vlm \
  --privileged \
  -p 8001:8001 \
  -v /dev:/dev \
  -e MODEL_KIND=vlm \
  -e LOG_LEVEL=warning \
  ghcr.io/seeed-projects/recomputer-rk-llm/vlm/<model-id>:rk3588-w8a8

健康检查和 API 文档

bash
curl http://localhost:8001/health
curl http://localhost:8001/docs
curl http://localhost:8001/redoc

OpenAI 多模态请求

服务器每次请求接受一张图片。请使用公开的 HTTP(S) URL 或 base64 数据 URL。

bash
curl -X POST http://localhost:8001/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "rkllm-vision",
    "messages": [{
      "role": "user",
      "content": [
        {"type": "text", "text": "Describe this image in detail."},
        {"type": "image_url", "image_url": {"url": "https://example.com/your-image.jpg"}}
      ]
    }],
    "stream": false
  }'

对于本地图片，请在 image_url.url 中填入数据 URL：

text
data:image/jpeg;base64,<base64-encoded-image>

流式多模态请求

bash
curl -N -X POST http://localhost:8001/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "rkllm-vision",
    "messages": [{
      "role": "user",
      "content": [
        {"type": "text", "text": "List the objects visible in this image."},
        {"type": "image_url", "image_url": {"url": "https://example.com/your-image.jpg"}}
      ]
    }],
    "stream": true
  }'

Python 客户端：

python
from openai import OpenAI

client = OpenAI(base_url="http://localhost:8001/v1", api_key="dummy-key")
response = client.chat.completions.create(
    model="rkllm-vision",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "Describe this image."},
            {"type": "image_url", "image_url": {"url": "https://example.com/your-image.jpg"}},
        ],
    }],
    max_tokens=128,
)
print(response.choices[0].message.content)

Cherry Studio

配置自定义的 OpenAI 兼容提供商：

  • API 主机：http://<board-ip>:8001/v1
  • API 密钥：任意值，例如 rkllm-local
  • 模型：rkllm-vision

选择提供商后附加图片。

故障排除

  • 不要混用来自不同开发板或标签的语言模型与视觉编码器构件。
  • 如果服务器报告缺少视觉模型，请确认 MODEL_KIND=vlm 和已发布的镜像标签。
  • 使用 sudo docker logs recomputer-rk-vlm 检查启动输出。

输入与输出

输入：文本、图像或 base64 WAV 音频。输出：通过兼容 OpenAI 的 API 生成的文本。