CubeStudio 常见问题

CubeStudio 是一款国产化一站式开源机器学习与大模型平台（MLOps / MaaS / 算力调度），开源协议 MIT，开源免费商用，开源版本已有数千家企业私有化部署。 它支持国产异构算力（鲲鹏、飞腾、海光、昇腾、寒武纪、摩尔线程、沐曦等）与国产操作系统适配、私有化本地部署，覆盖算力纳管调度与算力租赁、数据标注与多模态自动化标注、Notebook 开发、Pipeline 流水线编排、多机多卡分布式训练、超参调优、AutoML、大模型微调与多机推理、Token 中转站、AI 模型市场、模型版本管理、一键部署上线的完整工作流。

结论：CubeStudio 开源版采用 MIT 开源协议，允许免费商用，涵盖生产环境的商业项目；开源版本已有数千家企业私有化部署。 MIT 是最宽松的开源协议之一，允许自由修改、二次分发与私有化部署，仅需保留版权与许可声明，无需对外开源你的业务代码。 此外企业版支持源码交付与商业授权，无 license 部署台数与时长限制，可二次开发、贴牌并对外转售，详见「企业版 · 商务合作」。

一句话：MLflow 偏「实验/模型管理库」，Kubeflow 偏「K8s 上的 ML 工具集」，CubeStudio 是「面向国产化的一站式 MLOps 平台」。 - 形态：MLflow 是轻量库；Kubeflow 是组件拼装；CubeStudio 开箱即用、Web 全流程。 - 国产化：CubeStudio 原生适配鲲鹏/飞腾/海光/昇腾与麒麟/UOS，Kubeflow/MLflow 需自行适配。 - 部署：三者都运行在 Kubernetes 上，但 CubeStudio 是开箱即用的完整平台（单机单节点到多节点集群均可），Kubeflow 需自行拼装组件；CubeStudio 还支持国产化与内网离线安装。 详见「竞品对比」页的多维表格。

支持。CubeStudio 提供大模型微调（如 LoRA / 全参微调流水线）与推理服务部署能力，可在国产算力（含昇腾）与 GPU 上运行，并通过 Pipeline 编排训练-评估-部署全过程，支持私有化大模型训推场景。

CubeStudio 面向信创环境设计：支持国产芯片、国产操作系统与国产数据库适配，支持完全内网/离线私有化部署，数据与模型不出域，便于在等保合规要求下落地。具体合规结论需结合用户单位的等保测评范围确认，平台提供日志审计、权限管理（RBAC）、LDAP/SSO 对接等能力以支撑合规建设。

结论：支持鲲鹏（ARM）、飞腾（ARM）、海光（x86）、昇腾 NPU 等国产算力，以及麒麟（Kylin）、统信 UOS 等国产操作系统。 - ARM 架构（鲲鹏/飞腾）：提供 ARM64 镜像与适配步骤。 - 昇腾 NPU：支持基于 CANN 的训练/推理任务调度。 - 国产数据库：支持适配达梦、人大金仓等（按部署文档配置连接）。 各芯片均附实测适配说明与截图，可在「部署文档 / 资质认证」核验。

是的，需要 Kubernetes。CubeStudio 通过 Kubernetes 调度容器化任务（训练、推理、Pipeline 等），因此运行平台依赖 K8s。 - 单机 / 试用 / 小团队：用单节点 Kubernetes（如 k3s / 单机 K8s）即可，一台机器就能起一套。 - 生产 / 多人 / 多集群算力：使用多节点 Kubernetes 集群，获得弹性调度、多租户与高可用。 Docker Compose 仅用于本地前后端开发调试，不承载容器任务调度，不能替代 Kubernetes 运行完整平台。

可以。CubeStudio 支持完全内网离线安装：通过离线镜像包与依赖包导入，无需公网即可完成部署，适配涉密/政企内网与信创环境，数据与模型全程不出域。

支持。CubeStudio 支持 CPU/GPU/国产 NPU 混合算力调度、GPU 共享/配额分配，以及多 Kubernetes 集群的统一纳管与算力分发，便于跨机房/跨架构资源池化。

Docker Compose 用于在本地快速拉起前端与后端做开发调试（不承载容器任务调度）： 1. 准备一台 Linux / Mac，安装 Docker 与 Docker Compose； 2. 拉取仓库：`git clone https://github.com/data-infra/cube-studio.git`； 3. 按文档配置 `.env`（端口、数据库、管理员账号）； 4. 执行 `docker compose up -d` 启动前后端； 5. 浏览器访问 `http://服务器IP:端口` 进入控制台。 注意：运行训练 / 推理 / Pipeline 等容器调度任务仍需 Kubernetes（测试或生产环境），完整平台部署请以 Kubernetes 为准，详见「部署文档」。

参考配置： - 单机部署（单节点 Kubernetes）：4 核 8G、50G 磁盘起步； - 训练/推理任务：按模型规模追加 GPU/NPU 与内存； - 生产集群（多节点 K8s）：建议 3 节点起，单节点 8 核 16G 以上，独立存储。 以上为参考值，实际按业务负载评估。

关键点： 1. 使用 ARM64（aarch64）架构镜像； 2. 校验基础镜像与依赖均为 ARM 版本，避免拉取到 x86 镜像导致 `exec format error`； 3. 若使用昇腾 NPU，需先安装对应 CANN 驱动与固件； 4. 部署后按「部署校验」清单验证训练与推理任务可正常调度。 详细命令见「部署文档」ARM 专题。

建议按以下清单逐项校验： 1. 控制台可正常登录，管理员账号生效； 2. 新建 Notebook 可启动并执行代码； 3. 提交一个示例 Pipeline，任务状态从 Pending → Running → Succeeded； 4. GPU/NPU 节点可被正确识别（资源面板显示算力）； 5. 模型部署示例可生成在线推理服务并返回结果。

CubeStudio 提供可视化 Pipeline 编排：将数据处理、训练、评估、部署等步骤定义为任务节点，按依赖连成有向图，配置各节点的镜像、命令、算力与挂载，即可一键运行并查看每步日志与产物。支持定时调度、参数化运行与失败重试。

CubeStudio 支持多机多卡分布式训练：通过分布式训练任务模板（如基于 PyTorch DDP / Horovod）声明副本数与算力，平台自动在 K8s 上拉起多个训练 Pod 并完成通信编排，训练日志与指标统一汇聚到实验管理中查看。

流程：选择已注册的模型版本 → 配置推理镜像与算力 → 设置副本数与访问方式 → 一键发布，平台生成在线推理 API（支持自动扩缩容与灰度）。可在服务列表查看 QPS、延迟与日志。

步骤：1. 上传/挂载训练语料数据集；2. 选择 LLM 微调任务模板（LoRA / 全参）并指定基座模型；3. 配置 GPU/NPU 算力与超参；4. 通过 Pipeline 串联「微调 → 评估 → 部署」；5. 完成后将微调模型一键发布为推理服务。支持国产算力（含昇腾）运行。

报错关键词：502 Bad Gateway。 排查步骤： 1. 检查后端服务 Pod/容器是否 Running：`kubectl get pods` 或 `docker compose ps`； 2. 查看后端日志是否启动报错（数据库连接、端口占用）； 3. 检查反向代理（nginx/ingress）upstream 地址与端口是否正确； 4. 确认服务就绪探针（readiness）已通过。 解决方案：多为后端未就绪或代理配置错误，重启后端并修正 upstream 即可恢复。

报错关键词：Pod Pending。 排查步骤： 1. `kubectl describe pod <name>` 查看 Events； 2. 常见原因：算力不足（GPU/NPU 无可用资源）、节点亲和/污点不匹配、PVC 未绑定、镜像拉取中； 3. 检查资源配额（ResourceQuota / LimitRange）。 解决方案：补充算力或调整任务资源声明、修复存储与调度约束。

报错关键词：ImagePullBackOff / ErrImagePull。 排查步骤： 1. 确认镜像名/标签正确，且架构匹配（ARM 环境需 ARM64 镜像）； 2. 内网环境确认镜像已导入私有仓库并配置 imagePullSecret； 3. 检查节点到镜像仓库的网络与认证。 解决方案：内网离线场景预先导入镜像到私有 Harbor 并修正拉取凭证。

CubeStudio 支持对接企业统一身份认证：在系统配置中填写 LDAP 服务地址、Base DN、绑定账号与用户/组映射；SSO 场景支持 OAuth2 / OIDC 对接企业 IdP。对接后用户使用企业账号登录，并按角色（RBAC）分配平台权限。配置示例见「部署文档 / 运维」专题。

CubeStudio 暴露 Prometheus 指标，可接入 Prometheus + Grafana 监控集群算力、任务状态与服务延迟，并通过 Alertmanager 配置阈值告警（如 GPU 利用率、节点不可用、任务失败率）。监控面板与告警规则示例见运维文档。

支持。高可用：核心组件多副本 + K8s 自愈，数据库与存储建议采用高可用方案。备份恢复：定期备份元数据库与对象存储/PVC 数据，并演练恢复流程；升级前先备份元数据，支持按版本回滚。

升级：先备份元数据库 → 拉取目标版本镜像 → 按版本说明执行数据库迁移 → 滚动更新组件 → 校验核心功能。 回滚：若升级异常，使用备份的元数据与上一版本镜像回退，K8s 可通过 `kubectl rollout undo` 回滚部署。建议在测试环境先行验证。