KeepGPU CLI Operator
Use this workflow to run keep-gpu safely and effectively.
Prerequisites
- - Confirm at least one GPU is visible (
python -c "import torch; print(torch.cuda.device_count())"). - Run commands in a shell where CUDA/ROCm drivers are already available.
- Use
Ctrl+C to stop KeepGPU and release memory cleanly.
Install KeepGPU
Install PyTorch first for your platform, then install KeepGPU.
Option A: Install from package index
CODEBLOCK0
CODEBLOCK1
Option B: Install directly from Git URL (no local clone)
Prefer this option when users only need the CLI and do not need local source edits. This avoids checkout directory and cleanup overhead.
CODEBLOCK2
If SSH access is configured:
CODEBLOCK3
ROCm variant from Git URL:
CODEBLOCK4
Option C: Install from a local source checkout (explicit path)
Use this option only when users already have a local checkout or plan to edit source.
CODEBLOCK5
If the checkout already exists somewhere else, install by absolute path:
CODEBLOCK6
For ROCm users from local checkout:
CODEBLOCK7
Verify installation:
CODEBLOCK8
Command model
KeepGPU supports two execution modes.
Blocking mode (compatibility)
CODEBLOCK9
Use when users intentionally want one foreground process and manual Ctrl+C stop.
Non-blocking mode (recommended for agents)
CODEBLOCK10
INLINECODE4 auto-starts local service when unavailable.
INLINECODE5 stops only foreground blocking runs. For service mode sessions started by keep-gpu start, use keep-gpu status, keep-gpu stop, and keep-gpu service-stop.
CLI options to tune:
- -
--gpu-ids: comma-separated IDs (0, 0,1). If omitted, KeepGPU uses all visible GPUs. - INLINECODE13 : VRAM to hold per GPU (
512MB, 1GiB, or raw bytes). - INLINECODE16 : seconds between keep-alive cycles.
- INLINECODE17 (
--util-threshold alias): if utilization is above this percent, KeepGPU backs off.
Legacy compatibility:
- -
--threshold is deprecated but still accepted. - Numeric
--threshold maps to busy threshold. - String
--threshold maps to VRAM.
Agent workflow
- 1. Collect workload intent: target GPUs, hold duration, and whether node is shared.
- Choose mode:
- blocking mode for manual shell sessions,
- non-blocking mode for agent pipelines (default recommendation).
- 3. Choose safe defaults when unspecified:
--vram 1GiB, --interval 60-120, --busy-threshold 25. - Provide command sequence with verification and stop command.
- For non-blocking mode, include
status, stop, and daemon shutdown (service-stop).
Command templates
Single GPU while preprocessing (blocking):
CODEBLOCK11
All visible GPUs with lighter load (blocking):
CODEBLOCK12
Agent-friendly non-blocking sequence:
CODEBLOCK13
Open dashboard:
CODEBLOCK14
Remote sessions (preferred: tmux for visibility and control):
CODEBLOCK15
Fallback when tmux is unavailable:
CODEBLOCK16
Troubleshooting
- - Invalid
--gpu-ids: ensure comma-separated integers only. - Allocation failure / OOM: reduce
--vram or free memory first. - No utilization telemetry: ensure
nvidia-ml-py works and nvidia-smi is available. - No GPUs detected: verify drivers, CUDA/ROCm runtime, and
torch.cuda.device_count().
Example
User request: "Install KeepGPU from GitHub and keep GPU 0 alive while I preprocess."
Suggested response shape:
- 1. Install: INLINECODE35
- Run: INLINECODE36
- Verify:
keep-gpu status or dashboard http://127.0.0.1:8765/; stop session with keep-gpu stop --job-id <job_id> and daemon with keep-gpu service-stop.
Limitations
- - KeepGPU is not a scheduler; it only keeps already accessible GPUs active.
- KeepGPU behavior depends on cluster policy; some schedulers require higher VRAM or tighter intervals.
KeepGPU CLI 操作器
使用此工作流安全有效地运行 keep-gpu。
前置条件
- - 确认至少有一个 GPU 可见（python -c import torch; print(torch.cuda.device_count())）。
- 在已具备 CUDA/ROCm 驱动程序的 shell 中运行命令。
- 使用 Ctrl+C 停止 KeepGPU 并干净地释放内存。
安装 KeepGPU
首先为你的平台安装 PyTorch，然后安装 KeepGPU。
选项 A：从包索引安装
bash
CUDA 示例（将 cu121 改为你的 CUDA 版本）
pip install --index-url https://download.pytorch.org/whl/cu121 torch
pip install keep-gpu
bash
ROCm 示例（将 rocm6.1 改为你的 ROCm 版本）
pip install --index-url https://download.pytorch.org/whl/rocm6.1 torch
pip install keep-gpu[rocm]
选项 B：直接从 Git URL 安装（无需本地克隆）
当用户仅需 CLI 且无需本地源码编辑时，优先选择此选项。这避免了检出目录和清理开销。
bash
pip install git+https://github.com/Wangmerlyn/KeepGPU.git
如果已配置 SSH 访问：
bash
pip install git+ssh://git@github.com/Wangmerlyn/KeepGPU.git
从 Git URL 安装 ROCm 变体：
bash
pip install keep_gpu[rocm] @ git+https://github.com/Wangmerlyn/KeepGPU.git
选项 C：从本地源码检出安装（显式路径）
仅当用户已有本地检出或计划编辑源码时使用此选项。
bash
git clone https://github.com/Wangmerlyn/KeepGPU.git
cd KeepGPU
pip install -e .
如果检出已存在于其他位置，通过绝对路径安装：
bash
pip install -e /absolute/path/to/KeepGPU
对于从本地检出安装的 ROCm 用户：
bash
pip install -e .[rocm]
验证安装：
bash
keep-gpu --help
命令模式
KeepGPU 支持两种执行模式。
阻塞模式（兼容性）
bash
keep-gpu --gpu-ids 0 --vram 1GiB --interval 60 --busy-threshold 25
当用户有意使用单个前台进程并手动 Ctrl+C 停止时使用。
非阻塞模式（推荐用于代理）
bash
keep-gpu start --gpu-ids 0 --vram 1GiB --interval 60 --busy-threshold 25
keep-gpu status
keep-gpu stop --all
keep-gpu service-stop
当本地服务不可用时，start 会自动启动。
Ctrl+C 仅停止前台阻塞运行。对于由 keep-gpu start 启动的服务模式会话，请使用 keep-gpu status、keep-gpu stop 和 keep-gpu service-stop。
可调整的 CLI 选项：
- - --gpu-ids：逗号分隔的 ID（0、0,1）。如果省略，KeepGPU 使用所有可见 GPU。
- --vram：每个 GPU 保留的显存量（512MB、1GiB 或原始字节数）。
- --interval：保活周期之间的秒数。
- --busy-threshold（--util-threshold 别名）：如果利用率超过此百分比，KeepGPU 将退避。
旧版兼容性：
- - --threshold 已弃用但仍被接受。
- 数字型 --threshold 映射为繁忙阈值。
- 字符串型 --threshold 映射为显存量。
代理工作流
- 1. 收集工作负载意图：目标 GPU、保持时长以及节点是否共享。
- 选择模式：
- 手动 shell 会话使用阻塞模式，
- 代理管道使用非阻塞模式（默认推荐）。
- 3. 未指定时选择安全默认值：--vram 1GiB、--interval 60-120、--busy-threshold 25。
- 提供包含验证和停止命令的命令序列。
- 对于非阻塞模式，包含 status、stop 和守护进程关闭（service-stop）。
命令模板
预处理期间的单 GPU（阻塞）：
bash
keep-gpu --gpu-ids 0 --vram 1GiB --interval 60 --busy-threshold 25
所有可见 GPU 轻负载（阻塞）：
bash
keep-gpu --vram 512MB --interval 180
代理友好的非阻塞序列：
bash
keep-gpu start --gpu-ids 0 --vram 1GiB --interval 60 --busy-threshold 25
keep-gpu status
keep-gpu stop --job-id
keep-gpu service-stop
打开仪表盘：
text
http://127.0.0.1:8765/
远程会话（推荐使用 tmux 以获得可见性和控制）：
bash
tmux new -s keepgpu
keep-gpu --gpu-ids 0 --vram 1GiB --interval 300
按 Ctrl+b 然后 d 分离；重新连接：tmux attach -t keepgpu
当 tmux 不可用时的备用方案：
bash
nohup keep-gpu --gpu-ids 0 --vram 1GiB --interval 300 > keepgpu.log 2>&1 &
echo $! > keepgpu.pid
监控：tail -f keepgpu.log
停止：kill $(cat keepgpu.pid)
故障排除
- - 无效的 --gpu-ids：确保仅使用逗号分隔的整数。
- 分配失败/内存不足：减少 --vram 或先释放内存。
- 无利用率遥测：确保 nvidia-ml-py 正常工作且 nvidia-smi 可用。
- 未检测到 GPU：验证驱动程序、CUDA/ROCm 运行时以及 torch.cuda.device_count()。
示例
用户请求：从 GitHub 安装 KeepGPU，并在预处理期间保持 GPU 0 活跃。
建议的响应格式：
- 1. 安装：pip install git+https://github.com/Wangmerlyn/KeepGPU.git
- 运行：keep-gpu start --gpu-ids 0 --vram 1GiB --interval 60 --busy-threshold 25
- 验证：keep-gpu status 或仪表盘 http://127.0.0.1:8765/；使用 keep-gpu stop --job-id 停止会话，使用 keep-gpu service-stop 停止守护进程。
限制
- - KeepGPU 不是调度器；它仅保持已可访问的 GPU 处于活跃状态。
- KeepGPU 的行为取决于集群策略；某些调度器需要更高的显存量或更短的间隔。
