企业官网建设流程全解析

self-llm 教程实战：用 SGLang 部署 MiniMax-M3，完成 512K 长上下文推理、图片输入与工具调用

【免费下载链接】self-llm《开源大模型食用指南》针对中国宝宝量身打造的基于Linux环境快速微调（全参数/Lora）、部署国内外开源大模型（LLM）/多模态大模型（MLLM）教程项目地址: https://gitcode.com/datawhalechina/self-llm

本文以《开源大模型食用指南》（self-llm）仓库中的 MiniMax-M3 SGLang 部署教程 为主体，完整覆盖从环境准备、显存规划、模型下载、SGLang 服务启动（4 卡 / 8 卡）到客户端调用的全流程：读完你能掌握 MiniMax-M3 在 SGLang 上的标准部署姿势（含--tp-size/--ep-size等关键参数取值），并能用 OpenAI 兼容接口完成聊天、流式输出、图片输入（Vision）和工具调用（Tool Calling）四类实战调用。

一、模型与框架：为什么选 MiniMax-M3 + SGLang

MiniMax-M3 的能力基线

MiniMax-M3 是 MiniMax 推出的新一代开源大语言模型（模型 ID 为MiniMaxAI/MiniMax-M3）。相较上一代 M2.5，M3 在长上下文、推理质量与多模态能力上均有明显提升，核心规格为：

• 上下文窗口扩展到 512K，单次最大输出可达128K token；
• 原生支持图片输入：OpenAI 兼容与 Anthropic 兼容两套接口均可携带图片，目前仅支持图片，视频 / 音频 / 文档暂不支持；
• 官方推荐采样参数：temperature=1.0、top_p=0.95、top_k=20。

从仓库内同系列的 Transformers 部署教程 可以补充确认 M3 的模型侧环境参考值：Python 3.9–3.12、GPU 计算能力 7.0 及以上、权重显存需求约 220 GB。这些前提同样适用于 SGLang 部署场景。

SGLang 的推理框架定位

SGLang是一个面向大语言模型的高性能部署推理框架，提供开箱即用的推理加速与 OpenAI 兼容接口，能力包括：长上下文推理、流式输出、多卡并行（张量并行 TP 与专家并行 EP）、工具调用解析与“思考内容”解析等，便于将最新模型快速落地到生产环境。

仓库中的其他部署路线（交叉参考）

self-llm 仓库为 MiniMax-M3 提供了三条并行的部署教程，读者可按硬件与场景选择：

三者模型 ID 一致（MiniMaxAI/MiniMax-M3），客户端调用方式（OpenAI 兼容接口）也基本一致，主要差异集中在服务启动参数上。此外，仓库中 模型支持清单 也收录了这组 MiniMax-M3 教程索引。

二、环境准备与显存规划

基础环境自检

部署前先用两条命令确认 CUDA 与 PyTorch 状态：

nvidia-smi python -c "import torch; print(torch.version.cuda, torch.cuda.is_available())"

显存与推荐 GPU 配置

按官方文档给出的显存口径（教程原文数据）：

• 权重需求约220 GB显存；每 1M 上下文 token 约需240 GB显存；
• 96G × 4 GPU：支持约40 万 token总上下文；
• 144G × 8 GPU：支持约300 万 token总上下文。

注意：单请求上下文窗口最大为 512K，单次最大输出为 128K；上表的“总上下文”是硬件支持的最大并发 KV 缓存总量，不等于单请求长度。请结合业务的并发数与单请求上下文长度评估资源，而不是只看单序列上限。

安装 SGLang

建议使用虚拟环境（venv / conda / uv）避免依赖冲突：

uv venv source .venv/bin/activate uv pip install sglang

版本要求：请确保所装 SGLang 版本支持 MiniMax-M3。可用pip show sglang查看当前安装版本，必要时执行pip install -U sglang升级。仓库中同家族的 MiniMax-M2.5 SGLang 教程 给出的口径是 MiniMax M2 系列要求 SGLang >= v0.5.4.post1，M3 作为更新的模型，以“升级到最新稳定版”为准。

三、模型下载

SGLang 会在首次启动时自动从 Hugging Face 拉取并缓存模型，严格来说无需手动下载。若希望提前下载、复用缓存，或受网络限制，可选用modelscope手动下载：

# model_download.py from modelscope import snapshot_download model_dir = snapshot_download('MiniMaxAI/MiniMax-M3', cache_dir='/root/autodl-tmp', revision='master') print(f"模型下载成功，保存到: {model_dir}")

pip install modelscope python model_download.py

cache_dir按实际磁盘路径调整（示例使用 AutoDL 的/root/autodl-tmp大容量盘）。

网络提示：使用modelscope下载时无需设置 HF 镜像。若不用 modelscope、而是让 SGLang 自动从 Hugging Face 拉取，网络受限时可设置镜像：export HF_ENDPOINT=https://hf-mirror.com。

下载完成后，可以把--model-path直接指向本地目录（/root/autodl-tmp/MiniMaxAI/MiniMax-M3），避免重复拉取；教程示例中则直接使用MiniMaxAI/MiniMax-M3这一模型 ID。

四、启动 SGLang 服务

方式一：Python 启动脚本（自动识别 4/8 卡）

新建start_server.py，脚本按检测到的 GPU 数量自动拼装启动命令：

import torch from sglang.utils import launch_server_cmd, wait_for_server gpu_count = torch.cuda.device_count() if torch.cuda.is_available() else 0 if gpu_count == 4: cmd = ( "python -m sglang.launch_server " "--model-path MiniMaxAI/MiniMax-M3 " "--host 0.0.0.0 " "--port 8000 " "--tp-size 4 " "--tool-call-parser minimax-m2 " "--reasoning-parser minimax-append-think " "--trust-remote-code " "--mem-fraction-static 0.85" ) elif gpu_count == 8: cmd = ( "python -m sglang.launch_server " "--model-path MiniMaxAI/MiniMax-M3 " "--host 0.0.0.0 " "--port 8000 " "--tp-size 8 " "--ep-size 8 " "--tool-call-parser minimax-m2 " "--reasoning-parser minimax-append-think " "--trust-remote-code " "--mem-fraction-static 0.85" ) else: raise RuntimeError(f"建议使用 4 或 8 张 GPU，当前检测到: {gpu_count}") server_process, port = launch_server_cmd(cmd, port=8000) wait_for_server(f"http://127.0.0.1:{port}") print(f"SGLang Server started: http://127.0.0.1:{port}")

启动：

python start_server.py

服务启动成功后将监听http://127.0.0.1:8000/v1。脚本中launch_server_cmd负责拉起服务进程，wait_for_server阻塞等待服务就绪后再打印地址，适合作为自动化部署的一环。

方式二：命令行直接启动

4 卡部署（仅张量并行）：

python -m sglang.launch_server \ --model-path MiniMaxAI/MiniMax-M3 \ --tp-size 4 \ --tool-call-parser minimax-m2 \ --reasoning-parser minimax-append-think \ --host 0.0.0.0 \ --trust-remote-code \ --port 8000 \ --mem-fraction-static 0.85

8 卡部署（张量并行 + 专家并行）：

python -m sglang.launch_server \ --model-path MiniMaxAI/MiniMax-M3 \ --tp-size 8 \ --ep-size 8 \ --tool-call-parser minimax-m2 \ --reasoning-parser minimax-append-think \ --trust-remote-code \ --host 0.0.0.0 \ --port 8000 \ --mem-fraction-static 0.85

由于模型权重约 220 GB，首次加载时间较长，可能需要半小时以上，请给加载过程留足耐心，不要中途 Ctrl+C 后反复重启。

关键启动参数解析

结合教程的参数说明一节，各参数含义与取值建议如下：

与 vLLM 路线教程 对照可知：同一套 MiniMax 解析能力，在 SGLang 中写作连字符风格的minimax-m2/minimax-append-think，而在 vLLM 中写作下划线风格的minimax_m2/minimax_m2_append_think（且 vLLM 需额外加--enable-auto-tool-choice）。两套框架参数风格不同，切换部署路线时不要互相照抄参数名。

采样参数方面，官方推荐temperature=1.0、top_p=0.95、top_k=20；M3 单次最大输出可达 128K token，客户端按业务需要设置max_tokens，不必为占满上限而浪费显存与延迟。

五、验证服务：curl 冒烟测试

服务就绪后，先用 curl 打一次 OpenAI 兼容接口做冒烟测试：

curl http://localhost:8000/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "model": "MiniMaxAI/MiniMax-M3", "messages": [ {"role": "system", "content": [{"type": "text", "text": "You are a helpful assistant."}]}, {"role": "user", "content": [{"type": "text", "text": "请简要介绍 MiniMax-M3 模型的特点。"}]} ] }'

注意 MiniMax 系模型的 messagecontent采用分块数组格式（[{"type": "text", "text": "..."}]），而非纯字符串——这与后文图片输入接口的结构保持一致。

六、客户端调用示例

以下示例均使用 OpenAI 官方 Python SDK 调用 SGLang 的 OpenAI 兼容接口，base_url统一指向http://127.0.0.1:8000/v1。

1. 聊天对话（Chat Completions）

# test_chat.py from openai import OpenAI client = OpenAI( api_key="EMPTY", base_url="http://127.0.0.1:8000/v1", ) response = client.chat.completions.create( model="MiniMaxAI/MiniMax-M3", messages=[ {"role": "user", "content": "请介绍 MiniMax-M3 相比 M2.5 有哪些提升？"} ], max_tokens=8192, top_p=0.95, temperature=1.0, ) msg = response.choices[0].message print("MiniMax-M3:", msg.content)

python test_chat.py

2. 流式输出（Streaming）

# test_streaming.py from openai import OpenAI client = OpenAI( api_key="EMPTY", base_url="http://127.0.0.1:8000/v1", ) stream = client.chat.completions.create( model="MiniMaxAI/MiniMax-M3", messages=[{"role": "user", "content": "请用 Python 实现一个二叉搜索树，包含插入、查找和删除操作。"}], stream=True, max_tokens=32768, top_p=0.95, temperature=1.0, ) for chunk in stream: delta = chunk.choices[0].delta if delta and delta.content: print(delta.content, end="", flush=True)

python test_streaming.py

长代码类任务（如实现整棵 BST）建议像示例一样把max_tokens放大到 32768 量级，避免输出被截断。

3. 图片输入（Vision）

MiniMax-M3 原生支持图片输入。在 OpenAI 兼容接口中，将image_url与文本一起放入content数组即可：

# test_vision.py from openai import OpenAI client = OpenAI(api_key="EMPTY", base_url="http://127.0.0.1:8000/v1") response = client.chat.completions.create( model="MiniMaxAI/MiniMax-M3", messages=[ { "role": "user", "content": [ {"type": "text", "text": "请描述这张图片中的内容。"}, { "type": "image_url", "image_url": {"url": "https://upload.wikimedia.org/wikipedia/commons/thumb/3/3a/Cat03.jpg/640px-Cat03.jpg"}, }, ], } ], max_tokens=4096, ) print(response.choices[0].message.content)

仅支持图片输入；视频、音频、文档暂不支持。image_url可以是公网 URL，实践中也可换成 Base64 Data URL 形式以支持本地图片。

4. 工具调用（Tool Calling）

MiniMax-M3 在 Agent 和工具调用方面继续保持强表现。SGLang 部署时通过--tool-call-parser minimax-m2启用工具调用解析后，即可用标准 function calling 协议发起调用：

# test_tool_calling.py from openai import OpenAI import json client = OpenAI(base_url="http://localhost:8000/v1", api_key="EMPTY") def get_weather(location: str, unit: str): return f"Getting the weather for {location} in {unit}..." tools = [{ "type": "function", "function": { "name": "get_weather", "description": "Get the current weather in a given location", "parameters": { "type": "object", "properties": { "location": {"type": "string", "description": "City and state, e.g., 'San Francisco, CA'"}, "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]} }, "required": ["location", "unit"] } } }] response = client.chat.completions.create( model=client.models.list().data[0].id, messages=[{"role": "user", "content": "北京今天天气怎么样？请用摄氏度。"}], tools=tools, tool_choice="auto" ) tool_call = response.choices[0].message.tool_calls[0].function print(f"Function called: {tool_call.name}") print(f"Arguments: {tool_call.arguments}") print(f"Result: {get_weather(**json.loads(tool_call.arguments))}")

python test_tool_calling.py

示例中model参数通过client.models.list()动态获取服务实际挂载的模型 ID，避免因模型命名不一致而报错。

七、常见问题

1. Hugging Face 网络问题

如果 SGLang 自动拉取模型时遇到网络问题，设置镜像后再进行拉取：

export HF_ENDPOINT=https://hf-mirror.com

或者直接改用 modelscope 预下载（见第三节），绕过 HF 网络。

2. 报错 “MiniMax-M3 model is not currently supported”

说明当前安装的 SGLang 版本尚未支持 M3，升级到最新稳定版即可：

pip install -U sglang

3. 显存不足 / OOM

优先调低--mem-fraction-static（如 0.85 → 0.8）；若业务并发不高，也可减少同时在线的长上下文请求数。反过来，调高该比例可扩大 KV 缓存池，但需为权重加载与激活峰值预留余量。

八、延伸：同一仓库中的 M3 微调与并发评测

部署调通之后，如果要把 M3 适配到垂直领域，同一目录下还有配套的微调教程：MiniMax-M3 BF16 LoRA 及 SwanLab 可视化微调，其训练脚本与数据集位于 finetune 目录（含 DeepSpeed ZeRO-3 配置与tiny_qa.jsonl示例数据），可把微调后的 LoRA 权重再回接到 SGLang 服务中使用。整个 MiniMax-M3 教程组（vLLM / SGLang / Transformers / 微调）在 support_model.md 的模型清单中均有索引，可对照选择适合自己硬件的路线。

【免费下载链接】self-llm《开源大模型食用指南》针对中国宝宝量身打造的基于Linux环境快速微调（全参数/Lora）、部署国内外开源大模型（LLM）/多模态大模型（MLLM）教程项目地址: https://gitcode.com/datawhalechina/self-llm