Magnitude 详细部署教程

Magnitude 是一个开源推理服务器，它能自动识别你的硬件配置，推荐最适合的本地模型，并下载、调优、运行它们。与 Ollama 等通用推理工具不同，Magnitude 专为编程 Agent 工作负载设计，能直接对接你已经在使用的 Pi、OpenCode、Codex、Claude Code、Cline 等 Agent 。

本教程将引导你完成 Magnitude 的安装、配置和本地模型部署。

1. 准备工作

1.1 操作系统与环境要求

Magnitude 官方支持 macOS 和 Linux。Windows 用户可以通过 WSL (Windows Subsystem for Linux) 使用。

要求项	建议
操作系统	macOS (推荐 Apple Silicon), Linux (Ubuntu/Debian), Windows (通过 WSL)
内存	至少 8GB，推荐 16GB 以上以流畅运行 7B-8B 参数模型
网络	首次安装和下载模型时需要网络连接
Node.js	需要 Node.js 环境

注意：针对 Apple Silicon (M系列芯片) 用户，Magnitude 的 infer 包经过专门优化，能高效运行大型模型（如 Qwen 系列）。

1.2 理解概念：Magnitude 是什么

需要理清 Magnitude 的定位：

Magnitude CLI：一个命令行工具，用于模型推荐、下载和 Agent 配置。
Magnitude Inference Server：一个本地推理服务，基于 llama.cpp 构建，为 Agent 工作负载提供优化的模型运行环境。它负责加载模型、处理推理请求。
Magnitude Agent：一个可以运行在本地模型上的编码 Agent（类似 Claude Code 的角色）。

简单来说，部署 Magnitude 就是部署一个 专为 Agent 优化的本地模型运行环境。

2. 安装 Magnitude CLI

安装过程非常直接，通过 npm 全局安装即可。

打开终端，执行以下命令：

1	npm install -g @magnitudedev/cli

验证安装是否成功：

1	magnitude --version

3. 设置与配置

首次运行 magnitude 命令会启动一个交互式设置流程，帮助你完成硬件分析、模型选择和下载。

3.1 运行设置向导

在你的项目目录中，执行：

1	magnitude setup

magnitude setup 命令会自动开始以下流程：

硬件分析：检测 CPU、内存、GPU 等信息。
模型推荐：根据你的硬件，列出最适合运行的模型和量化版本，并给出预估的推理速度 (tokens/秒)。
模型下载：让你从推荐列表中选择模型，然后自动下载。

你还可以选择让已有的 Agent 辅助完成设置。向你的 Agent（例如 Claude Code）发送以下指令：

“Set up local models for me with the Magnitude CLI. Install it with npm i -g @magnitudedev/cli, then run magnitude docs onboarding and follow the instructions.”

3.2 连接你的 Agent

设置完成后，Magnitude 会知道你要用哪个 Agent（如 Codex、Claude Code 等）。它会自动配置该 Agent，使其连接到你刚下载的本地模型。

也就是说，一旦配置完成，你启动 Codex 等 Agent 时，它会自动使用 Magnitude 运行的本地模型进行推理，无需额外配置。

3.3 后台运行与服务管理

自动管理：Magnitude 的推理服务会默认在后台运行。它采用 按需加载 (Load on Demand) 策略：当 Agent 发起请求时，模型会被加载到内存；当长时间空闲或系统内存紧张时，模型会被自动卸载，释放资源。
手动管理：你可以通过 Magnitude CLI 管理模型和查看服务状态，具体命令可参考官方文档。

4. 高级部署与自托管推理服务

如果你需要深度定制推理服务（如使用不同的模型、调整端口等），可以手动部署 Magnitude 的推理核心。

4.1 系统要求与获取代码

硬件：此方式特别针对 Apple Silicon Mac (M1/M2/M3/M4) 优化，推荐 32GB 以上统一内存以运行 27B-32B 参数的模型。
软件：需要 Python 环境及 uv 包管理工具。

从 GitHub 克隆项目源码（以探索 infer 目录为例）：

1 2	git clone https://github.com/magnitudedev/magnitude.git cd magnitude/infer

4.2 配置推理服务环境

推理服务 (infer 目录) 是一个 Python 项目，通过环境变量进行配置。

你可以创建一个 .env 文件（或直接在终端设置），常用变量如下：

变量	默认值	说明
`INFER_MODEL`	`mlx-community/Qwen3.5-27B-6bit`	HuggingFace 上的模型 ID
`INFER_HOST`	`127.0.0.1`	服务绑定的地址
`INFER_PORT`	`8012`	服务监听的端口

4.3 启动自托管推理服务

在 infer 目录下，使用 uv 运行服务启动脚本：

1	uv run serve.py

首次运行：uv 会自动安装 pyproject.toml 中定义的依赖（如 vllm-mlx），并开始下载你指定的模型。
验证服务：服务启动后，可通过以下命令验证其 OpenAI 兼容 API 是否正常工作：
1
curl http://127.0.0.1:8012/v1/models
服务成功运行后，你需要配置你的 Agent (如 OpenCode) 指向这个本地 API 端点。

5. 故障排除

问题	可能原因与解决方案
`magnitude` 命令未找到	确保全局 npm 包的 bin 目录在系统 `PATH` 中。可尝试重新打开终端或使用 `npx @magnitudedev/cli`。
设置向导无法下载模型	检查网络连接。可以考虑设置代理，或直接从 Hugging Face 等网站手动下载 GGUF 模型并放置到指定目录。
推理服务启动失败 (Apple Silicon)	确认已安装 `uv`。检查 `infer` 目录下的依赖是否完整。确保模型 ID 正确且可访问。
Agent 无法连接到本地模型	1. 确认推理服务正在运行。2. 检查 Agent 的配置是否指向了正确的 `localhost` 端口。3. 重新运行 `magnitude setup`，让 CLI 重新配置 Agent 的连接。
运行大模型时内存不足	1. 在设置向导中选择更小的模型或更高压缩比的量化版本。2. 调整 `INFER_MODEL` 环境变量，使用更小的模型。3. 关闭其他占用内存的应用。