企业官网建设流程全解析

Ministral-3-14B-Base-2512-8bit 是 Mistral 3 14B 多模态基座模型（文本 + 视觉）的 MLX 8-bit 量化版本，可在 Apple Silicon 上用 mlx-vlm 直接加载运行。本文对仓库里的 13 个文件逐个拆解：3 个 safetensors 权重分片各装了什么、tokenizer.json 与 tekken.json 的 tekken 分词器是什么关系、config.json / params.json / generation_config.json 各管哪部分，最后给出一张可收藏的速查表，帮你在几分钟内看懂这个 MLX 模型仓库的完整结构。

📦 30 秒了解：这是一个什么模型

• 类型：Ministral 3 14BBase基座模型，未做指令微调，支持图像 + 文本的多模态理解
• 量化：语言骨干 8-bit affine 量化（group_size=64）；视觉塔与多模态投影器保留 bf16 全精度
• 来源：由官方 BF16 模型经 mlx-vlm 转换而来
• 体积：磁盘合计约 15.9 GB（权重总字节数 15,857,653,760）
• 适用：自训练 / 微调 / 二次开发；想直接聊天请使用 Instruct 变体

💡 模型卡 README.md 中声明该模型支持 en、fr、es、de、it、pt、nl、zh、ja、ko、ar 共 11 种语言，许可证为 Apache 2.0。

🗂️ 仓库文件总览速查表

📌 提示：在本 checkout 中，3 个.safetensors与两个大 tokenizer 文件是 Git LFS 指针（本地仅 135 字节），真实大小以指针内的size字段为准，例如分片①为size 5290092821≈ 5.29 GB。完成 LFS 拉取后即可得到真实权重文件。

🧩 safetensors 分片逐个拆：为什么切、怎么切

为什么一个模型要切成 3 个分片

单个 safetensors 文件超过 5 GB 后，下载、校验与加载都会变慢；按约 5 GB 切分后支持断点续传，也方便按张量名快速定位。切分方案完全由 model.safetensors.index.json 决定，它包含两部分：

• metadata.total_size：全部权重总字节数15,857,653,760
• weight_map：1147个张量名 → 所在分片文件的映射

三个分片各自装了什么

按weight_map统计，1147 个张量按前缀分为三大块：

具体切法（首 / 末张量均取自 index 文件）：

1. model-00001-of-00003.safetensors（493 张量，≈5.29 GB）以language_model.model.embed_tokens.biases（词表嵌入）开头，包含语言骨干前段（至第 10 层），随后整个 vision_tower 与 multi_modal_projector都压在这个分片里，最后一个张量是vision_tower.vision_model.transformer.layers.9.ffn_norm.weight。
2. model-00002-of-00003.safetensors（376 张量，≈5.35 GB）纯语言骨干中段：首张量language_model.model.layers.11.input_layernorm.weight，末张量layers.27.self_attn.v_proj.weight。
3. model-00003-of-00003.safetensors（278 张量，≈5.22 GB）以language_model.lm_head.weight开头，装下语言骨干后段（至第 39 层）与最终model.norm。注意 lm_head 名下没有 scales / biases，即输出头未量化。

8-bit 量化藏在哪些张量里

index 中的张量后缀只有三种：weight（585 个）、biases（281 个）、scales（281 个）。

• 凡是成组出现weight + biases + scales的（如self_attn.q_proj.*、mlp.gate_proj.*、embed_tokens.*），就是 8-bit affine 量化产物：weight存 8-bit 量化值，biases/scales存每 64 个元素一组的偏置与缩放因子，加载时反量化还原。
• vision_tower.*与投影器只有weight，保持 bf16 全精度——这正是 README.md 中 "vision retained at full precision" 一说的来源。
• 量化参数本身写在 config.json 的quantization字段：bits: 8、group_size: 64、mode: affine。

📝 tokenizer 三件套：tekken 分词器速查

tokenizer.json 与 tekken.json 是什么关系

该模型的分词器是Tekken 字节级 BPE（类名为LlamaTokenizerFast），两个文件各司其职：

两者词表一致（vocab_size =131072），体积也接近（17.08 MB 对 16.75 MB）。仓库同时保留两份，是为了让 MLX 原生栈与 transformers 生态都能独立加载，互不依赖。

tokenizer_config.json：1000 个附加 token

tokenizer_config.json 中几个新手值得注意的开关：

• tokenizer_class: LlamaTokenizerFast、legacy: true
• add_bos_token: true、add_eos_token: false：编码时自动加句首 token，不加句尾
• added_tokens_decoder共1000 个附加 token，前 20 个承担实际功能：

special_tokens_map.json 与之一致：bos = <s>(id 1)、eos = </s>(id 2)、pad = <pad>(id 11)，外加 1000 条additional_special_tokens。

processor_config.json：图像是怎么"分词"的

多模态模型里图像也有自己的"分词"。processor_config.json 配置了PixtralProcessor+PixtralImageProcessorFast：

• 图像按长边1540像素缩放（size.longest_edge），再以14×14的 patch 切块
• 使用固定均值 / 方差做归一化（CLIP 风格）
• 文本侧插入[IMG]占位符，spatial_merge_size: 2表示每 2×2 个 patch 合并为 1 个视觉 token
• [IMG_BREAK]/[IMG_END]对应 token id 12 / 13，用于标记图像块的边界

⚙️ 配置三兄弟：config.json / params.json / generation_config.json

• config.json：完整结构描述。architectures为Mistral3ForConditionalGeneration；text_config中 hidden_size = 5120、40 层、32 个注意力头（KV 头 8 个，即 GQA）、上下文 262144（YARN 从 16384 外推 16 倍）；vision_config为 pixtral 型（24 层、hidden 1024）。量化配置见 config.json 第 18–27 行。
• params.json：MLX 精简版结构参数，与 config 等价但更短——dim: 5120、n_layers: 40、rope_theta: 1e9、yarn.factor: 16，另有 vision_encoder 段（第 29–46 行） 描述视觉塔。
• generation_config.json：只放采样默认值：bos_token_id: 1、eos_token_id: 2、pad_token_id: 11、max_length: 262144。

💡 三份文件信息有重叠但面向不同加载器：transformers 读config.json，mlx-vlm 优先读params.json，generation_config.json只负责生成参数默认值。

🚀 快速上手：用 mlx-vlm 跑起来

pip install -U mlx-vlm

python -m mlx_vlm.generate --model mlx-community/Ministral-3-14B-Base-2512-8bit \ --max-tokens 100 --temperature 0.0 \ --prompt "Describe this image." --image /path/to/img.jpg

• 纯文本任务：省略--image参数即可
• 预期行为：Base 模型只按"续写"方式工作，不会乖乖遵循指令，聊天场景请换 Instruct 变体
• 磁盘占用约 15.9 GB，Apple Silicon 上建议 24 GB 统一内存起步（视觉塔保持 bf16，占位不小）

❓ 常见疑问

Q：只下载了分片①，为什么加载不起来？A：加载器会按 model.safetensors.index.json 的weight_map从 3 个分片中分别取 1147 个张量，缺一不可。

Q：tekken.json 和 tokenizer.json 能删掉一个吗？A：不建议。MLX 原生栈读tekken.json，transformers 生态读tokenizer.json，删掉任何一方都会让对应工具链加载失败。

Q：为什么 vision_tower 的张量没有量化后缀？A：mlx-vlm 的标准策略是不量化多模态模块，视觉塔与投影器保持 bf16 以保证图像理解质量（详见 README.md 的 Provenance 一节）。

Q：想基于它做微调，该从哪些文件入手？A：权重在 3 个 safetensors 分片中，结构看 params.json，量化参数看 config.json 第 18–27 行。Base 权重可直接作为 LoRA 或全参微调的初始化。

一句话总结：3 个 safetensors 分片装权重（1147 张量、约 15.9 GB，8-bit 量化只作用于语言骨干），tekken.json 与 tokenizer.json 装 Tekken 分词器（131072 词表 + 1000 个特殊 token），config / params / generation / processor 四份 JSON 分别描述模型结构、MLX 参数、采样默认值与图像处理。对照上面的速查表，任何文件的作用都能一秒定位。