8GB 显存跑通 MiniCPM5-2B + DeepSeek Harness：一次几乎全由 AI 完成的本地部署

硬件：RTX 5050（8GB 显存）| 系统：Windows | 成本：0 元 | 全程用时：一个下午
最重要的前提：我没有动手写一行部署代码——这些活儿全部交给了 Trae（AI IDE 的编程智能体），我只负责回答它的问题、确认方案、复制粘贴报错。

一、我做了什么，为什么值得写

2026 年 9 月初，面壁智能（OpenBMB）开源了 MiniCPM5-2B：约 25 亿参数、Apache 2.0 协议、支持 128K 上下文和混合思考模式，官方直接放出了 BF16 / GGUF / MLX / GPTQ 全套格式。与此同时，DeepSeek 开源了它的 Agent 框架 DeepSeek Harness（基于 Cordis 插件体系），可以接任意大模型跑完整的 Agent 工作流。

我想做的事很简单：在一张入门级显卡上，让一个开源 2B 模型既当聊天助手，又当 Agent 框架的"大脑"，全程离线、零 API 费用。

最后达成的效果：

项目结果
模型运行MiniCPM5-2B Q4_K_M（1.56GB），100% 卸载到 GPU，显存占用约 4.7GB（含 32K 上下文 KV Cache）
API 服务Ollama，OpenAI 兼容接口 http://localhost:11434/v1
Agent 接入DeepSeek Harness Web UI（端口 3080），默认模型即本地 2B，端到端跑通工具调用循环
运维一键启停脚本 + 图形启动器（状态机 + 后台监控线程）
视觉能力同系列 MiniCPM-V 4.6 备用，需要看图时切换

而整个过程本身，比结果更有意思——这是一次"把部署工作交给 AI 编程智能体"的完整实践。

二、为什么是这套组合

为什么 MiniCPM5-2B：8GB 显存是个尴尬的档位——7B 模型量化的勉强装下但上下文开不大；1B 太弱。2B 是甜点位：Q4 量化后权重仅 1.56GB，剩下大量显存给 KV Cache，32K 上下文绰绰有余。且它是标准 Llama 架构 + ChatML 模板，Ollama / llama.cpp / vLLM 全都原生支持。

为什么 Ollama 而不是 llama.cpp 直接跑：对个人部署，Ollama 的模型管理、自动 GPU 卸载、OpenAI 兼容接口开箱即用。缺点（模板不支持工具调用、上下文默认 8K）都有明确绕法，后文讲。

为什么 DeepSeek Harness：它是我试过的开源 Agent 框架里对"自定义 OpenAI 兼容后端"最友好的之一——一个 YAML 补丁文件就能接入本地模型，Web UI 和 headless 命令行双模式。

三、开始前的准备工作

如果你要复刻，先准备好这些信息（这也是你给 Trae 的第一批输入）：

  1. 硬件：显卡型号和显存（nvidia-smi）、内存大小、C 盘剩余空间。本文场景：RTX 5050 / 8GB / 87GB。
  2. 网络：能否访问 huggingface.co。不能的话（比如国内网络），用魔搭 ModelScope 的官方镜像，模型和 GGUF 都有。
  3. 软件：Windows 10/11；Ollama（后面会装）；Node.js + npm（跑 Harness 需要）。

我的环境就卡在第 2 条：huggingface.co 完全不可达。后来所有模型文件都从 ModelScope 下载，速度反而更好。

四、部署流程（Trae 实际执行的三段）

第一段：模型上线

Trae 从 ModelScope 拉取官方 MiniCPM5-2B-GGUF 的 Q4_K_M 版本（1.56GB），然后写了这样一个 Modelfile 导入 Ollama：

FROM ./MiniCPM5-2B-Q4_K_M.gguf
TEMPLATE """{{- if or .System .Tools }}<|im_start|>system
{{ .System }}{{ end }}...（ChatML 模板，略）"""
PARAMETER stop "<|im_end|>"
PARAMETER temperature 1.0
PARAMETER top_p 0.95
PARAMETER min_p 0.0
PARAMETER num_ctx 32768

两个值得注意的参数：temperature 1.0 / top_p 0.95 / min_p 0.0 是官方推荐的采样配置；num_ctx 32768 是后来补的（原因见踩坑清单第 6 条）。

导入后验证：ollama run minicpm5-2b 对话正常，ollama ps 确认 100% GPU 卸载。Trae 还现场写了一个零依赖的 PowerShell 测试脚本，把 OpenAI 兼容接口、多轮上下文、流式输出、关闭思考模式、视觉接口全部测了一遍，8 项全过。

第二段：接入 DeepSeek Harness

Harness 通过"配置补丁"接入自定义模型。在 %USERPROFILE%\.dsh\profiles\web\cordis.patch.yml（headless 模式同理，另一份同内容文件）写入：

- id: agent-default-model
  config:
    provider: ollama
    model: minicpm5-2b          # 新会话默认用本地模型

- id: llm-pi-ai
  config:
    providers:
      ollama:
        apiKeyEnv: OLLAMA_API_KEY      # 启动前设任意值即可
        api: openai-completions
        baseURL: http://localhost:11434/v1
        compat:
          supportsDeveloperRole: false  # Ollama 不支持 developer 角色
          maxTokensField: max_tokens    # Ollama 不识别 max_completion_tokens
        models:
          - id: minicpm5-2b
            contextWindow: 32768
            maxTokens: 8192
          - id: minicpm-v4.6            # 视觉模型，可接收图片
            contextWindow: 8192
            maxTokens: 4096
            input: [text, image]

compat 下那两行是关键——很多"接不上 OpenAI 兼容接口"的问题都出在这类协议细节上。

之后用 Harness 的 headless 模式跑了一条真实任务验证：“1+1等于几”——它完整走了一遍 Agent 循环（取默认模型 → 发请求 → 收回答），模型回复正确，链路闭环。

第三段：运维脚本和图形启动器

每天手动敲命令太烦，我让 Trae 做了两层封装：

命令行版 ai-stack.ps1：start / stop / status / restart 四个动作。start 会按序拉起 Ollama → 发一条最小请求预热模型进显存 → 启动 Harness Web UI，并从日志里自动提取带 token 的访问地址打印出来。

图形启动器 ai-launcher.ps1：Windows 自带 WinForms 写的窗口，零依赖，双击 .cmd 就能用。三盏状态灯（Ollama / 模型 / Harness）、四个按钮（启动全部、关闭全部、打开 Web 界面、查看日志）、实时滚动日志。并且明确做了状态机：

状态启动关闭打开Web
未启动 / 关闭完成✅❌❌
启动中❌✅（点击=中断）❌
运行中❌✅✅
关闭中❌❌❌

这两个脚本加起来五六百行，都是 Trae 现场生成、现场测试、现场修 bug。我没有看过完整代码，只审过它给我的行为描述。

五、踩坑清单（最值钱的部分）

整个过程撞了 9 个坑，每一个都值得单独记一笔：

  1. 旧终端不认识 ollama 命令。安装器写的是用户 PATH，已开着的终端不会自动刷新。刷新变量或重开终端即可。
  2. http://localhost:11434/v1 在浏览器里打开是 404。这是正常的——根路径本来没有页面，Agent 会自动拼接 /chat/completions 等端点。想验证服务，访问 /v1/models。
  3. 发截图就 500 报错（image input is not supported）。MiniCPM5-2B 是纯文本模型。解法：Agent 主模型用它，视觉模型单独配 MiniCPM-V 4.6（官方同系列，Ollama 直接可拉）。
  4. pnpm 报 no @pnpm/exe.win32-x64 native binary was found。npm 新版的安装脚本保护拦截了 pnpm 的二进制下载。全局修复：npm i -g @pnpm/exe.win32-x64 --allow-scripts；项目内（package.json 锁了 11.7.0）用 npx -y pnpm@11.7.0 绕过版本托管。
  5. Harness 报 MISSING_CREDENTIAL: deepseek-official。默认模型是 DeepSeek 官方路由。用配置补丁把 agent-default-model 覆盖成本地 ollama 模型；启动前设 $env:OLLAMA_API_KEY="ollama" 满足凭据检查（值任意）。
  6. CONTEXT_WINDOW_EXCEEDED: 8520 tokens > 8192。Harness 的系统提示+工具目录本身就吃 8.5K tokens，Ollama 模型默认 8K 上下文根本不够。重建模型把 num_ctx 提到 32768（显存代价：约 3.1GB → 4.7GB），配置里 contextWindow 同步改大。
  7. Ollama 关不掉，杀掉又复活。ollama.exe serve 是托盘程序 ollama app.exe 的子进程，先杀 serve 托盘会立刻重新拉起。必须先杀托盘进程树（taskkill /T /F），再清残余。
  8. 图形界面卡死。第一版启动器把端口探测、HTTP 查询、日志扫描全跑在 UI 线程上，服务半死状态时一次查询挂几秒，窗口就"未响应"。重构：所有探测移到后台线程，主线程只读同步结果——UI 物理上不可能再卡。
  9. PowerShell 5.1 的中文和 JSON 转义。给 curl 传 JSON 双引号会被转义搞坏（假成功）；含中文的 .ps1 文件必须存成 UTF-8 with BOM。这两个坑 AI 也会踩，但提醒一句它就能自己修。

六、"细节交给 Trae"工作法

如果这篇博客只让你记住一件事，就是这段。

整个过程我的实际角色是：决策者 + 测试员 + 报错搬运工。Trae 的角色是：架构建议、写配置、写代码、跑测试、修 bug、写文档。要让 AI 编程智能体把活干好，我总结四条经验：

1. 先把"环境事实"一次性交代清楚。
显卡、显存、内存、磁盘、网络可达性，第一句话就说。我开局就说了"5050 / 8GB / C 盘 87GB / 无法访问 huggingface"，所以 Trae 从第一步就走了 ModelScope 镜像，没有浪费任何一次重试。

2. 让它写测试，而不是你人肉测。
“写个脚本验证 API 的多轮对话、流式输出和关思考模式”——这类测试代码让 AI 写比自己快得多，而且测试脚本会留下来，以后每次改动都能重跑。

3. 报错原样贴回去，不要自己翻译。
CONTEXT_WINDOW_EXCEEDED、no @pnpm/exe.win32-x64 这种错，我看到的第一反应是"完了"，但原样丢给 Trae，它定位根因一般不超过两轮。你自己的"直觉修复"反而容易带偏。

4. 每完成一个阶段，顺手让它沉淀文档和脚本。
部署完当天我让它写了使用说明文档；第二天的启停脚本、第三天的图形启动器，都是在"能不能更省事"的抱怨中让它现做的。这些产物最后成了这篇博客的全部素材。

一个诚实的说明：Trae 不是永远一次做对。图形启动器改了三版（按钮没绑事件、Start-Job 在 GUI 里状态不回传、UI 线程阻塞），每次都是我实际点了一下发现问题、贴报错、它修。AI 负责从 0 到 90 分，人负责最后 10 分的验收——这个分工在部署类任务上非常划算。

七、你的复刻清单

想自己跑一遍？两条路。

路线 A：把这篇博客直接丢给 Trae（推荐）
新建一个会话，粘贴本文，附上你的硬件信息和网络状况（第三节那三条），然后说"按这篇博客帮我在本机完成部署，细节你来处理"。坑都替你踩过了，理论上一次通过率很高。

路线 B：手动执行，核心步骤浓缩版：

# 1. 安装 Ollama（官网或 winget install Ollama.Ollama）
# 2. 从魔搭下载 openbmb/MiniCPM5-2B-GGUF 的 Q4_K_M 文件
# 3. 按第四节写 Modelfile，导入并验证
ollama create minicpm5-2b -f Modelfile
ollama run minicpm5-2b "你好"

# 4. 克隆并构建 DeepSeek Harness
git clone https://github.com/deepseek-ai/deepseek-harness
cd deepseek-harness
npx -y pnpm@11.7.0 install
npx -y pnpm@11.7.0 run build

# 5. 按第四节写 cordis.patch.yml（web 和 headless 两份）
# 6. 启动并验证
$env:OLLAMA_API_KEY = "ollama"
npx -y pnpm@11.7.0 dsh web
# 浏览器打开控制台输出的带 token 地址，模型选择器里确认 minicpm5-2b

八、结语

这套东西现在的日常状态是：开机后 Ollama 托盘自启，我双击启动器，30 秒后 Web 界面就绪，一个跑在本地显卡上的 Agent 等着派活。不花钱、不上传任何数据、断网可用。

而对我来说更有价值的收获是方法本身：部署、测试、写文档、做工具——这些"杂活"正在变成一种可以说清楚需求就能获得的东西。 人的精力应该花在"要不要 32K 上下文""状态机按钮怎么设计"这类决策上，而不是去记 pnpm 的版本托管怎么绕。

把细节交给 AI，把判断留给自己。这篇博客本身，也是按这个分工写完的。

环境信息：Windows 11，RTX 5050 8GB，Ollama 0.34.3，DeepSeek Harness（Cordis），MiniCPM5-2B Q4_K_M @ num_ctx 32768。文中所有配置文件与脚本均由 Trae 生成并实测通过。
请添加图片描述
请添加图片描述
请添加图片描述

# typescript
Logo
EazyDevelop社区

一站式 AI 云服务平台

更多推荐

cover

2026 跨端协作远控深度横评——功能齐全度实测对比，附评分表与选型建议（开发者实测）

avatar EazyDevelop社区
cover

[Grok Bot 仓颉实践] 让 AI 助手替你干活之前，先想清楚谁来拍板——我用 Grok Bot 做游戏的做法

avatar EazyDevelop社区
cover

Excel按照某一列分类输出各个表格：不会VBA、不装Python，三步拆完

avatar EazyDevelop社区