zml/zml · 上手攻略

  • 仓库：zml/zml
  • 链接：https://github.com/zml/zml
  • 分类：llm-infra · framework · trending
  • 作者：Tom
  • 更新：2026-07-09

这是什么

ZML（Z Machine Learning）是一个生产级 AI 推理技术栈，旨在将任意模型部署到任意硬件加速器上，零妥协。

它基于 Zig 语言、MLIR 编译框架和 Bazel 构建系统实现，支持 NVIDIA CUDA、AMD RoCM、Intel OneAPI、Google TPU、AWS Trainium/Inferentia 2 等多种加速器后端。用户在同一套代码库上无需重写，即可在不同硬件平台间切换并获得峰值性能。

项目定位介于研究原型和生产级框架之间（Maturity: research），适合需要跨硬件部署、对性能有较高要求的团队。

解决什么问题

  • 硬件锁定：用 PyTorch 或 vLLM 部署时，若需切换到 AMD GPU 或 TPU，往往需要重写 CUDA kernels 或使用兼容性差的方案。
  • 多硬件统一优化：在异构集群（如同时有 NVIDIA 和 AWS Trainium 的服务器）中，缺乏统一的高性能推理抽象。
  • 编译时优化：JIT 方式在不同硬件上性能参差不齐，ZML 采用 MLIR 编译路径，在编译期做硬件针对性的优化。
  • 部署复杂度：用 Bazel 打包后可直接部署到服务器，无需 Python 运行时依赖，降低生产环境复杂度。

快速安装

环境要求

  • Bazel（通过 bazelisk 版本管理器安装）
  • Zig 语言（ZML 本身由 Zig 编写，但bazel build 会自动处理依赖）
  • 对应硬件的驱动/SDK（如 CUDA Toolkit for NVIDIA）

安装 Bazel

# macOS
brew install bazelisk

# Linux
curl -L -o /usr/local/bin/bazel \
  'https://github.com/bazelbuild/bazelisk/releases/download/v1.28.1/bazelisk-linux-amd64'
chmod +x /usr/local/bin/bazel

克隆代码库

git clone https://github.com/zml/zml.git
cd zml/

⚠️ ZML 不提供 pip/npm 等包管理器安装，需通过源码克隆 + Bazel 构建，不支持 Windows。

核心用法

运行 MNIST 示例（最快上手）

MNIST 是 ZML 自带的最小完整示例，bazel 会自动下载预训练模型和测试数据：

bazel run --config=release //examples/mnist

无任何参数，会下载 MNIST 预训练模型、编译、加载权重，并随机选取一个手写数字进行分类。

运行 LLM（主要示例）

ZML 目前支持 Llama 3.1 / 3.2、Qwen 3.5、LFM 2.5。

Hugging Face 认证（访问 gated 模型如 Meta Llama 需要）：

bazel run //tools/hf -- auth login

或者设置环境变量：

export HF_TOKEN="your_huggingface_token"

运行 Llama 3.2 1B（较小模型，适合本地测试）：

bazel run --config=release //examples/llm \
  -- --model=hf://meta-llama/Llama-3.2-1B-Instruct \
  --prompt="What is the capital of France?"

交互式对话模式（省略 --prompt）：

bazel run --config=release //examples/llm \
  -- --model=hf://meta-llama/Llama-3.2-1B-Instruct

指定模型来源：

# 本地路径
bazel run //examples/llm -- --model=/var/models/Llama-3.2-1B-Instruct

# S3
bazel run //examples/llm -- --model=s3://bucket/path/to/model

跨硬件运行

通过 --@zml//platforms:xxx=true 标志指定硬件平台：

硬件 标志 说明
NVIDIA CUDA --@zml//platforms:cuda=true 需要 CUDA Toolkit
AMD RoCM --@zml//platforms:rocm=true 需要 ROCm SDK
Intel OneAPI --@zml//platforms:oneapi=true 需要 OneAPI
Google TPU --@zml//platforms:tpu=true 需要 TPU 运行时
AWS Trainium/Inferentia2 --@zml//platforms:neuron=true 需要 Neuron SDK
禁用 CPU --@zml//platforms:cpu=false 加速编译，节省时间

示例：在 NVIDIA GPU 上运行 Llama

bazel run --config=release //examples/llm \
  --@zml//platforms:cuda=true \
  -- \
  --model=hf://meta-llama/Llama-3.2-1B-Instruct \
  --prompt="Write a haiku about Zig"

示例：在 AMD RoCM 上运行

bazel run --config=release //examples/llm \
  --@zml//platforms:rocm=true \
  -- \
  --model=hf://meta-llama/Llama-3.2-1B-Instruct \
  --prompt="Write a haiku about Zig"

测试

bazel test //zml:test

其他示例

示例 说明
//examples/sharding 逻辑 mesh、分片器、分片本地执行、性能分析
//examples/io 检查和加载本地/hf:// / https:// / s3:// 的模型文件
//examples/benchmark 测量加载和执行性能

Zig 代码示例（MNIST 模型定义）

ZML 模型用 Zig 语言编写，以下是一个完整前向传播示例：

const Mnist = struct {
    fc1: Layer,
    fc2: Layer,

    const Layer = struct {
        weight: zml.Tensor,
        bias: zml.Tensor,

        pub fn init(store: zml.io.TensorStore.View) Layer {
            return .{
                .weight = store.createTensor("weight", .{ .d_out, .d }, null),
                .bias = store.createTensor("bias", .{.d_out}, null),
            };
        }

        pub fn forward(self: Layer, input: zml.Tensor) zml.Tensor {
            return self.weight.dot(input, .d).add(self.bias).relu().withTags(.{.d});
        }
    };

    pub fn forward(self: Mnist, input: zml.Tensor) zml.Tensor {
        var x = input.flatten().convert(.f32).withTags(.{.d});
        for (&.{ self.fc1, self.fc2 }) |layer| {
            x = layer.forward(x);
        }
        return x.argMax(0).indices.convert(.u8);
    }
};

典型适用场景

  • 异构推理集群：同一代码库在 NVIDIA、AMD、TPU 等多硬件上运行，适合有跨平台需求的 AI 基础设施团队。
  • 硬件基准测试：在同一模型上对比不同加速器的性能表现。
  • 新兴硬件适配：AWS Trainium、Intel Gaudi 等新加速器缺乏成熟 Python 生态时，ZML 提供 MLIR 层面的统一抽象。
  • 极致推理优化：MLIR 编译路径允许在编译期针对特定硬件做 Fusion、量化等优化。
  • Zig 生态集成：已有 Zig 项目的团队可以直接使用 Zig 语言编写和部署模型，无需切换语言栈。

坑与注意

  1. 非 Windows：不支持 Windows 构建，只保证 Linux/macOS 可用。
  2. 无包管理器：不提供 pip/npm 等安装方式，必须 Bazel 构建，门槛较高。
  3. 文档有限：项目仍处于 research 阶段，API 变更频繁，示例覆盖不完整。
  4. 依赖 Hugging Face：LLM 示例默认从 Hugging Face 下载模型，Gated 模型需申请权限（Llama 通常需数小时审批）。
  5. 模型支持范围有限：当前仅明确支持 Llama 3.1/3.2、Qwen 3.5、LFM 2.5，其他模型需自行适配。
  6. bazelisk 必需：不能用原生 bazel，需通过 bazelisk 版本管理，否则依赖构建可能出错。
  7. 大模型本地运行：8B 模型在 CPU 上运行极其缓慢，即使 1B 模型也需要足够内存；大模型建议配合 GPU 使用。
  8. AWS Trainium 特殊 SDK：--@zml//platforms:neuron=true 需要提前安装 AWS Neuron SDK。

与同类对比

方案 语言 多硬件支持 编译优化 成熟度 适合人群
ZML Zig + MLIR NVIDIA/AMD/Intel/TPU/Trainium MLIR AOT Research 跨硬件基础设施团队
vLLM Python + CUDA NVIDIA 为主（实验性 AMD） PagedAttention Production 追求吞吐量的 LLM 推理
llama.cpp C/C++ CPU/GPU 多后端 Quantization Production 消费级硬件本地推理
MLX Swift/Python Apple Silicon MLX 框架 Production Apple 芯片用户
Torch.compile Python NVIDIA/AMD（有限） TorchInductor Beta 已有 PyTorch 工作流

ZML 的差异化在于 MLIR 层面的硬件抽象，适合需要硬件切换或跨平台部署的底层系统工程师，而非应用层开发者。

一句话推荐结论

ZML 是目前开源生态中硬件抽象层最底层的多硬件推理框架，适合需要跨 NVIDIA/AMD/TPU/Trainium 部署、愿意接受较高使用门槛的基础设施团队。

来源

  • GitHub README: https://github.com/zml/zml
  • Getting Started: https://github.com/zml/zml/blob/master/docs/tutorials/getting_started.md
  • Write First Model: https://github.com/zml/zml/blob/master/docs/tutorials/write_first_model.md
  • ZML Concepts: https://github.com/zml/zml/blob/master/docs/learn/concepts.md
  • Deploy on Server: https://github.com/zml/zml/blob/master/docs/howtos/deploy_on_server.md
  • Dockerize Models: https://github.com/zml/zml/blob/master/docs/howtos/dockerize_models.md
  • LLM Example README: https://github.com/zml/zml/blob/master/examples/llm/README.md