启智CLI工具

安装

cd qzcli_tool
pip install -r requirements.txt
pip install -e .

快速开始

```bash

2. 安装

python -m pip install -e .

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

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

4. 查看运行中的任务（-c 模式必须指定工作空间，或用 --all-ws 查全部）

qzcli ls -c -r -w <工作空间名称或ID> qzcli ls -c -r --all-ws

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

qzcli login ```

重要: - 首次使用建议执行 qzcli res -u，会发现并缓存所有你有权限访问的工作空间，非交互式 create / 按名称解析资源时会更稳定 - 如果遇到 未找到名称为 'xxx' 的工作空间 错误，说明缓存需要更新，请重新执行 qzcli res -u - 新加入的工作空间/项目需要重新执行 qzcli res -u 来更新缓存 - qzcli create -i 在没有本地交互快照时会自动按需预加载，不要求你先手动执行 qzcli avail

使用说明

正常使用时，不需要你手动先运行 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 后立刻报错，先修复启动报错，再回到客户端里接入

每日使用

```bash

输出示例：

示例工作空间

查看所有工作空间运行中的任务

qzcli ls -c --all-ws -r

使用名称（从 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

后台启动长命令：立即返回 job_id，不等待结果

qzcli exec --detach blender-rl bash /workspace/train.sh

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

qzcli ws

输出示例

使用建议

• 日常使用: 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 logs job-xxx --tail 100 拉取任务容器日志，--follow 可持续轮询
• 详细信息: qzcli ws 查看 GPU/CPU/内存使用率

预览 payload 不提交

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

预览所有任务

qzcli batch batch_eval.json --dry-run

带参数登录

qzcli login -u 学工号 -p 密码

给工作空间设置别名

qzcli res -w ws-xxx --name 我的空间

交互式提交：仅补齐未显式传入的参数

qzcli create -i

从 JSON 配置批量提交

qzcli batch batch_eval.json --delay 3

配置文件

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

环境变量

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"   # 可选，自定义凭据文件位置
export QZCLI_SESSION_ID="my-agent-01"   # 可选，见下方「多 agent 并发 exec」

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

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

qzcli - 启智平台任务管理 CLI

一个类似 kubectl / docker 风格的启智平台命令行工具，把资源查询、任务提交、任务管理、日志查看和 MCP/agent 工作流收敛到 CLI 里完成。

Cookie 模式（从 API 获取）

qzcli ls -c -w 分布式 # 指定工作空间 qzcli ls -c --all-ws # 所有工作空间 qzcli ls -c -w 分布式 -r # 只看运行中 qzcli ls -c -w 分布式 -n 50 # 显示 50 条

/jobs/interactiveModel(ing)?Detail/、/jupyter/、/api/v1/notebook/lab/、/notebook/lab/ 等多种形式）

qzcli exec 'https://qz.sii.edu.cn/jobs/interactiveModelingDetail/cfe43e55-...?spaceId=ws-...' df -h

qzcli avail -v

示例工作空间
  计算组                          空节点    总节点 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 分布式 -r

工作空间: 示例工作空间

[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资源组

想让多个进程归到同一个 session（比如一个 agent 起了多个 qzcli 子进程）

export QZCLI_SESSION_ID="my-agent-01"

平台 API v1 → v2 迁移

启智平台正在把 /api/v1 下线（/openapi/v1/specs/list 已经 404），官方 CLI qz 是纯 v2 客户端。qzcli 的接口层已迁到 v2，策略是 v2 优先 + v1 兜底： 公开方法签名一律不变，内部由 api._v2_then_v1 分发，只在 v2 路由不通 （404/405/50x、或被网关 302 成 HTML）时回落 v1；业务错误和 401 直接抛出， 不做静默降级。

已迁移：train ListJobs / GetJob / StopJob、notebook ListNotebooks、 `workspace ListNodeDimension / ListTaskDimension / GetBasicInfo / GetOverviewTaskMetric、hpc ListJobs`。

两个仍留在 v1 的地方（v2 没有对应能力，见 docs/v1_to_v2_mapping.md）：

- /api/v1/project/list —— v2 的 project ListProjects 对普通账号是 AccessForbidden；且 v2 全域没有 ListWorkspaces，工作空间只能从项目推导 - /api/v1/notebook/lab/{id} —— v2 拿不到 Jupyter 访问地址，qzcli exec 依赖它

推荐工作流

JSON 输出（供脚本集成）

qzcli create --name test --command "echo hi" --workspace "我的工作空间" --image registry.example.com/team/train-image:latest --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。