想在自己机器上跑一个专门干活的编程 agent 模型，你大概率卡在同一个两难里：云端 API 好用但代码和数据得出域，本地小模型跑得动但干不了真活。JetBrains 在 2026 年 10 月 8 日上架的 Mellum2.1-12B-A2.5B-Thinking 就是冲着这个缝来的——12B MoE 总参数、2.5B 激活，消费级 24GB 显存卡能跑，但它是 thinking 模型，官方只给了 vLLM 路线，网上流传的「1.6 倍提速」「Ollama 一键拉取」教程现在一个都复现不了。
这篇 SOP 给你一条今天就能走通的部署路径：vLLM serve 起模型、配好 reasoning parser 和工具调用模板、验证 131K 上下文，然后把三个大坑（MTP head 未发布、GGUF 未放出、thinking 输出解析）提前拆掉。所有命令按官方模型卡口径整理，性能结论以你自己仓库实测为准。
适用前提先自查，缺一条就直接换方案：
- NVIDIA 显卡，显存 24GB 及以上（4090/3090 这一档），估算口径，官方未给硬件数字；
- Linux 或 WSL2，CUDA 驱动正常，能装新版 vLLM；
- 接受纯自托管——Mellum2.1 没有官方托管 API；
- 用途是代码与 agent 任务，不要拿它当通用聊天模型。
如果显存只有 8GB 到 12GB，这篇可以先收藏，直接看 Qwen3.5-9B 本地部署 SOP，那条路线有现成量化生态。
一、先搞清楚你要跑的是什么
Mellum2.1 是 JetBrains 对 Mellum2 的训练配方升级版，架构没动：12B MoE 总参数、2.5B 激活、131,072 上下文、Apache 2.0 许可。变化在训练方法——RL 从收尾环节变成训练主体，跑了数千个环境、数百万次沙盒 run，新增数学、竞赛、科学、工具使用和软件工程任务。
JetBrains 自测口径（Pi harness v0.73.1、thinking mode）：SWE-bench Verified 47.0，对比 Qwen3.5-9B 的 50.0；LiveCodeBench v6 82.0 反超 Qwen 的 75.4；BFCL v4 62.3 也高于 Qwen 的 58.5。判读一句话：短任务、竞赛题、工具调用 Mellum 有优势，真实仓库长任务 Qwen 分数更高。别被「新模型发布」冲昏头，它不是全面超越，卖点是固定 GPU 预算下的高吞吐 agent 密度，加上数据不出域。
仓库在这里：huggingface.co/JetBrains/Mellum2.1-12B-A2.5B-Thinking。截至本文实测该仓库 ungated、Apache 2.0 许可，直接可拉。明文再写一遍地址，方便你复制：huggingface.co/JetBrains/Mellum2.1-12B-A2.5B-Thinking。模型背景与自测表解读可以看 Mellum2.1 开源解析篇。
二、vLLM 主路线：四步跑通
步骤 1：装环境
# 建议独立虚拟环境
pip install -U vllm
# 确认版本与 GPU 可见
vllm --version
nvidia-smi预期结果：vllm 版本号正常输出，nvidia-smi 能看到你的卡和驱动版本。vLLM 对 Mellum2.1 即日支持，用新版即可，不需要打补丁。
步骤 2：起服务
vllm serve JetBrains/Mellum2.1-12B-A2.5B-Thinking \
--reasoning-parser qwen3 \
--max-model-len 131072预期结果：权重下载完成后服务起来，终端出现监听地址（默认 8000 端口）。首次运行会拉约 24GB 级的 BF16 权重（估算口径），磁盘留足空间。--reasoning-parser qwen3 是官方模型卡口径——它是 thinking 模型，不配这个 parser，思考内容会直接串进回答结果里，agent 调用直接报废。如果显存吃紧，先把 --max-model-len 降到 32768 跑通，再逐步往上调。
步骤 3：验证基础推理
curl http://localhost:8000/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "JetBrains/Mellum2.1-12B-A2.5B-Thinking",
"messages": [{"role": "user", "content": "用 Python 写一个带重试的 HTTP 请求函数"}]
}'预期结果：返回的 JSON 里，reasoning_content 字段放思考过程，content 字段放干净答案。如果 content 里出现 <think> 标签或大段推理文字，说明 parser 没生效，回到步骤 2 检查参数。
步骤 4：验证工具调用与长上下文
工具调用方面，模型卡给了可选的 Hermes 工具调用模板。在 vLLM 启动参数里加 --tool-call-parser hermes，然后用带 tools 字段的请求测一轮：
curl http://localhost:8000/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "JetBrains/Mellum2.1-12B-A2.5B-Thinking",
"messages": [{"role": "user", "content": "帮我看下 /var/log 目录大小"}],
"tools": [{
"type": "function",
"function": {
"name": "run_shell",
"description": "执行 shell 命令",
"parameters": {
"type": "object",
"properties": {"cmd": {"type": "string"}},
"required": ["cmd"]
}
}
}]
}'预期结果：返回 tool_calls 结构化字段而不是纯文本。agent 框架（如自建的 runner）靠这个字段派活，这一步不过关后面全白搭。
长上下文验证：塞一份长代码文件进去，让它复述其中某个函数签名。预期结果：131,072 上下文配置下，长输入不报错、召回正常。注意 KV cache 显存占用随上下文线性涨，131K 满配置比短上下文多吃好几个 GB，这是第三步显存账的伏笔。
步骤 5：接入 agent 工作流前的冒烟测试
四步跑通不代表能直接上生产，接 agent 框架前再补一轮冒烟测试：用你真实业务里的一条任务（比如「修复这个测试文件里失败的用例」）走完整循环——模型思考、发起 tool_calls、你回传工具结果、模型继续。预期结果：多轮循环中 parser 稳定剥离思考内容，tool_calls 格式全程合法，循环正常收敛而不是原地打转。这一步暴露的问题，九成出在坑三的 thinking 解析上。
另外注意并发语义：vLLM 默认允许多路并发共享模型实例，agent 场景下单请求经常吃满长上下文，并发一多 KV cache 直接把显存打爆。起步阶段建议 --max-num-seqs 压到 4 以内，跑稳了再按显存余量放。
三、三个大坑，提前拆
坑一：MTP head 未随权重发布，1.6 倍提速现在买不到。 官方宣传里「单请求 1.6x 提速」靠 MTP 投机解码，但 MTP head 标注 coming soon，没和主权重一起放出。网上教程现在教你加投机解码参数的，都是复现不了的路数。等 head 发布后再加，今天先把主模型跑稳。
坑二：GGUF 未放出，Ollama 和 LM Studio 用户别等整合包。 llama.cpp、Ollama、LM Studio 的支持都还是 coming soon。「宣布支持」和「今天能拉」是两回事，任何声称提供 Mellum2.1 GGUF 整合包的第三方渠道都要警惕——模型刚发布两天，社区整合包既不可信也不可控。想用 Ollama 跑别的模型，参考 Ollama 本地部署 SOP，推理工具怎么选那边也有对照。
坑三：thinking 模型的输出解析。 这是 agent 接入最高频的翻车点。Mellum2.1 是 thinking 模型，原始输出里思考过程和答案混在一起，不配 reasoning parser 的下游代码会把「思考串」当成最终回答喂给 agent 循环，轻则回答啰嗦，重则工具调用格式错乱、死循环。vLLM 里 --reasoning-parser qwen3（官方模型卡口径）就是解这个的，务必带上。
为什么只有 vLLM 一条路线？因为 JetBrains 这次只随权重发布了 vLLM 的适配口径，reasoning parser 和工具调用模板都是按 vLLM 参数体系给的。社区生态（llama.cpp、Ollama）要等 GGUF 权重放出后各自适配，模板和 parser 也得从头验证。换句话说，现在所有非 vLLM 路线都在「等上游」，你能做的只有盯官方仓库更新，别在社区找野路子。
顺带一句显存红线：12GB 卡跑不动全量 BF16 权重，约 24GB 级是估算口径，官方没给硬件数字。12GB 及以下卡的用户，唯一现实路径是等 GGUF 量化版，或者换 Qwen3.5-9B 的量化生态。
四、硬件与显存账
按估算口径给你一张起步参考表（官方未给硬件数字，以下为 BF16 权重约 24GB 推算，非实测，以你自己的卡为准）：
| 配置 | 能不能跑 | 建议 |
|---|---|---|
| 24GB 单卡（4090/3090） | 起步可行 | max-model-len 从 32K 起步，逐步上探 |
| 48GB（双卡或 A6000 级） | 舒服 | 131K 满上下文 + 并发有了基础 |
| 80GB（H100/A100） | 富余 | 可开并发与更长 KV 余量 |
| 12GB 及以下 | 跑不动全量 | 候 GGUF 量化，或换 9B 级模型 |
账要算细：BF16 权重约 24GB 只是地板，KV cache 是浮动支出，随上下文长度和并发数涨。131K 满上下文的单请求 KV 占用对 24GB 卡不轻松，所以建议 24GB 卡用户把 --max-model-len 从 32K 起步，按 nvidia-smi 的显存余量逐级上调。给 131K 留 KV 余量这件事，48GB 以上才从容。
预算角度再说一句：Mellum2.1 的定位是「固定 GPU 预算下的高吞吐 agent 密度」，意思是同一张卡、同样电费，它靠 2.5B 激活的稀疏架构跑出更高的请求吞吐。但这个优势要在并发场景才兑现得出来——单请求串行跑一个任务，激活参数省下的算力未必转化为可感知的速度。所以如果你的场景是偶尔手工问两句，Qwen3.5-9B 的量化版可能更省心；如果是常驻的 agent 农场、批量处理工单，Mellum 的账才算得过来。
想了解这套模型在四强横评里的部署门槛对比，看 本地部署编程模型横评，那边比的是部署门槛五轴，这边管跑通。
五、常见报错排查
部署过程中高频出现的报错，先对号入座再动手：
| 现象 | 原因 | 处理 |
|---|---|---|
| 启动即 OOM | 显存不够装权重加 KV | 降 --max-model-len；确认没有其他进程占卡 |
| 回答里混着大段思考文字 | reasoning parser 没生效 | 核对 --reasoning-parser qwen3 参数拼写，重启服务 |
| tool_calls 字段缺失 | 工具调用模板没配 | 加 --tool-call-parser hermes，按模型卡口径核对 |
| 长输入直接报错 | max-model-len 设小了 | 上调长度，同时盯显存余量 |
| 下载中断 | 网络不稳 | 删掉残缺缓存目录重新拉，或配镜像源 |
排查的通用顺序：先看服务启动日志里 parser 和模板参数有没有被 vLLM 接受（不认识的参数会静默忽略或警告，别只盯最后一行），再用最小 curl 请求复现问题，最后才动模型侧。改任何启动参数都要重启服务才生效，热改配置不存在的。
六、与 Qwen3.5-9B 双跑对账法
JetBrains 的自测表只代表它自己的 harness 口径，分数多以图表呈现，没有可核对的原始数字。你要做生产决策，正确姿势是自己对账：
- 固定同一个 harness（评测框架）和同一批任务集，分别打 Mellum2.1 和 Qwen3.5-9B 的本地端点；
- 两个维度各记一列：tokens/s（固定输入输出的吞吐）和工单解决数（真实任务通过率）；
- tokens/s 只在同精度档位比才有意义——Mellum 是 BF16 全量，Qwen 跑量化的话先标注清楚；
- 工单解决数比 benchmarks 更接近你的真实收益。
结论判读参考官方口径的定性方向：短任务、竞赛题、工具调用场景 Mellum 可能占优，真实仓库长任务 Qwen3.5-9B 分数更高——但以你自己的任务分布实测为准。另外官方称 H200 重负载吞吐「接近 Qwen3.5-9B 两倍」，这是官方口径且具体值只在图表里，别直接搬到你 24GB 卡上做预算。API 与托管路线的取舍，横评篇里也有对照。
对账这件事别嫌麻烦。JetBrains 的图表分数和 Qwen 官方口径的分数出自不同 harness、不同任务集，直接摆在一起比大小是外行做法。你自己搭建的双跑环境里，任务集选自真实工单、温度参数固定、每题跑三遍取多数通过，得出的两张表才有决策价值。对账周期建议一周到两周，跑完把结论写进你的选型文档：哪个模型接哪类任务、各自的经济性临界点在哪。这套方法不只服务 Mellum2.1，以后每次本地模型换代都能复用。
FAQ
Q1: 16GB 显存的卡能跑 Mellum2.1 吗？ 全量 BF16 权重约 24GB 级（估算口径），16GB 装不下。现实路径只有等 GGUF 量化版发布，或者换 Qwen3.5-9B 这类有现成量化生态的模型。
Q2: 一定要加 --reasoning-parser qwen3 吗？ 强烈建议。这是官方模型卡口径。不加的话思考内容会串进回答，接 agent 框架时格式错乱、循环失控都是它引起的。
Q3: 为什么我跑不出官方说的 1.6 倍提速？ 那个数字靠 MTP 投机解码，而 MTP head 未随权重发布（coming soon），现在任何人都复现不了。先把主模型跑稳，等 head 放出再加。
Q4: Ollama 什么时候能拉这个模型？ GGUF 支持官方标注 coming soon，没有日期。「宣布支持」不等于今天可用，别信第三方整合包，以 huggingface.co/JetBrains/Mellum2.1-12B-A2.5B-Thinking 仓库页的更新为准。
Q5: 131K 上下文 24GB 卡能开满吗？ 权重大约占掉 24GB，131K 满上下文的 KV cache 再往上加，24GB 卡大概率开不满。建议从 32K 起步逐级上探，48GB 以上显存才从容开满。
Mellum2.1 的部署路线今天只有 vLLM 一条，坑也明明白白三个：MTP head 没发布、GGUF 没放出、thinking 解析必须配 parser。24GB 卡起步可行（估算口径），131K 上下文要给 KV 留余量，性能别信图表，同 harness 双跑对账以你自己的仓库实测为准。
三个后续时间点值得设个日历提醒：MTP head 放出（届时可以重测单请求提速）、GGUF 发布（小显存卡和 Ollama 用户入场的信号）、社区 harness 复测结果出现（JetBrains 自测表之外的第二个数据源）。这三个节点任何一个落地，本文的部署参数和结论都可能要更新一次，以官方仓库为准。
如果你已经跑起来了，欢迎在评论区报一下你的卡型和 tokens/s，帮后来人填坑；跑不通的把报错贴出来，一起看。