---

关于

Magnetron 是用 C 从头构建的机器学习运行时，配备小巧现代的 Python 接口以提升易用性。
它实现了自己的张量系统、算子集合、自动微分引擎和执行模型——完全不依赖大型外部框架。

目标很简单：

保持栈足够小，便于理解且可被深入探索，同时又足够强大，能够运行真实的模型。

这使得 Magnetron 在两种情况下非常有用：

• 当你想要 对执行和内存拥有完全控制权 时
• 当你希望有一个 干净的实验或新想法的基础 时

---

为什么选择 Magnetron？

Magnetron 并不试图在生态系统或功能数量上与 PyTorch 竞争。

相反，它专注于不同的方向：

Magnetron	PyTorch
小巧、可检查的核心	庞大、分层的系统
显式执行	隐式/抽象化
极少的依赖	重度运行时依赖
易于修改内核	后端逻辑更难理解
适合研究与系统工作	适合生产与规模化

如果你希望：

• 了解你的模型究竟是如何运行的
• 实验内核、内存布局或执行方式
• 将机器学习工作负载移植到特殊硬件上

Magnetron 能为你提供一条更为直接的路径。

---

架构概览

Magnetron 被构建为一个 单一、 cohesive 的运行时，而非一组松散耦合的库。

• 张量系统
  自主管理数据类型、形状、步长和内存——支持完整的 视图系统及视图求解器，实现复杂的切片、重塑和广播语义，类似于 PyTorch，同时保持显式和可预测性。

• 执行模型
  情景式执行，配备动态自动微分图（反向模式），该图在每次前向传播时构建，并在反向传播过程中遍历。

• 算子后端
  中央调度层，将高层操作映射到特定于架构的内核实现。

• CPU 后端
  多重分派设计，包含针对多种微架构（Intel、AMD Zen1–Zen5、ARM）的 编译时优化内核。
  运行时通过 CPUID 检测 自动选择最优的内核路径。
  支持多种 SIMD ISA 和扩展，包括 SSE (1–4)、AVX、AVX2、FMA、AVX-512、AVX-512-BF16、AVX-512-FP16、F16C 以及 ARM NEON，并结合多线程执行。

• CUDA 后端（开发中）
  内核层已实现——内存管理、执行流水线和集成正在积极完善中。

• 序列化
  原生 .mag 格式专为 零拷贝、内存映射加载 设计，可实现快速启动和高效的大模型处理。
  提供转换工具，用于从外部格式导入权重。

• 后端可扩展性
  架构经过精心设计，干净且模块化，因此引入新的后端或适配其他硬件平台都十分简便。

该系统刻意保持 紧凑且显式，使每一层都易于理解、控制和替换，而不会隐藏复杂性。

---

亮点

• 实用而非仅用于教学
  能够运行现代 LLM 推理（例如 Qwen3 的 BF16 版本），而不仅仅是玩具模型。

• 小型、可控的 ML 运行时
  设计宗旨是端到端可检查——不存在隐藏的执行层或不透明的后端。

• 真正掌控执行过程
  你可以无需任何抽象屏障，清晰地分析内存布局、内核调度和计算图行为。

• 天生具备硬件感知能力
  不是通用的后端封装——内核和执行流程均针对特定的 ISA 和微架构编写。

• 零拷贝模型加载
  内存映射的 .mag 格式可实现快速启动和高效的大模型处理。

• 专为实验设计
  易于修改算子、添加内核或尝试新的执行策略。

• 最小化的运行时表面
  原生扩展，无需任何 Python 依赖——易于部署和嵌入。

---

示例模型

端到端演示位于 examples/ 目录下。

路径	描述
examples/qwen3/	Qwen3 变换器推理，采用 bfloat16 数据类型，集成分词器、.mag 权重、CLI 对话以及 HTTP/流式 API。
examples/gpt2/	GPT-2 因果语言模型推理，支持 KV 缓存、令牌流式输出和可配置的生成设置。
examples/ae/	卷积自编码器，包含训练循环和重建可视化。
examples/linear_regression/	简单的一维回归，使用 SGD 并跟踪损失。
examples/xor/	最小化 MLP，展示自动微分和优化过程。

---

算子速查表

Magnetron 提供了一套紧凑但富有表现力的算子集，涵盖：

• 元素级操作（加、乘、除等）
• 归约操作（求和、平均等）
• 张量变换（视图、重塑、转置等）
• 神经网络基础组件（矩阵乘法、softmax、层归一化等）
• 类型转换和内存视图

完整的算子、数据类型和语义参考请见：

→ Magnetron 速查表

---

安装

Magnetron 已发布至 PyPI。

请确保你在 Python 虚拟环境中。

pip install magnetron

或使用 uv：

uv pip install magnetron

---

本地开发

克隆仓库并在本地安装：

git clone --recursive https://github.com/MarioSieg/magnetron
cd magnetron
uv pip install . -v

对于 C/C++ 开发，可在 IDE（如 CLion）中打开项目根目录（包含 CMakeLists.txt 文件）。

快速入门

from magnetron import Tensor, nn, optim

x = Tensor([[0.0, 0.0], [0.0, 1.0], [1.0, 0.0], [1.0, 1.0]])
y = Tensor([[0.0], [1.0], [1.0], [0.0]])

model = nn.Sequential(
    nn.Linear(2, 2),
    nn.Tanh(),
    nn.Linear(2, 1),
    nn.Tanh(),
)

optimizer = optim.SGD(model.parameters(), lr=1e-1)
criterion = nn.MSELoss()

for epoch in range(2000):
    y_hat = model(x)
    loss = criterion(y_hat, y)
    loss.backward()
    optimizer.step()
    optimizer.zero_grad()

    if epoch % 100 == 0:
        print(f"Epoch {epoch:4d} | Loss {loss.item():.6f}")

y_hat = model(x)
for i in range(x.shape[0]):
    print(f"Expected: {y[i].item():.1f}, Predicted: {y_hat[i].item():.4f}")

---

路线图

• 🚧 CUDA 后端
  完成内存模型、执行流水线，并使其稳定以供生产使用。

• 🚧 多 GPU 执行
  引入跨多个设备的可扩展执行能力。

• 🚧 新的 CPU 架构
  支持 LoongArch 和 RISC-V。

• 🧪 JIT 编译
  自定义基于 SSA 的中间表示，包含寄存器分配和目标特定的指令生成。

---

历史

Magnetron 项目始于 2024 年，最初是一个个人学习项目，旨在深入理解机器学习框架的内部工作原理：张量存储、算子调度、自动微分以及推理执行等。这个原本用于学习的项目逐渐演变为一个完整的运行时系统，具备独立的张量引擎、原生快照格式、面向 SIMD 的 CPU 后端，并支持以 BF16 精度运行 Qwen3 等现代模型。如今，Magnetron 既被用作实用的推理/运行时系统，也作为研究平台，用于探索新的后端、执行策略以及低层机器学习系统设计思路。

---

许可证

(c) 2026 马里奥·西格 - mario.sieg.64@gmail.com
根据 Apache 2 许可证发布。
开发于德国柏林。

---

类似项目

• PyTorch
• GGML
• tinygrad
• MLX

Magnetron 快速上手指南

Magnetron 是一个从零开始用 C 语言编写的紧凑机器学习运行时，专为希望完全掌控执行流程、内存布局及底层优化的开发者设计。它拥有独立的张量系统、算子集和自动微分引擎，无重型运行时依赖。

环境准备

• 操作系统：Linux, macOS, Windows (需支持 CMake 构建环境)
• Python 版本：推荐 Python 3.8+
• 前置依赖：
  • 建议在使用前创建独立的 Python 虚拟环境。
  • 若进行本地开发（C/C++ 修改），需安装 CMake 及 C/C++ 编译器（如 GCC, Clang 或 MSVC）。
• 硬件支持：
  • CPU：支持 Intel/AMD (SSE, AVX, AVX2, AVX-512 等) 及 ARM (NEON) 架构，运行时自动检测最优指令集。
  • GPU：CUDA 后端正在开发中，目前主要专注于 CPU 推理与训练。

安装步骤

方式一：通过 PyPI 安装（推荐）

确保已激活虚拟环境，使用以下命令安装：

pip install magnetron

如果你使用 uv 作为包管理器：

uv pip install magnetron

提示：国内用户若遇到下载缓慢，可添加国内镜像源，例如：

pip install magnetron -i https://pypi.tuna.tsinghua.edu.cn/simple

方式二：本地源码安装（用于开发或最新特性）

克隆仓库并递归获取子模块，然后进行本地安装：

git clone --recursive https://github.com/MarioSieg/magnetron
cd magnetron
uv pip install . -v

对于 C/C++ 开发，可使用 CLion 等 IDE 打开项目根目录（包含 CMakeLists.txt 的文件）进行调试。

基本使用

Magnetron 提供了类似 PyTorch 的现代 Python API，但底层更加透明可控。以下是一个完整的 XOR 问题训练示例，展示了张量创建、模型构建、损失计算及反向传播流程：

from magnetron import Tensor, nn, optim

# 1. 准备数据 (XOR 问题)
x = Tensor([[0.0, 0.0], [0.0, 1.0], [1.0, 0.0], [1.0, 1.0]])
y = Tensor([[0.0], [1.0], [1.0], [0.0]])

# 2. 构建模型 (简单的多层感知机)
model = nn.Sequential(
    nn.Linear(2, 2),
    nn.Tanh(),
    nn.Linear(2, 1),
    nn.Tanh(),
)

# 3. 配置优化器与损失函数
optimizer = optim.SGD(model.parameters(), lr=1e-1)
criterion = nn.MSELoss()

# 4. 训练循环
for epoch in range(2000):
    y_hat = model(x)
    loss = criterion(y_hat, y)
    
    # 反向传播
    loss.backward()
    
    # 更新参数
    optimizer.step()
    optimizer.zero_grad()

    if epoch % 100 == 0:
        print(f"Epoch {epoch:4d} | Loss {loss.item():.6f}")

# 5. 验证结果
y_hat = model(x)
for i in range(x.shape[0]):
    print(f"Expected: {y[i].item():.1f}, Predicted: {y_hat[i].item():.4f}")

核心特性速览

• 零拷贝加载：支持 .mag 格式模型文件，通过内存映射实现快速启动。
• 显式执行：没有隐藏的抽象层，你可以直接控制内存布局和内核调度。
• 硬件感知：自动利用 SIMD 指令集（如 AVX-512, NEON）加速计算。

更多高级示例（如 Qwen3 推理、GPT-2 生成、自编码器训练）请参考项目 examples/ 目录。