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

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 SGLangMiniMax-M3 的能力基线MiniMax-M3 是 MiniMax 推出的新一代开源大语言模型模型 ID 为MiniMaxAI/MiniMax-M3。相较上一代 M2.5M3 在长上下文、推理质量与多模态能力上均有明显提升核心规格为上下文窗口扩展到 512K单次最大输出可达128K token原生支持图片输入OpenAI 兼容与 Anthropic 兼容两套接口均可携带图片目前仅支持图片视频 / 音频 / 文档暂不支持官方推荐采样参数temperature1.0、top_p0.95、top_k20。从仓库内同系列的 Transformers 部署教程 可以补充确认 M3 的模型侧环境参考值Python 3.9–3.12、GPU 计算能力 7.0 及以上、权重显存需求约 220 GB。这些前提同样适用于 SGLang 部署场景。SGLang 的推理框架定位SGLang是一个面向大语言模型的高性能部署推理框架提供开箱即用的推理加速与 OpenAI 兼容接口能力包括长上下文推理、流式输出、多卡并行张量并行 TP 与专家并行 EP、工具调用解析与“思考内容”解析等便于将最新模型快速落地到生产环境。仓库中的其他部署路线交叉参考self-llm 仓库为 MiniMax-M3 提供了三条并行的部署教程读者可按硬件与场景选择路线教程特点vLLMMiniMax-M3 vLLM 部署调用vllm serve启动工具调用需--enable-auto-tool-choice --tool-call-parser minimax_m2解析器名称使用下划线风格minimax_m2/minimax_m2_append_thinkSGLang本篇MiniMax-M3 SGLang 部署调用python -m sglang.launch_server启动支持--tp-size--ep-size组合显存静态占比可配TransformersMiniMax-M3 Transformers 部署调用直接AutoModelForCausalLM加载适合离线推理与二次开发三者模型 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.post1M3 作为更新的模型以“升级到最新稳定版”为准。三、模型下载SGLang 会在首次启动时自动从 Hugging Face 拉取并缓存模型严格来说无需手动下载。若希望提前下载、复用缓存或受网络限制可选用modelscope手动下载# model_download.py from modelscope import snapshot_download model_dir snapshot_download(MiniMaxAI/MiniMax-M3, cache_dir/root/autodl-tmp, revisionmaster) print(f模型下载成功保存到: {model_dir})pip install modelscope python model_download.pycache_dir按实际磁盘路径调整示例使用 AutoDL 的/root/autodl-tmp大容量盘。网络提示使用modelscope下载时无需设置 HF 镜像。若不用 modelscope、而是让 SGLang 自动从 Hugging Face 拉取网络受限时可设置镜像export HF_ENDPOINThttps://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, port8000) wait_for_server(fhttp://127.0.0.1:{port}) print(fSGLang 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.858 卡部署张量并行 专家并行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首次加载时间较长可能需要半小时以上请给加载过程留足耐心不要中途 CtrlC 后反复重启。关键启动参数解析结合教程的参数说明一节各参数含义与取值建议如下参数教程取值说明--model-pathMiniMaxAI/MiniMax-M3模型名称HF 模型 ID或本地路径用 modelscope 预下载后也可填本地目录--tp-size4 / 8张量并行大小通常设为 GPU 数量--ep-size8仅 8 卡示例开启专家并行大小MiniMax 系列为 MoE 架构多卡场景下开启专家并行--tool-call-parserminimax-m2启用 MiniMax 风格工具调用解析M3 沿用 m2 解析器--reasoning-parserminimax-append-think启用“思考内容”解析将 reasoning 与正文分离输出--mem-fraction-static0.85静态显存占比显存紧张时可适当调低反之可上调以扩大 KV 缓存--trust-remote-code必加MiniMax 模型需要信任远程代码--host/--port0.0.0.0/8000服务监听地址与端口与 vLLM 路线教程 对照可知同一套 MiniMax 解析能力在 SGLang 中写作连字符风格的minimax-m2/minimax-append-think而在 vLLM 中写作下划线风格的minimax_m2/minimax_m2_append_think且 vLLM 需额外加--enable-auto-tool-choice。两套框架参数风格不同切换部署路线时不要互相照抄参数名。采样参数方面官方推荐temperature1.0、top_p0.95、top_k20M3 单次最大输出可达 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_keyEMPTY, base_urlhttp://127.0.0.1:8000/v1, ) response client.chat.completions.create( modelMiniMaxAI/MiniMax-M3, messages[ {role: user, content: 请介绍 MiniMax-M3 相比 M2.5 有哪些提升} ], max_tokens8192, top_p0.95, temperature1.0, ) msg response.choices[0].message print(MiniMax-M3:, msg.content)python test_chat.py2. 流式输出Streaming# test_streaming.py from openai import OpenAI client OpenAI( api_keyEMPTY, base_urlhttp://127.0.0.1:8000/v1, ) stream client.chat.completions.create( modelMiniMaxAI/MiniMax-M3, messages[{role: user, content: 请用 Python 实现一个二叉搜索树包含插入、查找和删除操作。}], streamTrue, max_tokens32768, top_p0.95, temperature1.0, ) for chunk in stream: delta chunk.choices[0].delta if delta and delta.content: print(delta.content, end, flushTrue)python test_streaming.py长代码类任务如实现整棵 BST建议像示例一样把max_tokens放大到 32768 量级避免输出被截断。3. 图片输入VisionMiniMax-M3 原生支持图片输入。在 OpenAI 兼容接口中将image_url与文本一起放入content数组即可# test_vision.py from openai import OpenAI client OpenAI(api_keyEMPTY, base_urlhttp://127.0.0.1:8000/v1) response client.chat.completions.create( modelMiniMaxAI/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_tokens4096, ) print(response.choices[0].message.content)仅支持图片输入视频、音频、文档暂不支持。image_url可以是公网 URL实践中也可换成 Base64 Data URL 形式以支持本地图片。4. 工具调用Tool CallingMiniMax-M3 在 Agent 和工具调用方面继续保持强表现。SGLang 部署时通过--tool-call-parser minimax-m2启用工具调用解析后即可用标准 function calling 协议发起调用# test_tool_calling.py from openai import OpenAI import json client OpenAI(base_urlhttp://localhost:8000/v1, api_keyEMPTY) def get_weather(location: str, unit: str): return fGetting 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( modelclient.models.list().data[0].id, messages[{role: user, content: 北京今天天气怎么样请用摄氏度。}], toolstools, tool_choiceauto ) tool_call response.choices[0].message.tool_calls[0].function print(fFunction called: {tool_call.name}) print(fArguments: {tool_call.arguments}) print(fResult: {get_weather(**json.loads(tool_call.arguments))})python test_tool_calling.py示例中model参数通过client.models.list()动态获取服务实际挂载的模型 ID避免因模型命名不一致而报错。七、常见问题1. Hugging Face 网络问题如果 SGLang 自动拉取模型时遇到网络问题设置镜像后再进行拉取export HF_ENDPOINThttps://hf-mirror.com或者直接改用 modelscope 预下载见第三节绕过 HF 网络。2. 报错 “MiniMax-M3 model is not currently supported”说明当前安装的 SGLang 版本尚未支持 M3升级到最新稳定版即可pip install -U sglang3. 显存不足 / 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考