常见问题
这里汇总 OpenBMB 模型选型、部署、显存与社区使用中的高频问题。 遇到具体报错时，建议同时准备模型版本、运行环境、硬件配置、启动命令和完整日志，便于快速定位。
模型与资料
我应该从哪个模型开始？
先按任务模态和设备资源选择：
- 文本生成、代码与工具调用：从 MiniCPM 文本系列开始。
- 图像、视频理解：选择 MiniCPM-V 多模态系列。
- 视觉、语音、文本实时交互：查看 MiniCPM-o 全模态系列。
- 语音生成与音色克隆：查看 VoxCPM 语音系列。
不同版本的参数量、上下文长度、能力特点及部署入口，可在 全系列产品图鉴 中对比。
在哪里查看部署和微调教程？
进入 文档中心，按 MiniCPM 文本、MiniCPM-V、MiniCPM-o、VoxCPM 或 PilotDeck 分类查找。全系列产品图鉴中也提供了对应的部署与微调入口。
想先体验一个完整应用，有推荐吗？
可以从 MiniCPM Desk Pet 开始。该实践包含系统要求、下载安装、首次启动、模型管理与已知限制，适合快速体验本地模型应用。
部署与显存
如何判断自己的设备能否运行某个模型？
重点查看模型参数量、精度或量化方式、上下文长度，以及推理框架的额外开销。可先查阅 显存与性能 页面中的显存估算公式、模型速查表和设备适配建议。
简化估算：总推理显存 ≈ 模 型权重显存 + KV Cache + 运行时开销。长上下文、多并发和多模态输入都会增加实际占用，建议预留余量。
显存不足或出现 OOM，应该先做什么？
- 缩短上下文长度、降低批大小或并发数。
- 改用 INT8、INT4、AWQ、GPTQ 或 GGUF 等量化版本。
- 选择参数量更小的模型，或启用 CPU / GPU 混合卸载。
- 关闭其他占用显存的进程，并确认实际可用显存。
- 仍无法解决时，记录峰值占用、启动参数和完整报错后再求助。
为什么模型支持很长的上下文，但我的设备跑不起来？
“支持的最大上下文”不等于所有设备都能直接使用。上下文越长，KV Cache 通常越大，同时还会增加计算耗时。实际可用长度取决于模型架构、KV 头数、精度、并发数和设备内存。建议从较短上下文开始，逐步增加并观察显存与速度。
量化会带来什么影响？
量化通常可以显著降低显存和磁盘占用，并提高部分设备上的推理可用性；代价可能是生成质量、速度或框架兼容性的变化。优先使用目标模型官方提供或社区广泛验证的量化版本，并用自己的真实任务做效果评测。
排障与社区
下载模型很慢或中途失败怎么办？
- 确认磁盘空间、网络连接和下载目录权限。
- 检查仓库页面是否提供镜像、断点续传或手动下载说明。
- 手动下载时，确认文件完整且目录结构符合教程要求。
- 不要只提供“下载失败”，同时附上下载方式、目标仓库、文件名和完整错误信息。
安装或启动失败时，提问需要带哪些信息？
| 信息 | 示例内容 |
|---|---|
| 模型与版本 | 模型名称、权重或量化版本、代码提交或发布版本 |
| 运行环境 | 操作系统、Python、CUDA、PyTorch 及推理框架版本 |
| 硬件配置 | CPU、GPU 型号、显存与系统内存 |
| 复现步骤 | 安装方式、启动命令、输入样例和最小复现代码 |
| 错误信息 | 从异常开始到结束的完整日志，不只截取最后一行 |
在哪里查看社区案例或寻求交流？
可在 开发者精选 查看真实项目与技术文章；知识库首页的“加入社区”区域提供 MiniCPM、MiniCPM-V、VoxCPM 和 PilotDeck 对应交流群入口。
如何贡献案例、教程或问题修复？
欢迎分享完整项目、部署脚本、复现记录、benchmark、显存优化、失败案例或业务落地经验。投稿前建议写清适用模型、环境版本、复现步骤、结果与限制，方便社区验证和复用。
没有找到答案？
如果上面的常见问题没有覆盖你的情况，欢迎提交一个开放问题。我们会定期整理并作答，具有共性的问题也可能补充到本知识库中。