# vmllm

**Repository Path**: uesoft/vmllm

## Basic Information

- **Project Name**: vmllm
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-25
- **Last Updated**: 2026-06-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# vmllm — LLM Inference VM 实验场

**性质：** monorepo（多项目共享 `core/`）+ benchmark 对比平台  
**目标：** 用同一个 GGUF 加载器 + 同一份原子算子，对比不同 VM 后端的简洁性 / 性能 / 可移植性

## 目录结构

```
vmllm/
├── README.md                  ← 你正在看
├── CMakeLists.txt             ← 顶层（add_subdirectory 各子项目）
├── core/                      ← 【共享】所有子项目的公共代码（单一来源）
│   ├── gguf.h  gguf.c         ← GGUF v3 加载 + Q4_K/Q6_K/F16/F32 反量化
│   ├── cordic.h  cordic.c     ← 数学后端（sin/cos/sqrt/exp/pow）
│   ├── tensor.h  tensor.c     ← Tensor 类型 + 原子算子 c_matmul/c_layernorm/...
│   └── tests/
│       └── test_gguf.c        ← GGUF 解析单元测试（共用）
│
├── fllm/                      ← Back-End 1: 直接 C 函数（无 VM）
│   ├── CMakeLists.txt         ← target_link_libraries(... core)
│   └── src/{llmvm.c,main.c}
│
├── mufllm/                    ← Back-End 2: muforth ITC 字节码 VM
│   ├── CMakeLists.txt
│   └── src/{vm.c,ops.c,model.c,main.c}
│
├── picocllm/                  ← Back-End 3: picoc 解释器（规划中）
├── wasmllm/                   ← Back-End 4: WASM runtime（规划中）
├── pfllm/                     ← Back-End 5: pForth（规划中）
│   （sqlitellm/pgllm/vmvm 暂不建空目录，等真有实现再说）
│
├── bench/                     ← 横向 benchmark（独立子项目）
│   ├── README.md              ← 评分表 + 排名
│   ├── scripts/
│   │   ├── bench_phi2.sh      ← 固定 phi-2 输入，跑各实现 forward
│   │   └── bench_report.py    ← 生成 markdown 排名表
│   ├── golden/                ← llama.cpp 参考输出（ground truth）
│   └── results/               ← 各实现每次提交的输出快照（JSON）
│
├── models/                    ← 模型软链（不进 git）
│   └── dsue-2-Q4_K_M.gguf → ../llama/models/dsue-2-Q4_K_M.gguf
│
└── docs/
    ├── review_2026-06-25.md   ← 上次审查报告（原始位置）
    ├── bugs.md                ← 各项目共享的 bug 跟踪
    └── design_notes.md        ← VM 对比的设计笔记
```

## 设计原则

### 1. core/ 是单一事实来源
- 修 Q4_K 反量化 bug → 只改 `core/gguf.c` 一处
- 所有 back-end 立即受益
- core 不依赖任何 VM 实现（纯 C99，可独立编译）

### 2. 子项目只写"如何把 core 串起来"
- **fllm**：core 直接调，无 VM
- **mufllm**：core 包成 mu_xxx 算子塞进 ITC 字节码
- **picocllm**：core 注册成 picoc C 库函数
- **wasmllm**：core 编译成 WASM module

### 3. bench/ 是裁判，不参赛
- 固定输入（phi-2 BOS token 50256）
- 固定输出位置（layer 0 hidden L2、最终 token）
- 数字说话，主观判断退场

## 迁移路径（破坏性变更，需通知 DeepSeek）

**Phase 1（现在）：** 建 vmllm 骨架，把 core/ 抽出来，但**不动 fllm/mufllm 的现有代码**——让它们原地工作。

**Phase 2（mufllm ffn_norm bug 修完后）：**
- 把 fllm 和 mufllm 的 src/ 移进 vmllm/fllm/ 和 vmllm/mufllm/
- 删除 D:/vc/fllm 和 D:/vc/mufllm 的旧副本（保留 git 历史）
- 各项目 CMakeLists 改为 link core

**Phase 3（benchmark 出第一份对比数据后）：**
- 决定是否继续探索 picocllm/wasmllm/pfllm
- 决定 vmvm 是否独立立项

## 为什么不把 ggml/ 拉进来？

ggml 是**完整的生产级张量库**（10 万行），跟"从零理解 VM"的目标冲突。
- 需要参考实现：直接 git submodule `ggml` 到 `extern/ggml/`，仅作只读对照
- 自研 core/ 故意保持 < 2000 行，确保可读、可改、可教学

## 为什么不抽 VM 核心？

VM 核心是**各 back-end 的差异点**——
- fllm 没 VM（直接 C 函数调用）
- mufllm 用 ITC 字节码 + 字典链表
- picocllm 用 picoc 的 AST 解释
- wasmllm 用 WASM bytecode

强行抽 `core/vm.c` 会把"对比"变成"趋同"，违背 benchmark 初衷。

## 现状

| 项目 | 状态 | 备注 |
|---|---|---|
| core/ | 🟡 待迁移 | 当前内容 = fllm/gguf.c 的副本 |
| fllm | ✅ 可用 | 待迁移到 vmllm/fllm/ |
| mufllm | 🔴 数值爆炸 | ffn_norm bug 修复后迁移 |
| bench | 🟡 待建 | 等 mufllm 修复后出第一份对比 |
| picocllm/wasmllm/pfllm | ⚪ 规划 | 不建空目录 |