qzcli - 启智平台任务管理 CLI

一个类似 kubectl/docker 风格的 CLI 工具，用于管理启智平台任务。

特性

一键登录: qzcli login 通过 CAS 认证自动获取 cookie，无需手动复制
资源发现: qzcli res -u 聚合历史任务、workspace 资源接口，自动发现工作空间、计算组、规格等资源并本地缓存
节点查询: qzcli avail 查询各计算组空余节点，支持低优任务统计和 cookie 失效自动刷新
交互式提交: qzcli create -i 提供层级式选择界面，缺少快照时按需预加载
任务列表: 美观的卡片式显示，完整 URL 方便点击
状态监控: watch 模式实时跟踪任务进度

开启启智的极致hack

qzcli login -u 用户名 -p 密码 && qzcli avail

分布式
  计算组                          空节点     总节点     空GPU GPU类型     
  -----------------------------------------------------------------
  某gpu2-3号机房-2                    3      xxx  x/xxx 某gpu2      
  某gpu2-3号机房                      0      xxx   x/xxx 某gpu2      
  某gpu2-2号机房                      0      xxx   x/xxx 某gpu2      
  cuda12.8版本某gpu1                 0      xxx  x/xxx 某gpu1

安装依赖

pip install rich requests prompt_toolkit mcp

cd qzcli_tool
pip install -e .

快速开始

# 1. 登录（自动获取 cookie）
qzcli login

# 2. 更新资源缓存（首次使用强烈建议执行，自动发现所有可访问的工作空间）
qzcli res -u

# 3. 查看空余节点
qzcli avail

# 4. 查看运行中的任务
qzcli ls -c -r

如果没有显式设置 QZCLI_ENV_FILE，qzcli 会默认尝试从 ~/.qzcli/.env 读取 CAS 凭据；如果你的凭据文件在别处，先导出 QZCLI_ENV_FILE=/path/to/.env：

cat > ~/.qzcli/.env <<'EOF'
QZCLI_USERNAME="your_username"
QZCLI_PASSWORD='your_password'
EOF

qzcli login

重要:

首次使用建议执行 qzcli res -u，会发现并缓存所有你有权限访问的工作空间，非交互式 create / 按名称解析资源时会更稳定

如果遇到 未找到名称为 'xxx' 的工作空间 错误，说明缓存需要更新，请重新执行 qzcli res -u

新加入的工作空间/项目需要重新执行 qzcli res -u 来更新缓存

qzcli create -i 在没有本地交互快照时会自动按需预加载，不要求你先手动执行 qzcli avail

MCP Server

如果你想在 Codex 或 Claude 里直接调用启智平台相关能力，可以把 qzcli 作为 MCP 工具接进去。

# 1. 进入项目目录（自行替换 xxxxx）
cd /inspire/xxxxx/qzcli_tool

# 2. 安装
python -m pip install -e .

安装完成后，可以先检查命令是否已经可用：

which qzcli-mcp

接入 Codex

执行下面两条命令即可：

codex mcp add qzcli -- qzcli-mcp
codex mcp list

如果你想固定使用绝对路径，也可以这样写：

codex mcp add qzcli -- /root/miniconda3/bin/qzcli-mcp （根据 which qzcli-mcp 的返回地址改)

接入 Claude Code

执行下面两条命令即可：

claude mcp add qzcli -- qzcli-mcp
claude mcp list

如果你想固定使用绝对路径，也可以这样写：

claude mcp add qzcli -- /root/miniconda3/bin/qzcli-mcp （根据 which qzcli-mcp 的返回地址改)

使用说明

正常使用时，不需要你手动先运行 qzcli-mcp。

把它加到 Codex 或 Claude 后，客户端会自动调用它，你手动运行 qzcli-mcp，一般只是为了排查问题，你可以直接这样告诉你的 Codex 或者 Claude Code：

开工了，我要登陆启智平台！

帮我看下现在有多少张华为Atlas950是空闲的

帮我看下现在有多少台某型号卡是空闲的，我要整台的8卡

即便数字部某天又在生产环境修改了返回值字段，模型也能根据原始返回JSON快速判断现在哪个字段代表原来的意图，无需手动再次重装qzcli工具（依赖于模型的上下文理解能力）

常见排障

如果提示找不到 qzcli-mcp，通常重新执行一次安装即可：

cd /inspire/xxxxx/qzcli_tool
python -m pip install -e .

如果已经注册过但客户端里看不到，先执行一次 codex mcp list 或 claude mcp list 确认是否注册成功
如果你手动运行 qzcli-mcp 后立刻报错，先修复启动报错，再回到客户端里接入

命令参考

认证命令

命令	说明	示例
`login`	CAS 登录获取 cookie	`qzcli login`
`cookie`	手动设置 cookie	`qzcli cookie -f cookies.txt`

# 交互式登录
qzcli login

# 带参数登录
qzcli login -u 学工号 -p 密码

# 脚本里从 stdin 读密码
echo 'your_password' | qzcli login -u 学工号 --password-stdin

# 查看当前 cookie
qzcli cookie --show

# 清除 cookie
qzcli cookie --clear

资源管理

命令	别名	说明
`resources`	`res`, `lsws`	管理工作空间资源缓存
`avail`	`av`	查询计算组空余节点

# 列出已缓存的工作空间
qzcli res --list

# 更新所有工作空间的资源缓存
qzcli res -u

# 更新指定工作空间
qzcli res -w CI -u

# 给工作空间设置别名
qzcli res -w ws-xxx --name 我的空间

# 查看空余节点（默认不包含低优任务统计，速度较快）
qzcli avail

# 查看空余节点（包含低优任务统计，即：空节点 + 低优任务占用的节点）
qzcli avail --lp

# 只查看 CI 工作空间
qzcli avail -w CI

# 只看某个计算组
qzcli avail -w CI -g lcg-xxx

# 显示空闲节点名称
qzcli avail -w CI -v

# 找满足 N 节点需求的计算组
qzcli avail -n 4

# 导出为脚本可用格式
qzcli avail -n 4 -e

如果本地 cookie 已过期，但你已经通过 shell 环境变量、QZCLI_ENV_FILE 指向的 .env（默认 ~/.qzcli/.env）或 ~/.qzcli/config.json 保存了 CAS 凭据，qzcli avail 会自动刷新 cookie 后继续查询。

任务列表

命令	别名	说明
`list`	`ls`	列出任务

# Cookie 模式（从 API 获取）
qzcli ls -c -w CI           # 指定工作空间
qzcli ls -c --all-ws        # 所有工作空间
qzcli ls -c -w CI -r        # 只看运行中
qzcli ls -c -w CI -n 50     # 显示 50 条

# 本地模式（从本地存储）
qzcli ls                    # 默认列表
qzcli ls -r                 # 运行中
qzcli ls --no-refresh       # 不刷新状态

创建任务

命令	别名	说明
`create`	`create-job`	创建并提交 GPU 分布式训练任务
`hpc`		提交 HPC/CPU 任务（Slurm，需 cookie 认证）
`batch`		从 JSON 配置文件批量提交任务

# 交互式提交：仅补齐未显式传入的参数
qzcli create -i

# 只针对某个 workspace 按需预加载交互快照
qzcli create -i -w "我的工作空间"

# 使用名称（从 qzcli res 缓存解析）
qzcli create \
  --name "my-training-job" \
  --command "bash /path/to/script.sh" \
  --workspace "我的工作空间" \
  --project "我的项目" \
  --compute-group "我的计算组" \
  --image registry.example.com/team/train-image:latest \
  --instances 4 \
  --priority 10

# 使用 ID
qzcli create \
  --name "my-training-job" \
  --command "bash /path/to/script.sh" \
  --workspace ws-<workspace_id> \
  --project project-<project_id> \
  --compute-group lcg-<compute_group_id> \
  --spec <spec_id> \
  --image registry.example.com/team/train-image:latest \
  --instances 4

# 预览 payload 不提交
qzcli create --name test --command "echo hi" --workspace "我的工作空间" --image registry.example.com/team/train-image:latest --dry-run

# JSON 输出（供脚本集成）
qzcli create --name test --command "echo hi" --workspace "我的工作空间" --image registry.example.com/team/train-image:latest --json

参数说明:

参数	短选项	默认值	说明
`--interactive`	`-i`		进入交互式任务提交模式，仅提示缺失参数
`--name`	`-n`	(必填)	任务名称
`--command`	`-c`	(必填)	执行命令
`--workspace`	`-w`		工作空间 ID 或名称
`--project`	`-p`	(自动选择)	项目 ID 或名称
`--compute-group`	`-g`	(自动选择)	计算组 ID 或名称
`--spec`	`-s`	(自动选择)	资源规格 ID
`--image`	`-m`	`docker.sii.shaipower.online/inspire-studio/dhyu-wan-torch29:0.4`	Docker 镜像
`--image-type`		`SOURCE_PRIVATE`	镜像类型
`--instances`		1	实例数量
`--shm`		1200	共享内存 GiB
`--priority`		10	优先级 1-10
`--framework`		pytorch	框架类型
`--no-track`			不自动追踪
`--dry-run`			只预览不提交
`--json`			JSON 输出

兼容性说明：历史脚本中的 qzcli create -i <image> 仍可用，CLI 会自动按旧语义解析为 --image。

提示: qzcli create -i 在 TTY 终端下会先进入单实例全屏的层级式选择菜单，按 workspace -> project -> compute_group -> spec 的顺序逐级选择，Enter/→ 进入下一层，← 返回上一层重新选择，界面会直接覆盖刷新而不是连续堆叠多个表格。compute_group 选项里会展示 GPU类型 / 占用口径 / 规格状态 / 空节点 / 空GPU / GPU利用率，其中 共享池 表示该数值来自底层物理 compute group 的共享资源池实时占用，规格状态 会标识该计算组的 spec 列表是否来自实时接口、缓存或异常分支。若某个计算组的实时 spec 查询失败，界面不会退出 TUI，而是在同一屏内给出告警，并支持 m 手动输入 spec ID、r 重试拉取、← 返回上一级更换计算组。完成资源选择后，再按原来的方式输入任务名称、执行命令、Docker 镜像等参数。若当前环境不是 TTY，或缺少 prompt_toolkit，CLI 会自动回退到原来的文本交互模式。若本地 cookie 已失效且已配置 CAS 账号密码，CLI 会自动刷新 cookie 后重试；若本地没有可复用的交互快照，create -i 会按需预加载当前可访问 workspace 的资源快照，并将结果保存到 ~/.qzcli/create_interactive_snapshot.json 供后续复用。已经显式传入的参数会直接跳过。非交互模式下，--project、--compute-group、--spec 省略时仍会自动从 qzcli res 缓存中选取第一个。首次使用前建议先运行 qzcli login && qzcli res -u。

提交 HPC/CPU 任务

HPC 任务使用 Slurm 调度，通过 /api/v1/hpc_jobs 接口提交，需要 cookie 认证（先运行 qzcli login）。

qzcli hpc \
  --name "bulk-NH3-check-outcar" \
  --workspace ws-<workspace_id> \
  --compute-group lcg-<compute_group_id> \
  --predef-quota-id <predef_quota_id> \
  --cpu 55 \
  --mem-gi 300 \
  --instances 30 \
  --cpus-per-task 55 \
  --image docker.sii.shaipower.online/inspire-studio/vasp_lmp-wyh:1203 \
  --entrypoint "cd /path/to/dir && bash run.sh"

参数说明:

参数	默认值	说明
`--name`	(必填)	任务名称
`--workspace`	(必填)	工作空间 ID 或名称
`--compute-group`	(必填)	计算组 ID（lcg-...）
`--predef-quota-id`	(必填)	预定义配额 ID（资源规格 UUID）
`--cpu`	(必填)	每节点 CPU 核心数
`--mem-gi`	(必填)	每节点内存 GiB
`--image`	(必填)	容器镜像地址
`--entrypoint`	(必填)	运行命令（shell 字符串）
`--project`	自动选择	项目 ID 或名称
`--instances`	1	节点数
`--cpus-per-task`	1	每任务 CPU 数
`--memory-per-cpu`	`5G`	每 CPU 内存
`--image-type`	`SOURCE_PRIVATE`	镜像类型
`--no-track`		不追踪任务
`--json`		JSON 输出

注意: HPC 任务在启智平台的「高性能计算任务」页面查看，URL 为 https://qz.sii.edu.cn/jobs/hpc?spaceId=<workspace_id>，与 GPU 分布式训练任务页面不同。

批量提交任务

# 从 JSON 配置批量提交
qzcli batch batch_eval.json --delay 3

# 预览所有任务
qzcli batch batch_eval.json --dry-run

# 遇到错误继续提交
qzcli batch batch_eval.json --continue-on-error

批量配置文件格式 (JSON):

{
  "defaults": {
    "workspace": "ws-<workspace_id>",
    "project": "project-<project_id>",
    "compute_group": "lcg-<compute_group_id>",
    "spec": "<spec_id>",
    "image": "docker.sii.shaipower.online/inspire-studio/dhyu-wan-torch29:0.4",
    "instances": 4,
    "shm": 1200,
    "priority": 10
  },
  "matrix": {
    "checkpoint": ["/path/to/ckpt1", "/path/to/ckpt2"],
    "eval_mode": ["mybench_universe", "video_universe"],
    "step": [105000, 200000]
  },
  "name_template": "eval-{checkpoint_basename}-{eval_mode}-step{step}",
  "command_template": "bash /path/to/eval.sh --checkpoint_dir {checkpoint} --eval_mode {eval_mode} --specific_steps {step}"
}

matrix 中的所有维度会做笛卡尔积，上面的例子会生成 2 x 2 x 2 = 8 个任务。模板中可用 {key} 引用 matrix 变量，路径类变量还可用 {key_basename} 获取文件名。

在 shell 脚本中循环提交（替代旧的 curl 方式）:

#!/bin/bash
CHECKPOINTS=("/path/to/ckpt1" "/path/to/ckpt2")
STEPS=(105000 200000)

for ckpt in "${CHECKPOINTS[@]}"; do
  for step in "${STEPS[@]}"; do
    qzcli create \
      --name "eval-$(basename $ckpt)-step${step}" \
      --command "bash /path/to/eval.sh --ckpt $ckpt --step $step" \
      --workspace "分布式训练" \
      --compute-group "xxx-3号机房-2" \
      --instances 4
    sleep 3
  done
done

任务管理

命令	说明	示例
`status`	查看任务详情	`qzcli status job-xxx`
`stop`	停止任务	`qzcli stop job-xxx`
`watch`	实时监控	`qzcli watch -i 10`
`track`	追踪任务	`qzcli track job-xxx`

工作空间视图

# 查看工作空间内运行任务（含 GPU 使用率）
qzcli ws

# 查看所有项目
qzcli ws -a

# 过滤指定项目
qzcli ws -p "我的项目"

输出示例

qzcli avail -v

CI-情景智能
  计算组                          空节点    总节点 GPU类型     
  -----------------------------------------------------
  OV3蒸馏训练组                       4      8 某gpu2      
    空闲: qb-prod-gpu1006, qb-prod-gpu1029, qb-prod-gpu1034, qb-prod-gpu1064
  openveo训练组                     1     79 某gpu2      
    空闲: qb-prod-gpu2000

qzcli ls -c -w CI -r

工作空间: CI-情景智能

[1] ● 运行中 | 44分钟前 | 44分36秒
    eval-OpenVeo3-I2VA-A14B-1227-8s...
    8×某gpu2 | 4节点 | GPU资源组
    https://qz.sii.edu.cn/jobs/distributedTrainingDetail/job-xxx

[2] ● 运行中 | 58分钟前 | 56分47秒
    sglang-eval-A14B-360p-wsd-105000...
    8×某gpu2 | 2节点 | GPU资源组

配置文件

配置存储在 ~/.qzcli/ 目录：

文件	说明
`config.json`	API 认证信息
`jobs.json`	本地任务历史
`.cookie`	Cookie（login 命令自动管理）
`resources.json`	资源缓存（工作空间、计算组等）
`create_interactive_snapshot.json`	`create -i` 的交互资源快照

环境变量

export QZCLI_USERNAME="your_username"
export QZCLI_PASSWORD="your_password"
export QZCLI_API_URL="https://qz.sii.edu.cn"
export QZCLI_ENV_FILE="/path/to/.env"   # 可选，自定义凭据文件位置

qzcli login / 自动刷新 cookie 会按下面的优先级读取凭据：

CLI 参数 > --password-stdin > shell 环境变量 > QZCLI_ENV_FILE 指向的 .env（默认 ~/.qzcli/.env） > ~/.qzcli/config.json > 交互输入

使用建议

日常使用: qzcli login && qzcli avail 一键登录并查看资源
提交前: qzcli avail -n 4 -e 找合适的计算组并导出配置
交互式提交 GPU 任务: qzcli create -i，如只关心单个 workspace 可加 -w
提交 GPU 任务: qzcli create -n "job" -c "bash run.sh" -w "分布式训练" --instances 4
提交 HPC 任务: qzcli login && qzcli hpc --name "job" --workspace ws-xxx --compute-group lcg-xxx --predef-quota-id uuid --cpu 55 --mem-gi 300 --instances 30 --image img --entrypoint "bash run.sh"
批量提交: qzcli batch config.json 从配置文件批量提交
监控任务: qzcli ls -c --all-ws -r 查看所有工作空间运行中的任务
详细信息: qzcli ws 查看 GPU/CPU/内存使用率

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

qzcli - 启智平台任务管理 CLI

特性

安装依赖

快速开始

MCP Server

接入 Codex

接入 Claude Code

使用说明

常见排障

推荐工作流

每日使用

提交任务前

查看任务

命令参考

认证命令

资源管理

任务列表

创建任务

提交 HPC/CPU 任务

批量提交任务

任务管理

工作空间视图

输出示例

qzcli avail -v

qzcli ls -c -w CI -r

配置文件

环境变量

使用建议

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

qzcli - 启智平台任务管理 CLI

特性

安装依赖

快速开始

MCP Server

接入 Codex

接入 Claude Code

使用说明

常见排障

推荐工作流

每日使用

提交任务前

查看任务

命令参考

认证命令

资源管理

任务列表

创建任务

提交 HPC/CPU 任务

批量提交任务

任务管理

工作空间视图

输出示例

qzcli avail -v

qzcli ls -c -w CI -r

配置文件

环境变量

使用建议