shield_lock
金大哥
← 返回 Skill 列表
extension
分类: 效率与办公无需 API Key

local-minicpm-pet-openvino

一键部署 MiniCPM 桌宠体验环境，后端采用 OpenVINO 推理引擎（Deploy MiniCPM Desk Pet with OpenVINO backend）. 使用本 Skill 可部署一个完整的桌宠体验环境，在 Intel AIPC 上本地运行，无需云端服务。 部署完成后，用户直接通过桌宠 UI 界面进行对话交互。 Use this skill when the user wants to deploy/set up/run the MiniCPM desk pet with OpenVINO backend, or build a local AI pet experience environment on Intel hardware. Trigger on: 部署桌宠/体验环境/搭建环境/本地推理/OpenVINO后端/桌宠环境/deploy pet/setup environment/run desk pet/ 英特尔/intel/AIPC/本地/离线/offline/MiniCPM/OpenVINO/桌宠. This is a DEPLOYMENT skill — it sets up the environment and launches the pet. After deployment, the user interacts with the pet directly through its UI (not via this script).

person作者: snake7gunhubgithub
open_in_new仓库download下载资源包

Local-MiniCPM-Pet-OpenVINO Skill Guide

使用本 Skill 可一键部署一个完整的 MiniCPM 桌宠体验环境。 后端采用 OpenVINO 推理引擎，前端从源码 npm start 启动。 部署完成后，用户直接与桌宠对话，无需再次调用本脚本。

!! CRITICAL: 环境依赖 !!

以下依赖缺一不可，必须在执行前验证：

| 依赖 | 最低版本 | 验证命令 | 用途 | | --- | --- | --- | --- | | Windows 10/11 | - | - | 操作系统 | | Intel AIPC 硬件 | LNL/ARL/PTL/WCL | bin\platform.exe --is-aipc | 本地推理加速 | | Python | 3.11 | python --version | OpenVINO 推理服务 | | Node.js | 18+ | node --version | 桌宠前端 | | npm | - | npm --version | 桌宠依赖安装 | | git | - | git --version | 获取桌宠源码 |

!! CRITICAL: 中国大陆网络环境 !!

所有网络操作必须使用国内源，否则极慢或不可用：

| 操作 | 国内源 | 说明 | | --- | --- | --- | | git clone | GitCode 镜像 | gitcode.com/OpenBMB/MiniCPM-Desk-Pet.git | | pip 安装 | 清华镜像 | mirrors.tuna.tsinghua.edu.cn | | npm 安装 | 淘宝镜像 | registry.npmmirror.com | | Electron 下载 | npmmirror | npmmirror.com/mirrors/electron/ | | 模型下载 | ModelScope | 默认国内直连 | | HuggingFace | hf-mirror | hf-mirror.com |

--china 参数已内置上述所有配置，无需手动设置。

!! CRITICAL: 沙箱外运行要求 !!

以下目录必须持久化（沙箱外），否则每次重试将重新下载 ~2.4GB：

| 目录 | 大小 | 内容 | | --- | --- | --- | | %USERPROFILE%\.openvino\venv\ | ~500MB | Python 虚拟环境 | | %USERPROFILE%\.openvino\models\ | ~1.5GB | AI 模型文件 | | %LOCALAPPDATA%\electron\Cache\ | ~180MB | Electron 二进制缓存 | | 桌宠源码 node_modules\ | ~200MB | npm 依赖 |

严格执行流程（必须按顺序，不可跳过）

Step 0: 判断用户网络环境（Agent 必须在调用前完成）

调用 scripts\run.ps1 之前，Agent 必须先判断用户的网络环境。

判断方法（任选其一）：

  • 用户明确说在中国大陆 / 国内
  • 用户系统语言为中文（zh-CN）
  • 用户时区为 UTC+8 且非新加坡/港澳台
  • 网络环境无法直接访问 GitHub / PyPI / npmjs.org

判断为中国大陆环境 → 加 --china；否则不加。

Step 1–8: 由 run.ps1 自动执行

Agent 必须使用以下方式调用脚本（禁止直接双击 ps1 文件）：

# 中国大陆环境（一条命令完成全部部署）
powershell -ExecutionPolicy Bypass -File "scripts\run.ps1" --china

# 海外 / 可直连环境
powershell -ExecutionPolicy Bypass -File "scripts\run.ps1"

# 指定推理设备（可选：NPU、GPU、CPU，默认自动检测）
powershell -ExecutionPolicy Bypass -File "scripts\run.ps1" --china --device NPU

或使用 run.cmd 包装入口（用户可直接双击）：

scripts\run.cmd --china

脚本自动完成以下步骤：

  1. 硬件检测（Intel AIPC）
  2. 配置镜像源（--china 时锁定国内源）
  3. 创建 Python 虚拟环境 + 安装 OpenVINO 依赖
  4. 获取桌宠源码（git clone）
  5. 安装桌宠 npm 依赖
  6. 预写 Onboarding Sentinel（跳过引导界面）
  7. 启动 OpenVINO 推理服务（HTTP，端口 18765）
  8. 启动桌宠前端（npm start）

部署完成后，用户直接通过桌宠界面进行对话。

Step 9: 验证部署结果（Agent 必须执行）

部署脚本执行完毕后，Agent 必须验证部署是否成功，不能直接报告"已完成"。

验证方法：

scripts\run.ps1 --status

判断标准（解析脚本输出）：

  • 输出包含 推理服务: 运行中 且 桌宠前端: 运行中 → 部署成功，向用户报告
  • 输出包含 推理服务: 未运行 → 部署失败，执行排障流程（见下方排障指南）
  • 输出包含 桌宠前端: 未运行 → 前端未启动，再次执行 scripts\run.ps1 重试

脚本在部署结束时也会输出结构化摘要，格式如下：

[DEPLOY_RESULT]
server_status=ok|error|timeout
server_port=18765
pet_frontend=running|not_running
model_status=loaded|downloading|error
[/DEPLOY_RESULT]

Agent 应解析此摘要：

  • server_status=ok + pet_frontend=running → 部署成功
  • server_status=error → 执行 scripts\run.ps1 --debug 获取诊断信息
  • model_status=downloading → 模型仍在下载中，提示用户等待

如果 --debug 也无法定位问题，将 debug 输出展示给用户协助排查。

部署后的架构

┌────────────────┐   HTTP :18765   ┌────────────────────┐   OpenVINO   ┌──────────┐
│  桌宠前端       │ ──────────────→ │  server.py (FastAPI)│ ──────────→ │ MiniCPM5 │
│  (Electron)    │ ←────────────── │  (常驻后台)          │ ←────────── │ INT8 模型 │
└────────────────┘                 └────────────────────┘             └──────────┘
  • server.py 提供 /v1/chat/completions（OpenAI 兼容）和 /api/health
  • 桌宠前端通过 HTTP 与推理服务通信
  • 模型首次运行时从 ModelScope 自动下载 (~1.5GB)

参数说明

| 参数 | 说明 | | --- | --- | | --china | 锁定中国大陆镜像源，不做网络探测 | | --device NPU\|GPU\|CPU | 指定推理设备（默认自动检测，优先 GPU） | | --status | 查看当前运行状态（推理服务 + 桌宠前端） | | --stop | 停止所有服务（推理服务 + 桌宠前端，含强杀残留进程） | | --debug | 输出详细诊断信息（Python 环境、模型文件、端口、日志） |

注意事项：

  • Agent 必须使用 powershell -ExecutionPolicy Bypass -File 方式调用（Windows 默认不允许直接执行 .ps1）
  • git clone 时自动设置 GIT_LFS_SKIP_SMUDGE=1 跳过 LFS 大文件（模型由 server.py 单独从 ModelScope 下载）
  • 处理器检测：非 Intel CPU 会直接阻断，非 Core Ultra 系列会警告但继续

生命周期示例：

# 部署并启动
scripts\run.ps1 --china

# 查看状态
scripts\run.ps1 --status

# 不想跑了，停止所有服务
scripts\run.ps1 --stop

# 再次启动（幂等，跳过已完成的步骤）
scripts\run.ps1 --china

Exit Codes

| Exit Code | 含义 | | --- | --- | | 0 | 部署成功，桌宠已启动 | | 1 | 一般错误（硬件不支持、环境缺失、网络失败） |

排障指南（Agent 遇到错误时参考）

推理服务未运行（server_status=error 或 timeout）

  1. 执行 scripts\run.ps1 --debug 查看诊断信息
  2. 检查「Python 环境」部分：确认 openvino-genai 已安装
  3. 检查「端口 18765 占用」：如果被其他进程占用，先 kill 再重试
  4. 检查「最近日志」：查找 Python traceback 或 ImportError
  5. 常见原因：
    • Python 依赖安装不完整 → 删除 venv 重新执行部署
    • 端口被占用 → netstat -ano | findstr :18765 找到 PID 并 kill
    • OpenVINO 不支持当前硬件 → 确认是 Intel AIPC（LNL/ARL/PTL/WCL）

桌宠前端未运行（pet_frontend=not_running）

  1. 确认 Node.js 18+ 和 npm 已安装：node --version
  2. 确认 MINICPM_BACKEND=openvino 环境变量已设置
  3. 检查 npm install 是否成功完成（是否有 node_modules 目录）
  4. 再次执行 scripts\run.ps1（幂等，会自动重试启动前端）
  5. 如果前端卡在 onboarding 引导界面：说明 MINICPM_BACKEND 未正确传递，检查环境变量

模型下载超时（model_status=downloading）

  1. 这不是错误，模型约 1.5GB，首次下载需要时间
  2. 确认已使用 --china 参数（国内 ModelScope 直连更快）
  3. 用 scripts\run.ps1 --status 查看推理服务是否仍在下载
  4. 下载完成后推理服务会自动加载模型，无需额外操作

通用排障步骤

# 1. 查看完整诊断信息
scripts\run.ps1 --debug

# 2. 停止所有服务
scripts\run.ps1 --stop

# 3. 重新部署（幂等，已完成的步骤会跳过）
scripts\run.ps1 --china

# 4. 验证
scripts\run.ps1 --status

日志位置：%USERPROFILE%\.openvino\log\

本 Skill 不做的事

  • 不接受对话 prompt 参数（对话通过桌宠 UI 进行）
  • 不调用任何云端服务
  • 不支持非 Intel 平台
  • 不在沙箱内执行大文件下载
  • 不使用预构建 .exe 安装包（从源码运行）