上一篇19-1《ViT 编码——图片是怎么变成视觉 token 的》下一篇19-3《视频帧与媒体模块默认不启用的 H.264》》真机实测通过本文实验已在 RK3588 板端实测完成2026-09方法学与原始记录见仓库 docs 与《实验脚本》目录。一句话导读vision_tokens 客户端预编码协议encode_media_item 为多模态请求开 image_url、video_frames、vision_tokens 三条路板端 serve 实测缓存命中跳过 ViT、特征直注与字节数自校验的拒绝边界。关键词vision_tokens、客户端预编码、ViT、视觉 token、多模态1. 知识点图片上行还是特征上行19-1 实测板载 ViT 编码一张 64×64 要 ~295ms——这还只是 4 个 token 的小图。如果每个请求都在板上重算 ViT视觉就变成了真瓶颈。这篇讲引擎的折中方案vllm_server.c的encode_media_item给一条多模态请求开了三条路——image_url板端 ViT 128 位图片缓存、video_frames帧数组、以及vision_tokens客户端/上位机预编码直接跳过 ViT。三条路在板端 servemodel.vqf部署形态全部实测跑通日志锚点[VIS-CACHE] hit … skip ViT与[VIS-TOKENS] client-preprocess …都拿到了。多模态请求有两条截然不同的带宽账方案上行内容上行体积板端算力image_url板上 ViT压缩图片base64几十 KB 级每次 ~295ms64×64起步vision_tokens客户端预编码视觉特征 fp32n×2048×4B4 token≈32KB784 token≈6.4MB0板端只做注入账要这么算客户端的视觉算力是免费的浏览器/上位机往往有 GPU而板上 ViT 是稀缺资源。让客户端把图片编码成特征再上行板端就退化成收特征 → 拼接 prompt → prefill。代价是特征体积随 token 数线性涨高分辨率大图会到 MB 级且客户端必须能跑同一套ViT——这正是协议要定义得极严的原因grid、fp32 布局、字节数、可选 DeepStack任何一处对不上就直接拒绝而不是拿错特征硬跑。同一套encode_media_item里还藏了第三条省钱路图片缓存。image_url的原始字节算 128 位 FNV-1a 键命中就直接回放上次的视觉 token[VIS-CACHE] hit … skip ViT。聊天里同一张图被引用多次是常态缓存让板端 ViT 只在第一次出现时付钱。2. 对应代码encode_media_item 的三路分发vllm_server.c的encode_media_item1608–1793 行按 content part 类型分发读协议注释原文1618–1620 行/* 客户端预处理模式vision_tokens part浏览器在本机算好的视觉特征 * 直接接收跳过 ViT 编码。协议 v1tokens_b64 base64(fp32 LE, n*d) * ds_b64可选 base64 数组每条 n*dgrid [gt, gh, gw] 合并后网格。 */2.1 分支一vision_tokens1621–1688 行const VJson *vt vjson_obj_get(part, vision_tokens); if (vt) { grid 必须为数组 [gt, gh, gw]gt/gh/gw ≥ 1 且 gt*gh*gw ≤ 4096 // 1623-1628 n gt*gh*gw tokens_b64 → base64 解码 → 字节数必须 n*d*sizeof(float) // 1633-1636 memcpy(vis_all …); grids[n_regions] (gt, gh, gw); // 1646-1651 ds_b64 可选≤3 条每条也必须 n*d*4→ ds_accum_append_rows // 1655-1682 fprintf(stderr, [VIS-TOKENS] client-preprocess n%d d%d ds%d grid[…]); }要点协议用字节数自校验。dLLM 隐宽 2048是板端说了算的客户端特征宽度差一维、条数差一条tlen ! need直接return -1。DeepStack 是可选字段1653–1654 行注释说得很直白缺省则 n_ds0prefill 跳过注入输出与带 ds 路径不一致客户端须自行负责——协议允许降级但把语义责任写在注释里。2.2 分支二image_url 图片缓存1691–1742 行url → decode_data_url只认 data:…;base64, 形式 // 1693-1696 h1/h2 FNV-1a128(原始字节) // 1698-1701图片键 rgb media_load_image_memory(raw, …) // stb 解码 if (vis_cache_apply(命中)) { …skip ViT… return; } // 1706-1714 n st_vision_encode_image(vis, rgb, w, h); // 171519-1 的八步 grids [1, gh grid_h/vis_merge, gw grid_w/vis_merge] // 1719-1724 vis_cache_store(…); // 1738存盘待回放缓存键是图片原始字节的 128 位 FNV-1a——同一张图换个尺寸/换个像素就换键命中即回放上次编码出的 token grid DeepStack完全跳过 ViT。2.3 分支三video_frames1744–1791 行video_frames是 base64 data URL 的数组每帧一张图解码后要求全部帧同尺寸1762–1763交给st_vision_encode_video沿时间维 patch19-1 的 temporal2grid 的gt n_frames_eff。这是帧序列语义的入口至于帧序列从哪来19-3 会讲它和 H.264 模块的关系。3. 改动后果serve 上四条请求实测实测口径RK3588 / aarch64 / Release / 2026-09-07。部署形态--serve --model 2B 目录自动加载model.vqf含 27 个v_*视觉张量。客户端从 x86 主机发 HTTP。3.1 模型就绪与协议日志[SERVE] vision encoder ready (VQF mmap, ViT 24 layers, hidden1024) [SERVE] model ready: …/Qwen3-VL-2B-Instruct (wmode0, vision1)serve 路径的视觉权重来自VQF mmap不是 19-1 CLI 的 safetensors 直读这印证了 17 篇的结论model.vqf把 ViT 的 Q8/F32 张量一并固化了。3.2 图像三条路的实测对比64×64 BMP 渐变图base64 data URL16,456 字节同一 prompt 连发① 首次/缓存未命中换 1 个像素触发 ttft_ms ≈ 769 / 797 ViT 编码 prefill串行 ② 同图第二次缓存命中 [VIS-CACHE] hit (64x64, 4 vis tokens, skip ViT) ttft_ms ≈ 297 / 301 纯 prefill无编码 ③ vision_tokens 零特征grid[1,2,2]n4, d2048 [VIS-TOKENS] client-preprocess n4 d2048 ds0 grid[1,2,2] ttft_ms ≈ 617 无编码但注入 prefill 比纯文本略高诚实解读三条缓存命中省掉的是 ViT 整段①−② 的差值 ≈0.47s是解码→编码→存储的净增量。注意它比 19-1 CLI 单测的 295ms 大——serve 里编码发生在请求线程、要叠加上解码/分配/首请求页故障等成本两次测量没有单独插桩精确拆分留给 Day 28 性能方法论这里只报命中 ~0.30s / 未命中 ~0.77–0.80s两个可直接复现的数字返回体带逐段时序image/vtok 响应含metricsttft_ms/tpot_ms/prefill_ms/total_ms这是引擎给上层做性能观测的现成钩子vision_tokens 只验证了协议与管线本实验发的特征全是 0板端照常解析、校验、注入并生成了一段看图说话——但那是零特征喂出来的幻觉文本不代表图像语义。协议链路base64→字节数校验→grid→DeepStack 可选→prefill被完整走过并返回 200这层结论是硬的零特征也能出活反过来恰好证明如果你把客户端特征传错模型会一本正经地胡说——这正是 §2.1 里客户端须自行负责那条注释的现实意义。3.3 一个真实回答样本image_urlViT 真编码content:这张渐变图的主色调是紫色。 metrics: prompt_tokens28 ttft_ms301 tpot_ms55 tok_s≈12.6文本基线同模型同板也正常关于红隼鸟的中文回答完整且正确。注意同图两次请求①②因采样路径不同给出的颜色描述并不一致本文不做图像理解质量评测只把编码/缓存/注入/生成这条链路是否跑通当作结论。4. 学员调试任务A 档x86 客户端 板端 serve复刻 3.2 的三条请求确认日志锚点[VIS-CACHE] hit与[VIS-TOKENS] client-preprocess出现修改vision_tokens的d或n使其与板端不符确认请求被return -1拒绝对同一张图连续发两次image_url对比两次ttft_ms的差值。
第 19-2 篇：vision_tokens 客户端预编码协议
上一篇19-1《ViT 编码——图片是怎么变成视觉 token 的》下一篇19-3《视频帧与媒体模块默认不启用的 H.264》》真机实测通过本文实验已在 RK3588 板端实测完成2026-09方法学与原始记录见仓库 docs 与《实验脚本》目录。一句话导读vision_tokens 客户端预编码协议encode_media_item 为多模态请求开 image_url、video_frames、vision_tokens 三条路板端 serve 实测缓存命中跳过 ViT、特征直注与字节数自校验的拒绝边界。关键词vision_tokens、客户端预编码、ViT、视觉 token、多模态1. 知识点图片上行还是特征上行19-1 实测板载 ViT 编码一张 64×64 要 ~295ms——这还只是 4 个 token 的小图。如果每个请求都在板上重算 ViT视觉就变成了真瓶颈。这篇讲引擎的折中方案vllm_server.c的encode_media_item给一条多模态请求开了三条路——image_url板端 ViT 128 位图片缓存、video_frames帧数组、以及vision_tokens客户端/上位机预编码直接跳过 ViT。三条路在板端 servemodel.vqf部署形态全部实测跑通日志锚点[VIS-CACHE] hit … skip ViT与[VIS-TOKENS] client-preprocess …都拿到了。多模态请求有两条截然不同的带宽账方案上行内容上行体积板端算力image_url板上 ViT压缩图片base64几十 KB 级每次 ~295ms64×64起步vision_tokens客户端预编码视觉特征 fp32n×2048×4B4 token≈32KB784 token≈6.4MB0板端只做注入账要这么算客户端的视觉算力是免费的浏览器/上位机往往有 GPU而板上 ViT 是稀缺资源。让客户端把图片编码成特征再上行板端就退化成收特征 → 拼接 prompt → prefill。代价是特征体积随 token 数线性涨高分辨率大图会到 MB 级且客户端必须能跑同一套ViT——这正是协议要定义得极严的原因grid、fp32 布局、字节数、可选 DeepStack任何一处对不上就直接拒绝而不是拿错特征硬跑。同一套encode_media_item里还藏了第三条省钱路图片缓存。image_url的原始字节算 128 位 FNV-1a 键命中就直接回放上次的视觉 token[VIS-CACHE] hit … skip ViT。聊天里同一张图被引用多次是常态缓存让板端 ViT 只在第一次出现时付钱。2. 对应代码encode_media_item 的三路分发vllm_server.c的encode_media_item1608–1793 行按 content part 类型分发读协议注释原文1618–1620 行/* 客户端预处理模式vision_tokens part浏览器在本机算好的视觉特征 * 直接接收跳过 ViT 编码。协议 v1tokens_b64 base64(fp32 LE, n*d) * ds_b64可选 base64 数组每条 n*dgrid [gt, gh, gw] 合并后网格。 */2.1 分支一vision_tokens1621–1688 行const VJson *vt vjson_obj_get(part, vision_tokens); if (vt) { grid 必须为数组 [gt, gh, gw]gt/gh/gw ≥ 1 且 gt*gh*gw ≤ 4096 // 1623-1628 n gt*gh*gw tokens_b64 → base64 解码 → 字节数必须 n*d*sizeof(float) // 1633-1636 memcpy(vis_all …); grids[n_regions] (gt, gh, gw); // 1646-1651 ds_b64 可选≤3 条每条也必须 n*d*4→ ds_accum_append_rows // 1655-1682 fprintf(stderr, [VIS-TOKENS] client-preprocess n%d d%d ds%d grid[…]); }要点协议用字节数自校验。dLLM 隐宽 2048是板端说了算的客户端特征宽度差一维、条数差一条tlen ! need直接return -1。DeepStack 是可选字段1653–1654 行注释说得很直白缺省则 n_ds0prefill 跳过注入输出与带 ds 路径不一致客户端须自行负责——协议允许降级但把语义责任写在注释里。2.2 分支二image_url 图片缓存1691–1742 行url → decode_data_url只认 data:…;base64, 形式 // 1693-1696 h1/h2 FNV-1a128(原始字节) // 1698-1701图片键 rgb media_load_image_memory(raw, …) // stb 解码 if (vis_cache_apply(命中)) { …skip ViT… return; } // 1706-1714 n st_vision_encode_image(vis, rgb, w, h); // 171519-1 的八步 grids [1, gh grid_h/vis_merge, gw grid_w/vis_merge] // 1719-1724 vis_cache_store(…); // 1738存盘待回放缓存键是图片原始字节的 128 位 FNV-1a——同一张图换个尺寸/换个像素就换键命中即回放上次编码出的 token grid DeepStack完全跳过 ViT。2.3 分支三video_frames1744–1791 行video_frames是 base64 data URL 的数组每帧一张图解码后要求全部帧同尺寸1762–1763交给st_vision_encode_video沿时间维 patch19-1 的 temporal2grid 的gt n_frames_eff。这是帧序列语义的入口至于帧序列从哪来19-3 会讲它和 H.264 模块的关系。3. 改动后果serve 上四条请求实测实测口径RK3588 / aarch64 / Release / 2026-09-07。部署形态--serve --model 2B 目录自动加载model.vqf含 27 个v_*视觉张量。客户端从 x86 主机发 HTTP。3.1 模型就绪与协议日志[SERVE] vision encoder ready (VQF mmap, ViT 24 layers, hidden1024) [SERVE] model ready: …/Qwen3-VL-2B-Instruct (wmode0, vision1)serve 路径的视觉权重来自VQF mmap不是 19-1 CLI 的 safetensors 直读这印证了 17 篇的结论model.vqf把 ViT 的 Q8/F32 张量一并固化了。3.2 图像三条路的实测对比64×64 BMP 渐变图base64 data URL16,456 字节同一 prompt 连发① 首次/缓存未命中换 1 个像素触发 ttft_ms ≈ 769 / 797 ViT 编码 prefill串行 ② 同图第二次缓存命中 [VIS-CACHE] hit (64x64, 4 vis tokens, skip ViT) ttft_ms ≈ 297 / 301 纯 prefill无编码 ③ vision_tokens 零特征grid[1,2,2]n4, d2048 [VIS-TOKENS] client-preprocess n4 d2048 ds0 grid[1,2,2] ttft_ms ≈ 617 无编码但注入 prefill 比纯文本略高诚实解读三条缓存命中省掉的是 ViT 整段①−② 的差值 ≈0.47s是解码→编码→存储的净增量。注意它比 19-1 CLI 单测的 295ms 大——serve 里编码发生在请求线程、要叠加上解码/分配/首请求页故障等成本两次测量没有单独插桩精确拆分留给 Day 28 性能方法论这里只报命中 ~0.30s / 未命中 ~0.77–0.80s两个可直接复现的数字返回体带逐段时序image/vtok 响应含metricsttft_ms/tpot_ms/prefill_ms/total_ms这是引擎给上层做性能观测的现成钩子vision_tokens 只验证了协议与管线本实验发的特征全是 0板端照常解析、校验、注入并生成了一段看图说话——但那是零特征喂出来的幻觉文本不代表图像语义。协议链路base64→字节数校验→grid→DeepStack 可选→prefill被完整走过并返回 200这层结论是硬的零特征也能出活反过来恰好证明如果你把客户端特征传错模型会一本正经地胡说——这正是 §2.1 里客户端须自行负责那条注释的现实意义。3.3 一个真实回答样本image_urlViT 真编码content:这张渐变图的主色调是紫色。 metrics: prompt_tokens28 ttft_ms301 tpot_ms55 tok_s≈12.6文本基线同模型同板也正常关于红隼鸟的中文回答完整且正确。注意同图两次请求①②因采样路径不同给出的颜色描述并不一致本文不做图像理解质量评测只把编码/缓存/注入/生成这条链路是否跑通当作结论。4. 学员调试任务A 档x86 客户端 板端 serve复刻 3.2 的三条请求确认日志锚点[VIS-CACHE] hit与[VIS-TOKENS] client-preprocess出现修改vision_tokens的d或n使其与板端不符确认请求被return -1拒绝对同一张图连续发两次image_url对比两次ttft_ms的差值。