多模态决策实战:clef-4bit图片与视频输入完整指南
多模态决策实战:clef-4bit图片与视频输入完整指南
clef-4bit 是运行在 Apple Silicon(MLX)上的多模态决策模型:Cloudflare Clef 27B 的 4-bit 量化版。它不是聊天模型,而是接收「当前状态 + 一组带类型的问题」——状态可以是文本、JSON、图片或视频——在单次前向推理中直接输出每个允许选项的概率。本指南带你从零完成 clef-4bit 的图片与视频输入实战。
🎯 认识 clef-4bit:一次推理输出全部答案
与"逐字生成"的聊天模型不同,clef-4bit 由视觉语言主干 + 联合 schema 决策头组成(见 joint_head.safetensors 与 joint_head_config.json),一次前向就能同时回答多个问题,非常适合分诊、审核、路由等"打标签"场景。
它支持 3 种问题类型:
| 类型 | 含义 | 答案形式 |
|---|---|---|
noul |
是/否判断 | true 的概率(0~1) |
choice |
多选一(带选项说明) | 最优选项 + 置信度 + 各选项概率 |
score |
有序评分档 | 加权分数 + 置信度 + 各档概率 |
📌 硬件要求(27B 4-bit):下载约 16.3 GB,峰值内存约 17.1~19.6 GB,建议 32 GB 内存的 Mac;M5 Max 上 1k token 约 1.4 秒、16k token 约 26 秒。详细对比见 README.md。
🚀 快速上手:安装与加载
先安装依赖(无需 PyTorch):
pip install "mlx-vlm>=0.7.4,<0.8" huggingface_hub
下载模型(二选一):
# 方式一:Hub 快照下载(推荐)
hf download mlx-community/clef-4bit --quiet
# 方式二:git clone
git clone https://gitcode.com/hf_mirrors/mlx-community/clef-4bit
用自带的 clef_mlx.py 加载模型(注意:不要用 mlx_lm.generate / LM Studio / Ollama 加载,它们只加载主干,输出无意义文本):
import sys
from huggingface_hub import snapshot_download
path = snapshot_download("mlx-community/clef-4bit")
sys.path.insert(0, path)
import clef_mlx
model = clef_mlx.load(path)
🖼️ 图片输入实战
Python 中传入 PIL 图片
图片放在请求的 images 字段,最常见的是审核类任务(例如判断小票金额是否清晰):
from PIL import Image
response = model.predict({
"state": {"task": "Review the attached receipt."},
"images": [Image.open("receipt.jpg")],
"questions": {
"legible": {"type": "noul", "instructions": "Is the receipt total legible?"}
},
})
print(response)
一次可以传多张图片(images 是一个列表)。图片的 token 排布与官方 PyTorch 实现完全对齐(预处理见 clef_mlx.py#L131-L176),配置来自 processor_config.json。
命令行直接带图
clef_mlx.py 自带 CLI,--image 可重复使用,多个文件即多图:
python clef_mlx.py predict \
--state "Checkout has been failing for every customer." \
--questions '{"urgent": {"type": "noul", "instructions": "Is this urgent?"}}' \
--image photo.jpg --image error_screen.png
输出为标准 JSON 响应,可直接被脚本消费。
🎬 视频输入实战
视频放在 videos 字段,格式为帧数组(numpy,形状 (N, H, W, 3),多段视频可放多个数组)。
import numpy as np
from PIL import Image
frames = np.load("clip_frames.npy") # (N, H, W, 3) 的帧序列
response = model.predict({
"state": "The attached clip shows our kiosk in the lobby.",
"videos": [frames],
"questions": {
"broken": {"type": "noul", "instructions": "Is the kiosk unresponsive in the clip?"},
"severity": {"type": "score", "criteria": ["None", "Minor", "Major"]}
},
})
框架内部会自动做均匀抽帧(见 clef_mlx.py#L107-L120),关键参数:
| 参数 | 默认值 | 说明 |
|---|---|---|
fps |
2 | 目标抽帧率 |
source_fps |
24 | 源视频帧率假设 |
min_frames / max_frames |
4 / 768 | 抽帧上下限 |
这些参数都可通过请求中的 media_kwargs 覆盖;do_sample_frames: false 则使用全部帧。
⚠️ 注意:视频只支持在 Python / CLI 中传入,HTTP 服务接口不支持视频(会直接报错提示)。
🌐 进阶:起一个本地 SystemOne 服务
一行命令把决策模型挂成本地 API,现有 SystemOne 客户端可直接指向你的 Mac:
python clef_mlx.py serve --port 8000
curl http://127.0.0.1:8000/v1/systemone -H "Content-Type: application/json" -d '{
"model": "clef",
"state": "New support ticket attached.",
"images": ["data:image/jpeg;base64,/9j/4AAQ..."],
"questions": {"urgent": {"type": "noul", "instructions": "Is this urgent?"}}
}'
- 图片在 HTTP 中用字符串表示:data URL、base64 或 http(s) 地址均可;
- 服务默认只绑定
127.0.0.1且无鉴权,请保持默认或自行加代理; - 请求在 GPU 上逐条执行,无批量能力。
⚠️ 常见坑与限制速查
| 坑 | 说明 |
|---|---|
| 当成聊天模型用 | mlx_lm.generate、LM Studio、Ollama 输出是无意义文本,必须用 clef_mlx.py |
| 图文混传 | 同一条记录里图片和视频二选一;多张图、多段视频都可以 |
| 超长输入 | 默认截断到 16,384 token;传 truncate=False 可改为抛 ContextTooLong 错误 |
| 无批量 | 每次调用只处理一条记录,请求串行执行 |
| 版本漂移 | 建议锁定 mlx-vlm 0.7.x(实测 0.7.4),版本不符时加载器会打印警告 |
📁 仓库关键文件速查
- 加载器 / CLI / 服务:clef_mlx.py
- 决策头权重(bf16,原样复制):joint_head.safetensors,结构配置 joint_head_config.json
- 主干配置(Qwen3.5 + 4-bit 量化参数):config.json
- 权重分片索引(共 3 个分片):model.safetensors.index.json
- 图像/视频处理器配置:processor_config.json
- 完整模型卡片与基准:README.md
按本指南完成图片与视频输入后,你就可以把 clef-4bit 接进客服分诊、工单审核、内容打标签等真实业务流程——一次推理,所有问题同时给出概率化的答案。