用途
get-available-resources 用于在用户请求资源感知规划,或某个具体工作负载需要资源规划时,构建当前进程可用资源的保守画像。它把主机清单、进程亲和性、cgroup/容器限制、调度器分配和加速器运行时可用性分开记录,避免把“可见”误判为“可用”。
主要能力
- 检测 CPU:区分主机逻辑核、主机物理核、进程亲和性逻辑核、cgroup v2 cpuset 逻辑核、cgroup v2 配额核数、Slurm 每进程 CPU 分配,并给出有效容量核数与保守的 CPU 工作进程上限。
- 检测内存:区分主机总内存/可用内存、当前 cgroup 用量、硬限制 memory.max、剩余层级容量、memory.high(压力/节流边界而非硬上限)、调度器内存分配及其范围,并给出保守的有效硬限制与可用估计。
- 检测加速器:将每个设备视为后端候选(NVIDIA GPU → CUDA 候选;AMD GPU → ROCm 候选;Apple 集成 GPU → Metal 候选)。管理查询可见性不代表调度器/容器权限、设备节点访问、驱动/运行时兼容、框架包兼容或算子/数据类型支持,因此 runtime_usable_devices 保持为 null,每个设备标记 runtime_compatibility: not_tested。
- 检测磁盘:区分容量字节、文件系统可用字节、用户可用块以及非写入权限检查;文件系统或项目配额可能更严格;绝对工作路径始终被脱敏。
- 检测调度器与容器:Slurm 变量描述分配范围,但实际执行取决于站点配置(如任务亲和性或 cgroups);优先以亲和性和 cgroup 观测作为执行证据。容器标记用于识别上下文,cgroup 控制用于识别限制。
- 工作负载规划:planner 消费经过校验的快照,不执行实际工作,可针对 cpu、mixed、io 工作负载给出有界的工作进程启发式建议,并支持显式上限、内存预留、加速器后端候选决策等控制项。
- 快照校验与差异比较:validate 校验快照,diff 在忽略 observed_at 的情况下比较资源状态,可用 --include-volatile 包含时间戳。
- 加速器只读诊断计划:生成固定、只读的管理查询参数列表,并分别设置可见性、权限和运行时兼容性门控,不执行任何诊断。
使用方式
从技能目录运行。
临时 stdout 快照:
python scripts/detect_resources.py
该命令仅向 stdout 输出 JSON。仅在普通 shell 权限可接受时才重定向。
显式私有文件:
python scripts/detect_resources.py --output resource-snapshot.json
显式输出限制为当前目录下的一个 .json 文件名,使用私有权限,拒绝符号链接和路径穿越,除非提供 --force 否则拒绝覆盖。
可选 psutil 增强:
uv pip install "psutil==7.2.2"
标准库检测器无需安装即可工作。导入是惰性的,导入失败会变成警告而非致命错误。
跳过管理工具探测:
python scripts/detect_resources.py --skip-accelerators
当不希望承担加速器发现延迟时使用。检测器仍会汇总允许列表可见性变量的存在与状态,但不返回其值。
规划工作负载:
python scripts/plan_workload.py resource-snapshot.json
--workload cpu
--tasks 100
--memory-per-worker-mib 2048
可选控制:--workers N 显式上限;--reserve-memory-mib N 保留在工作进程预算之外的内存;--workload cpu|mixed|io 选择有界工作进程启发式;--accelerator none|any|cuda|rocm|metal 请求候选后端决策但不声称可用;--output plan.json 显式私有本地输出,默认 stdout。
校验或比较快照:
python scripts/snapshot_tools.py validate resource-snapshot.json
python scripts/snapshot_tools.py diff before.json after.json
输入必须是常规、非符号链接、不超过 1 MiB 的 JSON 文件。差异比较是有界的。
可选加速器诊断计划:
python scripts/accelerator_diagnostics.py resource-snapshot.json
--backend auto
结果包含固定的只读管理查询参数列表,以及可见性、权限和运行时兼容性的独立门控。仅在将执行工作负载的确切环境中运行框架官方可用性检查。不要自动安装或变更驱动。
适用场景
- 用户明确请求资源感知规划时。
- 特定工作负载在运行前需要了解 CPU、内存、磁盘、调度器、容器或加速器约束时。
- 需要在 Slurm 分配或容器内判断实际可用资源上限时。
- 需要比较前后资源状态变化时。
- 需要生成加速器只读诊断计划而不实际执行诊断时。
限制
- 仅在用户请求或特定工作负载需要资源规划时运行检测,不要为每个科学任务持久化指纹。
- 默认使用 stdout;仅在用户选择明确的通用本地文件名时才持久化。
- 不运行压力测试、基准测试、大额分配、写入探测、设备重置、驱动安装或时钟/电源变更。
- 不转储环境变量,只读取检测器实现的具名 Slurm 和加速器变量。
- 不报告主机名、绝对路径、cgroup 路径、作业 ID、设备 UUID、PCI 地址或原始可见性变量值。
- 缺失观测视为未知,绝不将未知转换为无限。
- 绝不推断可见的主机 CPU、内存池或 GPU 在调度器分配或容器内可用。
- 管理查询可见性不建立调度器/容器权限、设备节点访问、驱动/运行时兼容、框架包兼容或算子/数据类型支持。
- 可见性/分配计数是上限而非保证。
- 磁盘的文件系统或项目配额可能比观测值更严格。
- Slurm 变量的实际执行取决于站点配置。
- 容器无有限 cgroup 值时仍可能看到主机清单;非 root cgroup 不自动标记为容器。
- 单个探测失败不应抹去成功观测;子进程 stderr 和原始异常文本不会复制到快照中,因为它们可能包含标识符或路径。
- 平台说明:Linux 仅读取有界的 /proc 和 cgroup v2 文件,并考虑祖先 CPU 和内存限制;macOS 使用固定 sysctl 键和有界的 system_profiler SPDisplaysDataType -json 查询,Apple 芯片内存为统一内存;Windows 可选 psutil 改善物理核、亲和性、可用内存和交换观测,处理器组范围可能导致主机与进程计数不同;Slurm 读取允许列表的分配变量,绝不输出作业、节点、提交主机、GPU-ID 或路径值;NVIDIA/AMD 管理 CLI 为可选,缺失是正常的,超时、截断、解析失败和运行时不确定性保持显式。
- 官方文档于 2026-07-23 刷新;更改语义或依赖固定版本前请查阅 references/sources.md。
- 代理操作流程:检查环境(确认 Python 环境和库版本,检查数据形状、类型和缺失值);确定输入(从数据或用户确认格式、标识符和参数,对会改变结果的值应询问而非猜测);先运行小版本(在样本或单折上运行并检查运行时和内存);使用上述说明和参考执行完整任务;验证结果(使用留出数据、固定随机种子和适当指标,检查泄漏,报告不确定性);报告(说明运行了什么、检查了什么、仍不确定什么)。
- 若出现内存不足或执行极慢,应子采样、使用分块或惰性计算、或减小模型规模,并告知用户变更内容。
- 若安装版本中缺少说明中的函数、标志或端点,应查阅已安装版本自身的文档并适配,告知用户,绝不虚构 API。
- 若必需输入、标识符或参数不明确,应询问用户,或在运行前明确说明假设。
- 完整性规则:绝不捏造结果、参数、标识符、引用或统计;若无法运行或验证,应明确说明;绝不报告本次会话未计算的指标,展示产生每个数字的代码路径;将版本特定细节视为可能过时,对照已安装版本的官方文档确认;在涉及花钱、消耗共享 GPU 或云配额、接触个人或患者数据、或不可撤销的操作前先询问。
附带文件
- scripts/detect_resources.py — 脱敏快照收集器。
- scripts/plan_workload.py — 确定性工作进程/内存规划器。
- scripts/snapshot_tools.py — schema 校验器和有界结构差异比较。
- scripts/accelerator_diagnostics.py — 非执行的只读诊断计划。
- tests/get-available-resources/ 在仓库根目录 — 无网络的 Linux、macOS、Windows、cgroup、Slurm 和加速器用例。
- references/resource_semantics.md — 解释和平台细节。
- references/snapshot_schema.md — schema 1.1 契约。
- references/sources.md — 带日期的官方来源台账。