Initial commit: E4B-MarkBase model integration with passing tests

- E4B-MarkBase model (42 layers, 4.4GB) loaded successfully - All Phase 1-6 tests passed (model loading, forward pass, vision/audio towers, token generation, performance) - All stress tests passed (5/5 in 127.6s) - Concurrent inference - Memory stress (67.5 tok/s, 0 NaN) - Continuous generation - Batch processing - Long-running stability - Swift Metal inference engine with multimodal support
2026-06-23 18:12:35 +08:00
commit ac75faa0cc
301 changed files with 63426 additions and 0 deletions
--- a/26B使用指南.md
+++ b/26B使用指南.md
@@ -0,0 +1,381 @@
+# 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
+**当前状态**: 可用（需转换）
+**推荐方案**: 使用转换脚本
+