markbaseengine/26B使用指南.md

Gemma-4 26B 使用指南

当前状态

已发现: MLX Gemma-4 26B 模型 位置: ~/.cache/huggingface/hub/models--mlx-community--gemma-4-26b-a4b-mxfp4/ 大小: 14.8 GB 状态: 格式不兼容，需要转换

---

快速开始

方案 A: 使用转换脚本 (推荐)

步骤 1: 运行转换脚本

cd /Users/accusys/MarkBase12B

python3 convert_mlx_26b.py \
  --input ~/.cache/huggingface/hub/models--mlx-community--gemma-4-26b-a4b-mxfp4 \
  --output ~/models/gemma-4-26b-standard

预期输出:

=== MLX 26B → 标准 4-bit 转换 ===

步骤 1: 加载 MLX 权重
  加载 model-00001-of-00003.safetensors...
  加载 model-00002-of-00003.safetensors...
  加载 model-00003-of-00003.safetensors...
  ✓ 总权重数: 1283

步骤 2: 重命名权重
  已处理 100/1283 权重
  ...
  ✓ 重命名完成

步骤 3: 转换 scales 格式
  转换 embed_tokens.scales: uint8 → BF16
  ...
  ✓ scales 转换完成

步骤 4: 保存为单个 safetensors
  ✓ 保存到: ~/models/gemma-4-26b-standard/model.safetensors

步骤 5: 创建 config.json
  ✓ config.json 创建完成

步骤 6: 复制 tokenizer 文件
  ✓ 复制 tokenizer.json
  ✓ 复制 tokenizer_config.json
  ✓ 复制 generation_config.json

=== 转换完成 ===

步骤 2: 测试加载

swift test --filter test26BModelLoading

步骤 3: 启动服务器

swift run G12BServer ~/models/gemma-4-26b-standard 8080 gemma-26b

---

详细步骤说明

依赖安装

需要安装 Python 依赖:

pip install safetensors torch

转换过程详解

脚本功能:

1. 加载 MLX 权重

# 加载 3 个 safetensors shards
weights = {}
for shard in ["model-00001-of-00003.safetensors", ...]:
    shard_weights = load_file(shard)
    weights.update(shard_weights)

2. 重命名权重

# 移除 language_model.model 前缀
# language_model.model.layers.0 → layers.0
new_key = key.replace("language_model.model.", "")

3. 转换 scales

# uint8 scales → BF16
if ".scales" in key and tensor.dtype == torch.uint8:
    converted = tensor.float().bfloat16()

4. 生成配置

{
  "model_type": "gemma4",
  "hidden_size": 2816,
  "num_hidden_layers": 42,
  "vocab_size": 262144,
  "quantization_config": {
    "bits": 4,
    "group_size": 64
  }
}

---

Memory 要求

26B Memory 估算

权重大小:

• 26B parameters × 0.5 bytes (4-bit) = 13 GB
• Embed tokens: ~1 GB
• Vision tower: ~0.5 GB
• 总计: ~14.5 GB

运行时 Memory:

• Weights: 14.5 GB
• KV Cache (128 context): 0.5 GB
• Activations: 1-2 GB
• 总计: ~17 GB

Mac 要求

Mac Model	Memory	26B 支持	建议
M1/M2 Base	8-16GB	✗	不推荐
M1/M2 Pro	16GB	⚠	勉强
M1/M2 Max	24-32GB	⚠	可能需要优化
M3 Pro	36GB	✓	推荐
M3 Max	48GB	✓	充足
M4/M5	64-192GB	✓	完全充足

Memory 优化建议

如果 Memory 不足:

1. 减小 Context Length

let model = try E4BModel(
    modelDir: modelDir,
    engine: engine,
    maxContextLength: 128  // 而非 512
)

2. 使用 RDMA 分布式

# 42层分布到多个设备
# Device 1: Layers 0-20
# Device 2: Layers 21-41

3. 关闭其他应用

# 释放更多 memory

---

性能预期

单设备性能

预估:

26B 参数量 × 2 (vs 12B)
性能 ≈ 12B 的 50%

12B: ~30 tok/s
26B: ~15 tok/s (预估)

分布式性能

RDMA distributed:

跨设备推理可以显著提升:
- 658 tok/s (12B baseline)
- 26B distributed: 400+ tok/s (预估)

---

测试指南

转换后测试

测试 1: 加载验证

func test26BModelLoading() throws {
    let model = try E4BModel(modelDir: "~/models/gemma-4-26b-standard", ...)
    XCTAssertGreaterThan(model.numHiddenLayers, 0)
    XCTAssertEqual(model.hiddenSize, 2816)
}

测试 2: 推理测试

func test26BInference() throws {
    let tokens = tokenizer.encode(text: "Hello")
    let logits = try model.forward(tokenId: tokens[0], position: 0)
    XCTAssertGreaterThan(logits.count, 0)
}

测试 3: Memory 测试

func test26BMemory() throws {
    // 检查 memory 使用
    let memoryUsed = getMemoryUsage()
    XCTAssertLessThan(memoryUsed, 20_000_000_000)
}

---

故障排除

转换失败

问题: 转换脚本报错

解决方案:

# 检查依赖
pip install safetensors torch

# 检查输入路径
ls ~/.cache/huggingface/hub/models--mlx-community--gemma-4-26b-a4b-mxfp4/

# 检查 Python 版本 (需要 3.9+)
python3 --version

加载失败

问题: Swift 加载报错

常见错误:

Error: unsupportedDtype
→ 检查 scales 是否正确转换为 BF16

Error: weights not found
→ 检查权重命名是否正确

Error: memory不足
→ 减小 maxContextLength 或使用 RDMA

推理失败

问题: 推理错误或挂起

解决方案:

# 检查 memory
# 检查 config.json 参数
# 使用简单输入测试

---

完整示例

从开始到运行

完整流程:

# 1. 下载依赖
pip install safetensors torch

# 2. 转换模型
cd /Users/accusys/MarkBase12B
python3 convert_mlx_26b.py \
  --input ~/.cache/huggingface/hub/models--mlx-community--gemma-4-26b-a4b-mxfp4 \
  --output ~/models/gemma-4-26b-standard

# 3. 验证转换
ls -lh ~/models/gemma-4-26b-standard/
jq '.' ~/models/gemma-4-26b-standard/config.json

# 4. 测试加载
swift test --filter test26BModelLoading

# 5. 启动服务器
swift run G12BServer ~/models/gemma-4-26b-standard 8080 gemma-26b

# 6. 测试推理
curl -X POST http://localhost:8080/v1/chat/completions \
  -d '{"messages":[{"role":"user","content":"Hello"}]}'

---

与其他模型对比

26B vs 12B

特性	12B	26B
参数量	12B	26B
Hidden size	2560	2816
Memory	8GB	17GB
性能	30 tok/s	15 tok/s
MoE	No	Yes
文件大小	6GB	14.8GB

26B vs 31B

特性	26B	31B
参数量	26B	31B
Memory	17GB	20GB
性能	15 tok/s	10 tok/s
推荐 Mac	M3 Pro+	M4+

---

下一步

立即行动

推荐路径:

1. ✓ 运行转换脚本
2. ✓ 测试加载
3. ✓ 启动服务器
4. ✓ 测试推理

后续优化

可选优化:

1. 实现 MoE 支持
2. RDMA distributed 推理
3. Performance tuning
4. Memory optimization

---

总结

26B 模型可以使用，但需要转换格式

步骤:

1. 运行 convert_mlx_26b.py
2. 测试加载
3. 启动服务器

要求:

• Memory: 17+ GB (M3 Pro/Max 或更高)
• Python: 3.9+ (用于转换)
• 依赖: safetensors, torch

时间:

• 转换: 10-30 分钟
• 加载: 1-2 分钟
• 推理: 与 12B 类似但稍慢

---

使用指南生成: June 19, 2026 当前状态: 可用（需转换） 推荐方案: 使用转换脚本