mlx-vlm 中 Prism Bonsai 三元 2-bit 文生图模型的推理路径与 API 实战指南【免费下载链接】mlx-vlmMLX-VLM is a package for inference and fine-tuning of Vision Language Models (VLMs) on your Mac using MLX.项目地址: https://gitcode.com/GitHub_Trending/ml/mlx-vlm本篇聚焦 mlx-vlm 中 Prism Bonsai 的完整推理链路它不走文本/VLM 的 token 生成路径而是走专用的图像生成image generation路径支持三通道输出——CLI 生成 PNG 文件、Python API 返回求值后的mx.array、OpenAI 兼容的/v1/images/generations服务端点。读完后你能够用命令行一键出图、用 Python 编程式生成并拿到 Base64 PNG还能通过 HTTP API 把它接入现有 OpenAI 风格的图像生成工作流同时理解三元 2-bit 量化矩阵乘法、Flow Matching 采样循环与显存淘汰策略的底层实现。模型概览Bonsai 在 mlx-vlm 中的定位Prism Bonsai 是一个文生图Text-to-image模型。在mlx-vlm中它被显式注册为图像生成模型而不是语言模型模型实现 BonsaiImageGenerationModel 上带有is_image_generation_model True与model_type bonsai类变量由统一的图像生成加载器 load_image_generation_model 按 model id 识别并分发。当前支持的模型与别名见 变体定义ModelAliasNotesprism-ml/bonsai-image-ternary-4B-mlx-2bitbonsai-ternary三元 2-bit MLX 模型从源码结构看bonsai-ternary只是别名表中的一个入口实际可识别的别名还包括bonsai、ternary、ternary-mlx、bonsai-ternary-mlx、2bit以及完整 repo id 本身小写形式。也就是说 CLI/Python 里写--model bonsai-ternary或--model 2bit都能命中同一个变体未识别的名称会抛出带有完整别名清单的ValueError。能力清单文生图生成基于三元ternaryMLX Bonsai 模型CLI 输出生成 PNG 文件Python API 输出返回求值后的mx.arrayOpenAI 兼容 API通过/v1/images/generations端点支持的图像尺寸为每边 256 到 2048 像素且宽、高都必须是 16 的倍数。这一约束直接来自 validate_dimensions任何一维超出[256, 2048]或非 16 的倍数都会立即抛出ValueErrorparse_size还支持WIDTH×HEIGHT全角乘号会被归一化为x的写法。运行前提三元量化的硬件依赖Bonsai 的 transformer 使用 2-bit 三元量化权重其矩阵乘法依赖 MLX 原生的量化 matmul kernel。pipeline 初始化 会调用_check_quantized_matmul做能力探测若当前 MLX 运行时不支持所需的 2-bit 量化矩阵乘路径会抛出RuntimeError提示使用 PrismML MLX 对应版本或包含该 kernel 的其他 MLX 构建。这是使用 Bonsai 前需要确认的第一件事。安装与模型下载pip install -U mlx-vlm模型默认通过huggingface_hub.snapshot_download按需下载到 Hugging Face 缓存。从 download.py 可以看到若未指定本地目录直接调用snapshot_download(repo_id...)落到 HF 缓存若指定了models_dir/local_dir会先创建目录再下载到指定位置默认落点为当前工作目录下的models/bonsai-image-4B-ternary-mlx私有访问可通过token参数或环境变量BONSAI_TOKEN传递下载完成后执行validate_model_layout校验快照必须包含以下 4 个必需文件缺失时会在错误信息中逐项列出transformer-packed-mflux/diffusion_pytorch_model.safetensors transformer-packed-mflux/quantization_config.json text_encoder-mlx-4bit/model.safetensors tokenizer/tokenizer.json你也可以直接把一个本地的 Bonsai 快照路径作为--model传入跳过下载。组件架构三个子模型 Flow Matching 采样从 weights.py 的加载逻辑可以确认一个完整的 Bonsai 快照由三部分组成文本编码器text_encoder-mlx-4bit下的 4-bit 量化 Qwen3 文本编码器hidden_size2560, intermediate_size9728加载后按bits4, group_size64量化扩散 Transformertransformer-packed-mflux下的打包权重dtypemx.bfloat16加载构造为 Flux2KleinFastTransformer走 Flux.2 Klein 的双流/单流块结构patch_size1、guidance_embedsFalseVAE 解码器从black-forest-labs/FLUX.2-small-decoder仓库按需拉取diffusion_pytorch_model.safetensors只映射decoder.*、post_quant_conv.*、bn.*权重并跳过.num_batches_tracked统计量、修正 4D 权重的通道顺序。采样循环在 BonsaiImage.generate_array 中实现是标准的 Flow Matching 离散化流程校验尺寸与steps 1、prompt 非空用Flux2Tokenizer 4-bit 文本编码器编码 prompt结果按(prompt, max_sequence_length, bucketed)三元组缓存由seed初始化打包的潜变量image_seq_len (height//16) * (width//16)用FlowMatchEulerDiscreteScheduler生成steps个时间步逐步预测噪声并scheduler.step更新潜变量每步mx.eval同步若guidance 1.0额外编码空白 prompt 作为负向嵌入做noise negative guidance * (noise - negative)的 CFG 合成最后把潜变量重排为[B, C, H, W]交给 VAE 解码解码结果经x/2 0.5 → clip → uint8归一化输出 HWC 的 RGBmx.array。generate_array的默认参数与文档示例一致seed42、steps4、width512、height512、guidance1.0——Bonsai 本身就是一个为极少步数4 步设计的高效模型。显存淘汰策略BonsaiRuntimeConfigBonsaiRuntimeConfig 提供一组针对内存紧张的 Apple Silicon 的开关参数默认值作用evict_text_encoderTrue文本编码完成后置空并gc.collect() mx.clear_cache()把内存让给 transformerevict_transformerFalse生成完成后清空 transformer/VAE 并释放缓存bucketed_seq_lenFalseprompt 编码时启用分桶序列长度tiled_vaeautoVAE 分块解码auto下当max(height, width)达到 2 倍 tile 边长时自动开启见 _resolve_tilingmax_sequence_length512prompt 编码的最大序列长度这些参数既能在BonsaiImage.from_pretrained(...)中直接传入也能通过 BonsaiImageGenerationModel.from_model_id 的同名 kwargs 传递例如load(bonsai-ternary, tiled_vaeon, max_sequence_length768)。CLI 使用生成一张图python -m mlx_vlm generate_image \ --model prism-ml/bonsai-image-ternary-4B-mlx-2bit \ --prompt A tiny glass bonsai tree on a moonlit desk \ --size 512x512 \ --steps 4 \ --seed 9909 \ --output outputs/bonsai.png等价的 generate 命令python -m mlx_vlm generate \ --output-modality image \ --model bonsai-ternary \ --prompt A tiny glass bonsai tree on a moonlit desk \ --size 512x512 \ --steps 4 \ --seed 9909 \ --output outputs/bonsai.png两条命令走同一条底层路径run_image_generation_cli 解析参数后调用load_image_model(..., taskgenerate)→generate_image(model, request, output_path...)。几个值得注意的行为细节--seed省略时生成一个随机 32-bit 种子random.randrange(2**32)--output省略时图片写入outputs/image-{seed}.png默认--size为512x512未传--steps时默认为 4命令执行成功后会打印Saved {path} seed... sizeWxH steps... variant...摘要其中variant对 Bonsai 即ternary图像生成任务对 token 类参数做了白名单式校验--kv-bits、--eos-tokens、--chat、--audio等文本生成参数与图像任务不兼容传入会直接报错见 _validate_image_generation_args。Python APIPython 侧的统一入口在 mlx_vlm/generate/image.pyload_image_generation_model负责按 id/别名/本地路径识别模型类generate_image负责执行并把结果封装为 ImageGenerationResult。基本生成from mlx_vlm.generate.image import ( ImageGenerationRequest, generate_image, load_image_generation_model, ) model load_image_generation_model( prism-ml/bonsai-image-ternary-4B-mlx-2bit ) request ImageGenerationRequest( promptA tiny glass bonsai tree on a moonlit desk, seed9909, steps4, width512, height512, guidance1.0, ) result generate_image(model, request) # 主输出是求值后的 MLX 数组HWC、uint8、RGB、0-255 array result.array print(array.shape, array.dtype) result.save(outputs/bonsai.png)ImageGenerationResult除了array还携带seed、width/height、steps、guidance、prompt_tokens、peak_memoryGB等元数据save()会自动创建父目录并把result.path回填。Prompt 简写形式generate_image的第二个参数既可以是ImageGenerationRequest对象也可以直接传 prompt 字符串此时seed、steps、width、height、guidance等 kwargs 会被 自动组装为请求其余未知 kwargs 非空时并入extrafrom mlx_vlm.generate.image import generate_image, load_image_generation_model model load_image_generation_model(bonsai-ternary) result generate_image( model, A tiny glass bonsai tree on a moonlit desk, seed9909, steps4, width512, height512, output_pathoutputs/bonsai.png, ) print(result.path)注意request.seed is None时generate_image会就地补一个随机 32-bit 种子保证每次调用都有确定来源的种子。Base64 PNG 输出from mlx_vlm.generate.image import generate_image, load_image_generation_model model load_image_generation_model(bonsai-ternary) result generate_image( model, A tiny glass bonsai tree on a moonlit desk, seed9909, steps4, width512, height512, ) b64_png result.to_b64_json()to_b64_json()内部先把mx.array转成 PIL 图像再编码为 PNG 字节做 Base64与 OpenAI 图像接口的b64_json响应格式完全对齐可直接塞进下游服务。OpenAI 兼容 APImlx-vlm 的 server 模块暴露了POST /v1/images/generations见 server/openai.py请求体与 OpenAI 图像生成 API 对齐curl http://localhost:8080/v1/images/generations \ -H Content-Type: application/json \ -d { model: prism-ml/bonsai-image-ternary-4B-mlx-2bit, prompt: A tiny glass bonsai tree on a moonlit desk, size: 512x512, steps: 4, seed: 9909, response_format: b64_json }默认response_format为b64_json返回 Base64 编码的 PNG需要落盘时改为response_format: path并可附带output_path或output_dir指定保存位置。server 侧最终同样是调用generate_image(...)拿到ImageGenerationResult再按response_format序列化因此 API 与 CLI/Python 三条路径的输出语义种子、尺寸、步数完全一致。注意事项始终显式传入图像生成模型 id 或本地快照路径Bonsai 不是 VLM 的对话模型不能当作--model下的默认语言模型来跑文本生成。直接传纯 prompt 文本Bonsai 的 tokenizer 应用的是它自己的 chat template不要把已经包好 system/assistant 消息的对话结构喂进去。目前只暴露 ternary 变体binary/1-bit 模型出于策略原因暂未在变体表中开放config.py 中VARIANTS仅注册了ternary。本地快照识别当传入的字符串是一个已存在的目录时resolve_variant 会默认按ternary变体加载can_load会对目录执行validate_model_layout校验后再判定可加载性。测试用例 test_bonsai.py 用伪造的 transformer/VAE 覆盖了generate_array的完整采样循环与模型类识别逻辑可作为行为参照。内存与步数取舍4 步、guidance1.0无 CFG省一次前向是该模型的推荐配置若要开 CFGguidance取 1.0即可每一步会多一次以 为 prompt 的前向。小结Prism Bonsai 在 mlx-vlm 中演示了超低位宽扩散模型如何落地为可用产品接口的完整闭环三元 2-bit 量化 transformer 4-bit 文本编码器 小 VAE 解码器4 步 Flow Matching 采样配合 prompt 缓存与文本编码器淘汰控制内存峰值对上则同时提供 CLI、Python 与 OpenAI 兼容 API 三种一致的调用面。相关实现集中在 mlx_vlm/models/bonsai/config、download、weights、pipeline、model、klein_fast与 mlx_vlm/generate/image.py 两条代码路径中可按上文链接继续深入。【免费下载链接】mlx-vlmMLX-VLM is a package for inference and fine-tuning of Vision Language Models (VLMs) on your Mac using MLX.项目地址: https://gitcode.com/GitHub_Trending/ml/mlx-vlm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考