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: 运行转换脚本**
```bash
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: 测试加载**
```bash
swift test --filter test26BModelLoading
```

**步骤 3: 启动服务器**
```bash
swift run G12BServer ~/models/gemma-4-26b-standard 8080 gemma-26b
```

---

## 详细步骤说明

### 依赖安装

**需要安装 Python 依赖**:
```bash
pip install safetensors torch
```

### 转换过程详解

**脚本功能**:

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

#### 2. 重命名权重
```python
# 移除 language_model.model 前缀
# language_model.model.layers.0 → layers.0
new_key = key.replace("language_model.model.", "")
```

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

#### 4. 生成配置
```json
{
  "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
```swift
let model = try E4BModel(
    modelDir: modelDir,
    engine: engine,
    maxContextLength: 128  // 而非 512
)
```

#### 2. 使用 RDMA 分布式
```bash
# 42层分布到多个设备
# Device 1: Layers 0-20
# Device 2: Layers 21-41
```

#### 3. 关闭其他应用
```bash
# 释放更多 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: 加载验证**
```swift
func test26BModelLoading() throws {
    let model = try E4BModel(modelDir: "~/models/gemma-4-26b-standard", ...)
    XCTAssertGreaterThan(model.numHiddenLayers, 0)
    XCTAssertEqual(model.hiddenSize, 2816)
}
```

**测试 2: 推理测试**
```swift
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 测试**
```swift
func test26BMemory() throws {
    // 检查 memory 使用
    let memoryUsed = getMemoryUsage()
    XCTAssertLessThan(memoryUsed, 20_000_000_000)
}
```

---

## 故障排除

### 转换失败

**问题**: 转换脚本报错

**解决方案**:
```bash
# 检查依赖
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
```

### 推理失败

**问题**: 推理错误或挂起

**解决方案**:
```bash
# 检查 memory
# 检查 config.json 参数
# 使用简单输入测试
```

---

## 完整示例

### 从开始到运行

**完整流程**:
```bash
# 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
**当前状态**: 可用（需转换）
**推荐方案**: 使用转换脚本