huawei-cloud-modelarts-notebook-management

Huawei Cloud ModelArts Notebook 管理

通过 hcloud CLI 全生命周期管理 ModelArts Notebook 实例 — 涵盖 7 个功能域中的 31 个 API 接口。

---

概述

此 skill 可通过 hcloud CLI 管理 Huawei Cloud ModelArts Notebook 实例。它涵盖 Notebook 的完整生命周期，包括实例增删改查、启动/停止、租期续订、标签管理、镜像管理、规格/集群查询、功能查询和动态存储管理。

架构

User Request → Agent → hcloud ModelArts <Operation> --cli-region={region} [--params] → Huawei Cloud ModelArts API

适用场景

• 日常运维：列出 Notebook、检查状态、查看详情、查询规格
• 实例生命周期：创建、启动、停止、更新、删除 Notebook 实例
• 镜像管理：将运行中的实例保存为镜像、注册/列出/删除/同步自定义镜像
• 存储管理：动态为 Notebook 实例挂载/卸载存储
• 租期管理：查询和续订 Notebook 租期
• 标签管理：创建、删除、查询 Notebook 标签

范围

本 skill 仅支持 ModelArts Notebook 实例管理（31 个 API），涵盖上述 7 个功能域。

不支持以下 ModelArts 能力，相关请求请使用对应 skill：

• 推理服务（在线服务、批量服务）— 使用推理服务管理 skill
• DevServer（开发环境）— 使用 DevServer 管理 skill
• 模型管理（导入/导出/发布模型）— 使用模型管理 skill
• 训练作业（创建/管理训练任务）— 使用训练作业管理 skill
• 自动搜索、超参调优 — 使用自动搜索 skill

---

前提条件

1. 已安装并完成认证的 hcloud CLI — 参考：https://support.huaweicloud.com/qs-hcli/hcli_02_003.html
2. 已通过 hcloud 配置 Huawei Cloud AK/SK（请参阅下文的安全与凭证检查）
3. 目标区域已启用 ModelArts 服务
4. IAM 权限 — 请参阅 references/iam-policies.md

安全与凭证检查

⚠️ 严重：本节定义了 Agent 的安全边界。请严格遵守。

🔒 安全规则（必须遵守）

• 🚫 绝不读取、回显或打印 AK/SK 值（例如，cat ~/.hcloud/config.json、echo $HW_ACCESS_KEY 均禁止）
• 🚫 绝不读取或 cat 凭证文件，例如 ~/.hcloud/config.json 或任何可能包含密钥的文件
• 🚫 绝不要求用户在对话或命令行中直接输入 AK/SK
• 🚫 绝不执行 hcloud configure set --cli-access-key=... --cli-secret-key=... — 凭证配置是用户的责任，应在 Agent 会话之外完成
• 🚫 绝不在每次 API 调用时传入 --cli-access-key/--cli-secret-key — 在整个请求期间，这些值都会暴露在进程列表（ps aux）中
• ✅ 始终使用 hcloud configure list 检查凭证状态（仅检查是否存在，不查看值）
• ✅ 如果不存在有效配置文件，停止并指导用户在本会话之外配置凭证
• ✅ 建议使用权限最小化的 IAM 用户，而不是主账号

✅ Agent 凭证检查（唯一可接受的检查方式）

# Step 1: Check credential status — presence only, not values
hcloud configure list

• ✅ 预期结果：显示具有 mode: AKSK 的有效配置文件

• ❌ 如果结果为空/无效 → 按照以下 3 个步骤指导用户：

  逐步指导（可复制给用户）：

  "未找到有效凭证。请在终端中按照以下 3 个步骤操作："

  ① 获取 AK/SK 登录 Huawei Cloud 控制台 → IAM → 访问密钥。如果还没有访问密钥，请点击“创建访问密钥”并妥善保存。

  ② 在终端中运行以下命令（一次性设置）：

  hcloud configure set --cli-access-key=<YOUR_AK> --cli-secret-key=<YOUR_SK>
  

  （将 <YOUR_AK> 和 <YOUR_SK> 替换为步骤 ① 中获取的值）

  ③ 完成后请告诉我“已配置”，我会验证配置是否生效。

  注意：configure set 命令会将凭证存储在 ~/.hcloud/config.json 中。此后，所有 hcloud 命令都会自动使用这些凭证，无需再次传入 AK/SK。

  Agent：请勿自行执行任何 configure set 命令。

🔧 用户责任（用于文档说明，不用于 Agent 执行）

用户在 Agent 会话之外（在自己的终端中）配置凭据：

# One-time setup — run this in your terminal, NOT in the agent chat
HISTCONTROL=ignorespace
 hcloud configure set --cli-access-key=<YOUR_AK> --cli-secret-key=<YOUR_SK>

⚠️ 注意：hcloud CLI 不会读取 HW_ACCESS_KEY/HW_SECRET_KEY 环境变量（这些变量仅供 Python SDK 使用）。hcloud configure set 是唯一受支持的凭据配置方法。

---

工作流

步骤 1：确定操作

根据用户的请求，确定其需要执行的笔记本操作：

用户意图	操作类别
创建/列出/查看/更新/删除/启动/停止笔记本	实例管理
查询/续期租约	租约管理
创建/删除/查询标签	标签管理
保存/注册/列出/删除/同步镜像	镜像管理
查询规格/集群/功能	规格与集群
挂载/卸载/列出存储	动态存储

步骤 2：执行 CLI 命令

hcloud ModelArts <Operation> --cli-region={region} [--key=value ...]

{region} 必须替换为实际区域，例如 cn-north-4。不要硬编码区域。

步骤 2.5：查阅已知问题（仅写入操作）

执行任何写入操作之前，请阅读 references/known-issues.md，并检查目标 API 的已知问题、参数修正和所需的解决方法。

需要应用的常见解决方法：

API	问题	解决方法
CreateNotebook (EVS)	CLI 拒绝 --volume.category=EVS	使用带有 {"body":{...}} 包装对象的 --cli-jsonInput，并显式指定 --project_id
CreateNotebook	参数名 flavor_id 错误	使用 --flavor
CreateNotebook	参数名 volume.size 错误	使用 --volume.capacity
CreateNotebook	ownership=PRIVATE 无效	使用 MANAGED 或 DEDICATED
AttachDynamicStorage	STOPPED 实例被拒绝	确保实例处于 RUNNING 状态
AttachDynamicStorage	mount_path 格式错误	必须以 /data/ 开头并以 / 结尾
RegisterImage	arch 大小写不匹配	使用大写的 X86_64/AARCH64
RenewLease	type 大小写不匹配	使用小写的 timing/idle

对所有写入操作，此步骤都是强制要求。跳过此步骤可能导致 CLI 参数错误或已记录过的 API 故障。

步骤 3：处理写入操作

对于所有写入操作（Create/Update/Delete/Start/Stop/Attach/Detach/Register/Sync/Renew），执行前请征求用户确认。对于收费操作（CreateNotebook、StartNotebook），应先查询 BSS 定价，告知用户相关费用。有关定价查询工作流，请参阅 references/pricing-inquiry.md。

删除类操作交互指引：当用户请求删除标签（DeleteNotebookTags）、删除镜像分组（DeleteImageGroup）等操作但未指定具体对象时，必须先查询当前对象列表（如 ShowNotebookTags / ListImageGroup），向用户展示并确认要删除哪个对象，确认后再执行。避免因上下文不明确导致误删。

---

KooCLI 命令格式规范

hcloud ModelArts <Operation> --cli-region={region} [--key=value ...]

特性	说明	示例
服务名称	固定为：ModelArts	ModelArts
操作名称	PascalCase	ListNotebooks、CreateNotebook
区域参数	--cli-region={region}	--cli-region=cn-north-4
简单参数	--key=value	--id=xxx
索引参数	--key.1=value1	--tags.1.key=env
project_id	若省略则自动解析	使用已配置的项目 ID

注意：若省略 --project_id，系统会根据身份验证凭据自动解析该参数。仅在指定特定项目时才显式添加。

---

核心命令

所有 7 个功能领域中的 31 个 CLI 命令示例均记录在单独的参考文件中。

📖 有关详细命令语法、参数和示例，请阅读 references/cli-command-examples.md

快速索引

#	领域	API	关键操作
1	实例管理	8	CreateNotebook、ListNotebooks、ListAllNotebooks、ShowNotebook、UpdateNotebook、DeleteNotebook、StartNotebook、StopNotebook
2	租约管理	2	ShowLease、RenewLease
3	标签管理	3	ShowNotebookTags、CreateNotebookTags、DeleteNotebookTags
4	镜像管理	9	CreateImage、ListImage、RegisterImage、ShowImage、DeleteImage、SyncImage、ListImageGroup、DeleteImageGroup、UpdateImageGroup
5	规格与集群	4	ListFlavors、ShowSwitchableFlavors、ListAuthoringClusters、ShowCluster
6	功能查询	1	ListFeatures
7	动态存储	4	ListDynamicStorages、AttachDynamicStorage、ShowDynamicStorage、DetachDynamicStorage

执行任何命令时，务必参阅参考文件，以确认准确的参数名称、必填/可选标记和使用方式。

---

参数确认

参数	必填	说明	示例
{region}	是	华为云区域	cn-north-4、cn-east-3
{instance_id}	是（大多数操作）	Notebook 实例 UUID	xxx-xxx-xxx
{image_id}	创建/列表	镜像 UUID	xxx-xxx-xxx
{flavor_id}	创建	实例规格 ID	modelarts.bm.4xlarge.pro
{resource_id}	标签操作	用于添加标签的资源 ID	xxx-xxx-xxx
{cluster_id}	ShowCluster	集群 ID	xxx-xxx-xxx
{storage_id}	存储操作	存储 ID	xxx-xxx-xxx
{feature}	ListFeatures	功能名称	NOTEBOOK
{project_id}	否（自动）	项目 ID；省略时自动解析	省略则使用默认值

---

SDK 回退方案

如果 CLI 操作因 CLI 缺陷而失败，请回退到 SDK：

from huaweicloudsdkcore.auth.credentials import BasicCredentials
from huaweicloudsdkmodelarts.v1.modelarts_client import ModelArtsClient
from huaweicloudsdkmodelarts.v1.region.modelarts_region import ModelArtsRegion

credentials = BasicCredentials(ak="{AK}", sk="{SK}", project_id="{project_id}")
client = ModelArtsClient.new_builder() \
    .with_credentials(credentials) \
    .with_region(ModelArtsRegion.value_of("{region}")) \
    .build()

---

参考文档

文档	说明
references/cli-command-examples.md	所有 31 个 API 的详细 CLI 命令语法和示例
references/iam-policies.md	最小权限 IAM 策略
references/verification-method.md	验证和测试方法
references/dataflow-diagram.md	Mermaid 数据流图
references/acceptance-criteria.md	验收标准清单
references/api-paths.md	SDK 源码中的 REST API 路径
references/cli-installation-guide.md	CLI 安装和身份验证指南
references/known-issues.md	已知问题和解决方法
references/pricing-inquiry.md	可计费操作的 BSS 价格查询指南

已知问题（摘要）

完整详情：references/known-issues.md

#	问题	关键要点
1	CLI 未在 volume.category 枚举中包含 EVS	使用带 body 封装的 --cli-jsonInput，并显式指定 --project_id
2	存储类别 × 所有权矩阵	EVS:MANAGED ✅，OBS/OBSFS:DEDICATED ✅，OBS/OBSFS:MANAGED ❌
3	DEDICATED 所有权要求提供 pool_id	先查询专用存储池，再传入顶层 pool_id
4	将 OBS 用作 data_volume 会静默失败	将 OBS 用作主 volume，或将 OBSFS 用作 data_volume
5	存储桶类型（POSIX 与 OBJECT）无关紧要	两者都支持 DEDICATED 所有权
6	不支持 OBSFS:MANAGED 扩展存储	对 OBSFS 使用 DEDICATED
7	OBS/OBSFS 主卷需要 dew_secret_name	在 DEW/CSMS 密钥中存储 AK/SK
8	OBS 数据卷需要 mount_path	始终指定有效路径
9	镜像与规格的架构不匹配	确保镜像和规格的 arch 字段一致
10	--cli-jsonInput 通用解决方法	必须使用 {"body":{...}} 封装，并显式传入 --project_id
11	ShowLease 的时长是总时长，而非剩余时长	计算：remaining = (create_at + duration) - current_time
12	ListImageGroup 的响应字段因 --limit 而异	不指定 limit 时使用 groups 字段；指定 limit 时使用 data 字段。两种情况都要解析
13	AttachDynamicStorage 仅支持 POSIX 存储桶	OBJECT 存储桶会被拒绝，并返回 ModelArts.6772；使用 obsutil stat 进行验证

---

注意事项

• 所有 31 个 API 接口均可通过 hcloud ModelArts CLI 使用
• 如果 CLI 遇到问题，可回退使用 huaweicloudsdkmodelarts v1 SDK
• 通过 --cli-region 指定区域，不应将其硬编码
• 如果省略 --project_id，系统会根据凭据自动解析（但使用 --cli-jsonInput 时必须显式指定）
• 执行所有写入操作（Create/Update/Delete/Start/Stop/Attach/Detach/Register/Sync/Renew）前，必须获得用户确认
• 计费操作（CreateNotebook、StartNotebook）需要先查询 BSS 定价，以便告知用户费用
• API 路径已根据 SDK 源码中的 _http_info resource_path 验证，不使用推断的端点
• 任何文件中都没有硬编码的 AK/SK——凭据由 hcloud 通过 hcloud configure list/set 管理