MLC-LLM

通过机器学习编译实现通用的 LLM 部署 — 使用机器学习编译在任何硬件上以最高性能运行任何大型语言模型。

🌟 20,000+ GitHub 收藏星 | 由 MLC AI 团队维护 | Apache-2.0 许可证

---

什么是 MLC-LLM？

MLC-LLM（用于大型语言模型的机器学习编译）是一个通用框架，可实现大型语言模型在多种硬件后端上的高效部署。通过利用 TVM（Tensor Virtual Machine） 作为其编译后端，MLC-LLM 将 LLM 模型直接编译为本地硬件代码——在无需针对特定硬件进行工程优化的情况下实现接近最优的性能。

关键能力

• 通用硬件支持 — NVIDIA CUDA、AMD ROCm、Apple Metal、Vulkan、WebGPU

• 兼容 OpenAI 的 REST API — 可作为现有工作流的无缝替代

• 多种模型格式 — Llama、Mistral、Gemma、Phi、Qwen、Falcon 等等

• 4 位 / 8 位 量化 — 在消费级 GPU 上运行大型模型

• 聊天界面 — 内置网页 UI 以便立即测试

• Python 与 CLI 工具 — 灵活的集成选项

为什么在 Clore.ai 上使用 MLC-LLM？

Clore.ai GPU 市场为您提供具有竞争租金价格的高性能 NVIDIA GPU。MLC-LLM 的编译方法能从每块 GPU 中榨取最大吞吐量——使其非常适合于：

• 规模化的生产 API 推理

• 跨模型规模的研究与基准测试

• 使用量化模型的成本高效服务

• 在单个 GPU 实例上部署多模型

---

在 Clore.ai 上快速开始

步骤 1：查找 GPU 服务器

1. 前往 clore.ai 市场

2. 筛选服务器： NVIDIA GPU，最少 8GB 显存 （建议 16GB+ 以运行 7B+ 模型）

3. 为获得最佳性能：RTX 3090、RTX 4090、A100 或 H100

步骤 2：部署 MLC-LLM

注意： MLC-LLM 未在 Docker Hub 发布官方预构建的 Docker 镜像。推荐的部署方式是使用 NVIDIA CUDA 基础镜像并通过 pip 安装 MLC-LLM。使用 nvidia/cuda:12.1.0-devel-ubuntu22.04 作为您在 Clore.ai 上的基础镜像。

在您的 Clore.ai 订单配置中使用 NVIDIA CUDA 基础镜像：

Docker 镜像：nvidia/cuda:12.1.0-devel-ubuntu22.04

端口映射：

容器端口	用途
22	SSH 访问
8000	REST API 服务器

推荐的环境变量：

MLC_MODEL=HF://mlc-ai/Llama-3-8B-Instruct-q4f16_1-MLC
MLC_HOST=0.0.0.0
MLC_PORT=8000

启动脚本 （SSH 登录后运行）：

pip install --pre -U -f https://mlc.ai/wheels mlc-llm-nightly-cu121 mlc-ai-nightly-cu121

步骤 3：通过 SSH 连接

ssh root@<clore-node-ip> -p <assigned-ssh-port>

---

安装与设置

选项 A：使用预编译模型（最快）

MLC-AI 在 Hugging Face 上维护着一库预编译模型。无需编译：

# 拉取并运行预编译的 Llama 3 8B（4 位量化）
python -m mlc_llm serve HF://mlc-ai/Llama-3-8B-Instruct-q4f16_1-MLC \
  --host 0.0.0.0 \
  --port 8000

选项 B：编译您自己的模型

对于自定义模型或特定的量化需求：

# 第 1 步：转换模型权重
python -m mlc_llm convert_weight \
  ./path/to/model \
  --quantization q4f16_1 \
  --output ./compiled/model-q4f16_1

# 第 2 步：生成模型配置
python -m mlc_llm gen_config \
  ./path/to/model \
  --quantization q4f16_1 \
  --conv-template llama-3 \
  --output ./compiled/model-q4f16_1

# 第 3 步：编译模型
python -m mlc_llm compile \
  ./compiled/model-q4f16_1/mlc-chat-config.json \
  --device cuda \
  --output ./compiled/model-q4f16_1/lib.so

编译时间： 在第一次运行时编译一个 7B 模型通常需要 10–30 分钟。编译产物会被缓存并在后续启动中重复使用。

---

运行 API 服务器

启动兼容 OpenAI 的服务器

python -m mlc_llm serve \
  HF://mlc-ai/Llama-3-8B-Instruct-q4f16_1-MLC \
  --host 0.0.0.0 \
  --port 8000 \
  --max-batch-size 4 \
  --max-total-sequence-length 8192

服务器启动输出

[2024-01-01 12:00:00] INFO: 正在从 HF://mlc-ai/Llama-3-8B-Instruct-q4f16_1-MLC 加载模型
[2024-01-01 12:00:15] INFO: 模型加载成功
[2024-01-01 12:00:15] INFO: 服务器已在 0.0.0.0:8000 启动
[2024-01-01 12:00:15] INFO: 兼容 OpenAI 的 API 可在 http://0.0.0.0:8000/v1 使用

可用的 API 端点

端点	方法	描述
/v1/chat/completions	POST	聊天补全（OpenAI 格式）
/v1/completions	POST	文本补全
/v1/models	GET	列出可用模型
/v1/debug/dump_event_trace	GET	性能调试

---

API 使用示例

聊天补全（Python）

from openai import OpenAI

# 指向您的 Clore.ai 服务器
client = OpenAI(
    base_url="http://<clore-node-ip>:<api-port>/v1",
    api_key="none"  # 默认情况下 MLC-LLM 不要求身份验证
)

response = client.chat.completions.create(
    model="Llama-3-8B-Instruct-q4f16_1-MLC",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "用简单的语言解释量子计算。"}
    ],
    temperature=0.7,
    max_tokens=512
)

print(response.choices[0].message.content)

流式响应

stream = client.chat.completions.create(
    model="Llama-3-8B-Instruct-q4f16_1-MLC",
    messages=[{"role": "user", "content": "写一个关于 AI 的短篇故事。"}],
    stream=True,
    max_tokens=1024
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

cURL 示例

curl http://<clore-node-ip>:<api-port>/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Llama-3-8B-Instruct-q4f16_1-MLC",
    "messages": [
      {"role": "user", "content": "2+2 等于多少？"}
    ],
    "temperature": 0.7,
    "max_tokens": 100
  }'

---

可用的预编译模型

MLC-AI 在 Hugging Face 上提供可直接使用的已编译模型：

Llama 3 系列

# 8B Instruct（推荐用于大多数使用场景）
HF://mlc-ai/Llama-3-8B-Instruct-q4f16_1-MLC

# 70B Instruct（需要 40GB+ 显存或多 GPU）
HF://mlc-ai/Llama-3-70B-Instruct-q4f16_1-MLC

Mistral / Mixtral

HF://mlc-ai/Mistral-7B-Instruct-v0.3-q4f16_1-MLC
HF://mlc-ai/Mixtral-8x7B-Instruct-v0.1-q4f16_1-MLC

Gemma

HF://mlc-ai/gemma-2b-it-q4f16_1-MLC
HF://mlc-ai/gemma-7b-it-q4f16_1-MLC

Phi

HF://mlc-ai/phi-2-q4f16_1-MLC
HF://mlc-ai/Phi-3-mini-4k-instruct-q4f16_1-MLC

完整模型列表： 在以下地址浏览所有预编译模型： huggingface.co/mlc-ai

---

量化选项

MLC-LLM 支持多种量化方案。根据您的显存预算选择：

量化	位数	速度	显存（7B）	显存（13B）
q4f16_1	4 位	★★★★☆	≈4GB	~7GB
q4f32_1	4 位（f32 累加）	★★★★☆	≈4GB	~7GB
q8f16_1	8 位	★★★★★	≈8GB	≈14GB
q0f16	16 位（无量化）	★★★★★	≈14GB	~26GB
q0f32	32 位（无量化）	★★★★★	~28GB	~52GB

显存建议： 始终留出 2–3GB 的余量以应对 CUDA 开销和 KV 缓存。带有 q4f16_1 在典型工作负载下大约需要 ~6–7GB 的总显存。

---

多 GPU 部署

对于需要多 GPU 的大型模型（70B+）：

# 在 2 块 GPU 上启用张量并行
python -m mlc_llm serve \
  HF://mlc-ai/Llama-3-70B-Instruct-q4f16_1-MLC \
  --host 0.0.0.0 \
  --port 8000 \
  --tensor-parallel-shards 2

在部署前检查 GPU 拓扑：

nvidia-smi topo -m  # 检查 NVLink/PCIe 互联

最佳性能： 多 GPU 在 NVLink 互联的显卡（例如 A100 80GB SXM 配对）上表现最佳。通过 PCIe 互联的 GPU 在大型模型上会出现瓶颈。

---

网页聊天界面

MLC-LLM 包含一个内置网页 UI，服务器运行后可访问：

# 启用网页 UI 启动服务器
python -m mlc_llm serve \
  HF://mlc-ai/Llama-3-8B-Instruct-q4f16_1-MLC \
  --host 0.0.0.0 \
  --port 8000 \
  --enable-debug  # 可选：启用调试端点

在以下地址访问 UI： http://<clore-node-ip>:<api-port>

---

性能调优

优化批量大小

# 增大批量大小以提高吞吐量（需要更多显存）
python -m mlc_llm serve \
  HF://mlc-ai/Llama-3-8B-Instruct-q4f16_1-MLC \
  --host 0.0.0.0 \
  --port 8000 \
  --max-batch-size 8 \
  --max-total-sequence-length 16384 \
  --prefill-chunk-size 2048

监控 GPU 使用率

# 在另一个终端中
watch -n 1 nvidia-smi

# 更详细的监控
nvidia-smi dmon -s u  # 流式利用率指标

基准吞吐量测试

import base64
from openai import OpenAI

client = OpenAI(base_url="http://localhost:8000/v1", api_key="none")

start = time.time()
response = client.chat.completions.create(
    model="Llama-3-8B-Instruct-q4f16_1-MLC",
    messages=[{"role": "user", "content": "从 1 数到 100"}],
    max_tokens=512
)
elapsed = time.time() - start

tokens = response.usage.completion_tokens
print(f"吞吐量: {tokens/elapsed:.1f} tokens/sec")

---

Docker Compose 设置

对于在 Clore.ai 上使用 NVIDIA CUDA 基础镜像并通过 pip 安装 MLC-LLM 的生产就绪部署：

version: '3.8'
services:
  mlc-llm:
    image: nvidia/cuda:12.1.0-devel-ubuntu22.04
    runtime: nvidia
    environment:
      - NVIDIA_VISIBLE_DEVICES=all
    ports:
      - "8000:8000"
    volumes:
      - ./models:/root/models
      - mlc-cache:/root/.cache/mlc_llm
    command: >
      bash -c "pip install --pre -U -f https://mlc.ai/wheels mlc-llm-nightly-cu121 mlc-ai-nightly-cu121 &&
      python -m mlc_llm serve
      HF://mlc-ai/Llama-3-8B-Instruct-q4f16_1-MLC
      --host 0.0.0.0
      --port 8000
      --max-batch-size 4"
    restart: unless-stopped

volumes:
  mlc-cache:

---

故障排除

模型下载失败

# 检查网络连接
curl -I https://huggingface.co

# 使用 huggingface-cli 手动下载
pip install huggingface_hub
huggingface-cli download mlc-ai/Llama-3-8B-Instruct-q4f16_1-MLC

显存不足（OOM）

# 减少上下文长度
python -m mlc_llm serve MODEL \
  --max-total-sequence-length 4096  # 从默认值减少

# 使用更激进的量化
# 从 q8f16_1 切换到 q4f16_1

CUDA 版本不匹配

# 检查 CUDA 版本
nvcc --version
nvidia-smi | grep CUDA

# 对于 CUDA 12.1 的服务器，安装：
pip install --pre -U -f https://mlc.ai/wheels mlc-llm-nightly-cu121 mlc-ai-nightly-cu121

# 对于 CUDA 12.2+ 的服务器，安装：
pip install --pre -U -f https://mlc.ai/wheels mlc-llm-nightly-cu122 mlc-ai-nightly-cu122

常见陷阱： MLC-LLM 的 pip wheel 与 CUDA 版本相关。请确保安装与服务器 CUDA 版本匹配的变体。可在以下位置查看可用的 wheel： mlc.ai/wheels.

服务器无法访问

# 验证端口是否在监听
ss -tlnp | grep 8000

# 检查防火墙
iptables -L -n | grep 8000

# 先在本地测试
curl http://localhost:8000/v1/models

---

Clore.ai 的 GPU 建议

MLC-LLM 的编译方法能在所有 GPU 级别上提供接近最优的吞吐量。根据模型大小和预算进行选择：

GPU	显存（VRAM）	Clore.ai 价格	适合用于	吞吐量（Llama 3 8B Q4）
RTX 3090	24 GB	~$0.12/小时	7B–13B 模型，预算型服务	~85 令牌/秒
RTX 4090	24 GB	~$0.70/小时	7B–34B 模型，快速服务	~140 tok/s
A100 40GB	40 GB	~$1.20/小时	34B–70B，生产 API	~110 tok/s
💡 本指南中的所有示例均可部署在	80 GB	~$2.00/小时	70B+，多模型服务	~130 tok/s
H100 SXM	80 GB	~$3.50/小时	最大吞吐量，FP8	~280 令牌/秒

推荐起点： 对于通过 MLC-LLM 提供 Llama 3 8B 和 Mistral 7B 服务，RTX 3090（约 $0.12/小时）在性价比上表现最佳。已编译的内核能从消费级 GPU 中提取接近最大利用率。

对于 70B 模型（例如 Llama 3 70B Q4）：使用 A100 40GB（约 $1.20/小时）或通过张量并行使用两块 RTX 3090。

---

资源

• 📦 Pip Wheels： mlc.ai/wheels （通过 pip 安装，未提供 Docker Hub 镜像）

• 🐙 GitHub： github.com/mlc-ai/mlc-llm

• 📚 文档： llm.mlc.ai/docs

• 🤗 预编译模型： huggingface.co/mlc-ai

• 💬 Discord： discord.gg/9Xpy2HGBuD