Research Experiment Platform (REXP)

REXP（发行包 rexprun）是面向科研实验的调度与管理平台，提供资源排队、独立环境、断点恢复、评测分析和 Ray Tune 参数搜索，支持 NVIDIA GPU 与昇腾 NPU。实验脚本、日志和结果集中保存在用户指定的数据根目录，可通过终端、Agent 或 Web 使用。

SSH 与 Agent 接入

Handfree SSH MCP 选择目标主机，REXP 插件通过同一条 SSH 连接调用该主机的 rexp，通过 SFTP 上传项目和取回结果。插件中的 platformRoot 是固定的数据根目录，rexpPath 是该主机的 rexp 程序位置；没有独立的 REXP 客户端包或 rexp client 命令。多台 SSH 主机沿用 Handfree 的 connectionName，各主机的路径保存在私人插件 registry 的 connections.<SSH别名> 中。

详见 SSH MCP 接入说明 和 Agent 接入指南。

被控端安装

pip install rexprun
rexp init --root /绝对路径/平台根目录
rexp doctor
rexp node env list

pip install 注册全局 rexp 命令。初始化会绑定环境管理器，准备独立的平台运行环境与轻量 default 实验环境。已有 uv/Conda 时优先 uv；都没有则询问是否安装，拒绝安装时使用 Python venv。平台无需 PyTorch；GPU/NPU 实验使用单独登记的兼容环境。

# 无交互并明确允许安装 uv（仅在缺失时安装）
rexp init --root /绝对路径/平台根目录 --install-manager uv --yes
# 不安装管理器，使用已有 Python 的 venv
rexp init --root /绝对路径/平台根目录 --env-manager venv --yes
# 按绑定管理器创建并登记实验环境
rexp node env create py311 --python 3.11 --description "实验基线环境，依赖按项目要求安装"

环境统一存放在 <根目录>/env/，平台为 platform，默认分析环境为 default。venv 的 --python 需要已安装解释器，uv/Conda 可指定 Python 版本。先检查已有环境是否可复用，再创建新环境。升级已有平台不需要重新初始化；使用 rexp doctor --json 返回的平台 Python 执行 -m pip install --upgrade rexprun。

运行实验

rexp project create demo --version v1
rexp submit demo v1 --config /绝对路径/平台根目录/research/demo/v1/configs/smoke.yaml
rexp start                           # 前台运行调度器
rexp status
rexp queue
rexp runs
rexp run show run_001
rexp run logs run_001
rexp run eval run_001
rexp run analyze run_001

控制端通过通用 plugin-list / plugin-activate / plugin-skill 发现插件并获取当前版本说明， 然后用 plugin-run 执行 rexp 命令（args 不含 rexp）。上传项目和取回结果使用 SSH MCP 原有 SFTP 工具；传输前先查询平台事实，确认固定根目录。

服务端接口

• rexp：被控端本地命令，Handfree 插件通过 SSH 调用。
• rexp mcp：服务端本机的原生 MCP stdio 接口。

完整命令见 使用说明书，配置与数据结构见 架构 和 Schema。

昇腾 NPU（普通实验已通过 A3 真卡验证）

支持读取 Linux npu-smi 整卡拓扑、检查实验环境的 torch_npu 能力，并按运行时逻辑卡号分卡。 实验配置增加 resources.accelerator_backend: npu；原 gpu_count / min_vram_gb 字段在 NPU 节点代表逻辑设备数量 / 每个逻辑设备的 HBM，保留名称以兼容已有配置。 一张 A3 物理卡可暴露两个逻辑设备，硬件摘要区分物理卡数与逻辑设备数，不把它们计作两张物理卡。 平台不自动安装驱动、CANN 或转换 CUDA 实验代码。实验自身需兼容昇腾 PyTorch。

用 rexp project create ascend_check --version v1 --template ascend_smoke 创建不下载模型的 真卡数值测试；详见生成项目的 README。已在 A3 / TorchNPU 2.10.0 真机通过矩阵乘法、反向传播、双逻辑设备隔离与排队自动续跑测试；尚未验证大模型。

可选 Ray Tune 搜索

支持用一个平台 run 管理一轮参数搜索，父任务预留资源，内部 trial 分别运行。 rexp project create search_demo --template ray_tune 获取 CPU 示例，实验环境需安装 rexprun[tune]。 通过普通 rexp submit 提交，rexp tune list / rexp tune show run_XXX 查看结果。 支持 Random/Grid、Optuna TPE、FIFO/ASHA 与多目标 Pareto；支持 CPU、CUDA 与昇腾 NPU 参数搜索。 完整预算、显卡分配、暂停恢复与存储约定见 使用说明书 的 Ray Tune 章节。

CLI 命名（0.1.66 起）

全局入口统一为 rexp；源码目录或指定解释器也可使用 python -m rexp。 按下方步骤迁移后只提供新入口，不再提供旧命令别名。发行包名为 rexprun，Python 导入名仍为 rexp。 SSH 插件使用 rexpPath 指向 Linux/macOS 的 bin/rexp 或 Windows 的 Scripts/rexp.exe。 修改命令名不改变平台根目录、~/.rexp 配置、环境注册或实验记录。

从旧测试包迁移

正式发行包名为 rexprun；rexp-server 是旧 TestPyPI 包。两者提供同一个 rexp Python 模块， 不要在同一环境中同时保留。正式包发布后，在平台所用 Python 环境先下载新版，再卸载旧包并安装：

python -m pip download --no-deps --dest /已确认的安装包目录 'rexprun==0.1.66'
python -m pip uninstall rexp-server
python -m pip install /已确认的安装包目录/rexprun-0.1.66-py3-none-any.whl
rexp version

迁移前确认实验与调度器已停止；保留原平台根目录和实验环境，无需重新初始化。

Ray Tune 的昇腾设备约定（0.1.68）

resources.accelerator_backend: npu 指定昇腾，resources.gpu_count 是搜索池逻辑设备数， tune.gpus_per_trial 是每个尝试的逻辑 NPU 数；名称保留兼容。A3 的 1 张物理卡可能提供两个逻辑设备。 rexp project create npu_search --template ray_tune_npu 提供真实 NPU 运算与梯度校验示例，实验环境需有兼容的 TorchNPU/CANN 和 rexprun[tune]。 控制器不预占卡；trial 在用户模块导入前领取租约，按 ASCEND_RT_VISIBLE_DEVICES 隔离，使用本进程可见的 npu:0，不写物理卡号。 不得覆盖容器 ASCEND_VISIBLE_DEVICES。控制器保留宿主允许的范围，禁用 Ray 对 NPU mask 的自动覆盖；私有 Ray runtime 的 GPU/NPU 资源均为 0，实际卡归平台队列管理，不使用 ray.get_gpu_ids() 判断分配。 config['_rexp'] 提供 accelerator_backend 与 allocated_device_ids；轻量 runtime 快照的 visible_devices 随后端记录对应 mask。 CPU/CUDA/NPU 共用优先级、动态让位、资源释放与暂停恢复；不抢占正在执行的尝试。模型续算必须保存原生 Ray checkpoint，频率按计算代价决定。 tune list --json 的 accelerator_backends 列出当前插件支持的后端，网页用它判断 NPU 搜索能力；旧节点不因网页升级而被误认为已支持。