📦 Modular Platform (MAX & Mojo) 部署教程

Modular Platform 是一个统一的 AI 开发和部署平台，主要包括 MAX Framework（用于高性能模型服务）和 Mojo 编程语言（用于 AI 基础设施编程）。部署 Modular 并不需要克隆这个 GitHub 仓库，官方推荐通过包管理器直接安装。

🚀 部署 MAX Framework（模型服务）

MAX 是一个用于高性能模型推理的框架。部署 MAX 的核心是启动一个 OpenAI 兼容的模型服务端点。

1. 系统要求与准备

  • 操作系统：macOS 或 Linux（不支持 Windows）。
  • GPU（强烈推荐）：为了获得最佳性能，建议使用数据中心级 GPU，如 NVIDIA H100 或 AMD MI300X 系列。也可以在 Mac 或 CPU 上运行，但兼容的模型会更少，性能会较慢。
  • 包管理器：推荐使用 pixi 或 uv，以隔离项目环境。

2. 安装 modular 包

使用 pixi（推荐）：

1
2
3
4
5
6
# 安装 pixi
curl -fsSL https://pixi.sh/install.sh | sh
# 创建并进入项目，添加 modular 包（nightly 版本）
pixi init quickstart -c https://conda.modular.com/max-nightly/ -c conda-forge && cd quickstart
pixi add modular
pixi shell  # 激活虚拟环境

使用 uv：

1
2
3
4
5
6
# 安装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh
# 创建项目并安装 modular
uv init quickstart && cd quickstart
uv venv && source .venv/bin/activate
uv pip install modular --index https://whl.modular.com/nightly/simple/ --prerelease allow

3. 启动模型端点

使用 max serve 命令启动一个本地模型服务。你需要先从 Hugging Face 获取模型访问权限并设置 HF_TOKEN。

1
2
3
4
5
# 设置 Hugging Face 访问令牌
export HF_TOKEN="hf_..."

# 启动一个 Gemma 模型端点（示例）
max serve --model google/gemma-4-31B-it

首次运行会下载模型并进行编译，需要一定时间。服务启动后，你会看到 🚀 Server ready on http://0.0.0.0:8000 的提示。

4. 发送推理请求

在另一个终端中，使用 OpenAI Python 库向本地端点发送请求：

1
2
3
4
5
6
7
from openai import OpenAI
client = OpenAI(base_url="http://localhost:8000/v1", api_key="EMPTY")
completion = client.chat.completions.create(
    model="google/gemma-4-31B-it",
    messages=[{"role": "user", "content": "Who won the world series in 2020?"}],
)
print(completion.choices[0].message.content)

🐳 使用 Docker 容器部署（生产推荐）

Modular 提供了针对 NVIDIA 和 AMD GPU 优化的 Docker 容器，方便在云环境或 Kubernetes 中部署。

拉取并运行 NVIDIA GPU 容器：

1
2
3
4
5
docker run --gpus=1 \
    -v ~/.cache/huggingface:/root/.cache/huggingface \
    -p 8000:8000 \
    modular/max-nvidia-full:latest \
    --model google/gemma-3-27b-it

此命令会挂载 Hugging Face 缓存目录，并将容器内的 8000 端口映射到宿主机。

🔥 安装 Mojo 编程语言

Mojo 是 Modular 推出的高性能 AI 编程语言。同样，你无需克隆此仓库即可安装 Mojo。

1. 系统要求

  • 操作系统：macOS (Apple Silicon) 或 Linux (x86_64/aarch64)。Windows 暂不支持。
  • Python 环境：需要 Python 3.10 或更高版本。

2. 安装方式

使用 pip（简单）：

1
pip install mojo

如果想安装 nightly 构建版：

1
pip install --pre mojo --extra-index-url https://whl.modular.com/nightly/simple/

使用 pixi 或 uv（推荐，更规范）：

1
2
# 使用 pixi 安装 nightly 版本
pixi global install mojo -c conda-forge -c https://conda.modular.com/max-nightly

安装后，你可以通过 mojo --version 验证。

3. 编写并运行 Mojo 程序

创建一个 hello.mojo 文件，内容如下：

1
print("Hello from Mojo!")

在终端运行：

1
mojo hello.mojo

你也可以在 VS Code 中安装官方 Mojo 扩展，以获得语法高亮、代码补全和调试支持。

🛠️ 从源码开发（面向贡献者）

如果你希望修改 MAX 框架的源代码或为 Modular 项目做贡献，可以克隆此 GitHub 仓库进行开发。

关键步骤：

  1. 克隆仓库：git clone https://github.com/modular/modular.git
  2. 安装开发依赖：系统需满足 MAX 的系统要求，并安装 pixi 和 Bazel。
  3. 运行测试：在仓库根目录执行 ./bazelw test //max/... 来运行所有测试。

详细的开发指南请参考项目中的 CONTRIBUTING.md 和 max/docs/development.md。

❓ 常见问题 (FAQ)

  • 我是否需要克隆此 GitHub 仓库才能使用 Modular？
    • 不需要。使用 Modular 平台（MAX 和 Mojo）的标准方式是通过 pip、pixi 或 uv 等包管理器安装。克隆仓库是为了贡献代码或从源码构建。
  • Windows 系统是否支持？
    • 目前 Modular Platform 的官方工具（MAX SDK, Mojo）不支持 Windows。你可以在 Windows 的 WSL 2 环境中使用 Linux 子系统。
  • MAX 会开源吗？
    • Modular 正在逐步开源 MAX 框架的部分组件，包括 Python 服务库、模型架构和 GPU 内核，但完整平台目前并非全部开源。
  • 如何更新 Mojo？
    • 如果你是用 pip 安装的，运行 pip install --upgrade mojo。如果使用 pixi，运行 pixi update mojo。

更多详细信息、支持的模型列表和高级配置，请务必查阅 Modular 官方文档。