qzcli

qzcli — 启智プラットフォームのタスク管理

Qizhi（启智）プラットフォームでGPUコンピューティングジョブを管理する、kubectl/docker風のCLIです。

GitHub： tianyilt/qzcli_tool

環境コントラクト

Qizhiは、../shared-references/compute-env-contract.mdにおけるスケジューラークラスター型です。 イメージはプラットフォーム外でビルドされ、送信時に指定されるため、宣言型の 環境仕様とenv:<name>@<specHash>台帳（.aris/compute/qizhi.md）によって、 「どのイメージにどのスタックが含まれているか」を把握できます。 長時間実行のためにイメージを信頼する前に、送信したジョブ内でカーネルの証拠を実行してください（ログイン側では実行しないでください）。

インストール

pip install rich requests prompt_toolkit mcp
git clone https://github.com/tianyilt/qzcli_tool
cd qzcli_tool && pip install -e .

MCP 連携（任意）

Claude CodeまたはCodexからqzcliをMCPツールとして直接使用するには：

# Claude Code
claude mcp add qzcli -- qzcli-mcp

# Codex
codex mcp add qzcli -- qzcli-mcp

---

設定

認証情報は次の優先順位で読み込まれます： CLI args > --password-stdin > env vars > QZCLI_ENV_FILE (.env) > ~/.qzcli/config.json > interactive input

# Option A: env file (recommended)
mkdir -p ~/.qzcli
cat > ~/.qzcli/.env <<'EOF'
QZCLI_USERNAME="your_username"
QZCLI_PASSWORD="your_password"
EOF

# Option B: environment variables
export QZCLI_USERNAME="your_username"
export QZCLI_PASSWORD="your_password"
export QZCLI_API_URL="https://qz.yourorg.edu.cn"

設定ファイルは~/.qzcli/に保存されます：config.json、.cookie、resources.json、jobs.json。

---

クイックスタート

# 1. Login
qzcli login

# 2. Discover and cache workspaces/compute groups (run once, re-run after joining new workspaces)
qzcli res -u

# 3. Check available nodes
qzcli avail

# 4. List running jobs
qzcli ls -c -r

---

認証

# Interactive login
qzcli login

# With credentials
qzcli login -u YOUR_USERNAME -p 'YOUR_PASSWORD'

# Read password from stdin (for scripts)
echo 'YOUR_PASSWORD' | qzcli login -u YOUR_USERNAME --password-stdin

# Check current cookie
qzcli cookie --show

# Clear cookie
qzcli cookie --clear

注： 認証情報が設定されている場合、qzcli availはCookieの期限切れ時に自動更新します。

---

リソースの検出

# List cached workspaces
qzcli res --list

# Refresh all workspace resource cache (run this first!)
qzcli res -u

# Refresh a specific workspace
qzcli res -w MY_WORKSPACE -u

# Set a human-readable alias for a workspace
qzcli res -w ws-xxxxxxxx --name "My Workspace"

---

利用可能なノードの確認

# All workspaces
qzcli avail

# Including low-priority task nodes (slower but more accurate)
qzcli avail --lp

# Specific workspace
qzcli avail -w MY_WORKSPACE

# Find compute groups with N free nodes
qzcli avail -n 4

# Export IDs for scripting
qzcli avail -n 4 -e

# Show idle node names
qzcli avail -w MY_WORKSPACE -v

---

ジョブの送信

対話形式（初回の使用におすすめ）

# Full interactive selection: workspace → project → compute group → spec
qzcli create -i

# Interactive for a specific workspace only
qzcli create -i -w "My Workspace"

TUIでは各階層にGPUの種類、空き状況、仕様のステータスが表示されます。Enter/→を押すと下の階層に進み、←を押すと戻ります。

非対話形式

# Using names (resolved from qzcli res cache)
qzcli create \
  --name "my-training-job" \
  --command "bash /path/to/train.sh" \
  --workspace "My Workspace" \
  --compute-group "My Compute Group" \
  --image YOUR_REGISTRY/team/image:tag \
  --instances 4 \
  --priority 10

# Using IDs directly
qzcli create \
  --name "my-job" \
  --command "bash /path/to/train.sh" \
  --workspace ws-YOUR_WORKSPACE_ID \
  --compute-group lcg-YOUR_LCG_ID \
  --spec YOUR_SPEC_ID \
  --image YOUR_REGISTRY/team/image:tag \
  --instances 4

主なパラメーター：

パラメーター	デフォルト	説明
--name / -n	required	ジョブ名
--command / -c	required	実行するコマンド
--workspace / -w		ワークスペース名またはID（ws-...）
--compute-group / -g	auto	コンピューティンググループ名またはID（lcg-...）
--spec / -s	auto	リソース仕様ID
--image / -m		Dockerイメージ
--instances	1	インスタンス数
--shm	1200	共有メモリ（GiB）
--priority	10	優先度（1～10）
--dry-run		プレビューのみ。送信しません
--json		スクリプト用のJSON出力

# Preview before submitting
qzcli create --name test --command "echo hi" --workspace "My Workspace" \
  --image YOUR_IMAGE --dry-run

環境変数の受け渡し（既存の送信スクリプト向け）

# Pass vars directly — do NOT use "export VAR; bash script.sh"
WORKSPACE_ID="ws-YOUR_WORKSPACE_ID" \
LCG_ID="lcg-YOUR_LCG_ID" \
SPEC_ID="YOUR_SPEC_ID" \
CHECKPOINT_DIR="/path/to/checkpoint" \
bash YOUR_SUBMIT_SCRIPT.sh

HPC / CPUジョブ（Slurm）

qzcli hpc \
  --name "my-cpu-job" \
  --workspace ws-YOUR_WORKSPACE_ID \
  --compute-group lcg-YOUR_LCG_ID \
  --predef-quota-id YOUR_QUOTA_ID \
  --cpu 55 --mem-gi 300 --instances 30 \
  --image YOUR_REGISTRY/team/cpu-image:tag \
  --entrypoint "cd /path/to/dir && bash run.sh"

---

バッチ送信

# Submit from config file
qzcli batch batch_config.json --delay 3

# Preview all jobs
qzcli batch batch_config.json --dry-run

# Continue on error
qzcli batch batch_config.json --continue-on-error

設定形式（batch_config.json）：

{
  "defaults": {
    "workspace": "ws-YOUR_WORKSPACE_ID",
    "compute_group": "lcg-YOUR_LCG_ID",
    "spec": "YOUR_SPEC_ID",
    "image": "YOUR_REGISTRY/team/image:tag",
    "instances": 4,
    "priority": 10
  },
  "matrix": {
    "checkpoint": ["/path/to/ckpt1", "/path/to/ckpt2"],
    "step": [50000, 100000]
  },
  "name_template": "eval-{checkpoint_basename}-step{step}",
  "command_template": "bash eval.sh --checkpoint {checkpoint} --step {step}"
}

マトリックスキーは直積として展開されます（上記の例では2×2＝4ジョブ）。パスのベース名には{key_basename}を使用してください。

シェルループ（別の方法）

for step in 040000 050000 060000; do
  qzcli create \
    --name "eval-step${step}" \
    --command "bash eval.sh --step $step" \
    --workspace "My Workspace" \
    --compute-group "My Compute Group" \
    --instances 4
  sleep 3
done

---

ジョブ管理

# List jobs
qzcli ls -c -w MY_WORKSPACE          # specific workspace
qzcli ls -c --all-ws                 # all workspaces
qzcli ls -c -w MY_WORKSPACE -r       # running only
qzcli ls -c -w MY_WORKSPACE -n 50    # show 50

# Stop a job
qzcli stop JOB_ID

# Job status / details
qzcli status JOB_ID

# Watch all running jobs (refresh every 10s)
qzcli watch -i 10

# Workspace view with GPU utilization
qzcli ws
qzcli ws -a           # all projects
qzcli ws -p "My Project"

---

トラブルシューティング

問題	原因	対処方法
Cookieの期限切れ	セッションの空白期間	qzcli loginを再実行します
未找到名称为 'xxx' 的工作空间	キャッシュが古い	qzcli res -uを実行します
create -iでリソースが表示されない	キャッシュが空	qzcli login && qzcli res -uを実行します
qzcli-mcpが見つからない	インストールされていない	cd qzcli_tool && pip install -e .を実行します
仕様がワークスペースにない	IDの不一致	仕様IDを正しいワークスペースに合わせます
ジョブがエラーなく失敗する	スクリプトのsys.exit(0)	ジョブログを直接確認します
zshのグロブエラー	リモートシェルがzsh	コマンドをbash -cで囲むか、Pythonを使用します