Orx 本地计算后端（`--backend local`）实战指南：在本机运行受监督的 GPU/CPU 实验

人工智能AI Agent深度研究自主智能体Agent 编排【免费下载链接】OpenResearchTurn your coding agents into research agents项目地址https://gitcode.com/GitHub_Trending/op/OpenResearch点击查看免费下载导读本文是 OrxOpenResearch将编码 Agent 转变为研究 Agent 的实验编排系统计算路由体系中local 后端的完整实战指南。当研究任务的规模适合放在当前机器上、或用户明确要求在本机运行时orx exp run expId --backend local会在本机启动一个与终端会话完全分离的受监督进程通过不可变快照保证运行的是实验分支记录的提交而不是随时可能被修改的工作区。读完本文你将掌握 local 后端的使用边界、run 目录的完整文件合同、取消与监督机制的底层原理以及结合 orx-compute 技能说明 的排障与等待流程。一、什么时候该用 local 后端local 后端只应在两种情况下使用用户明确要求在本机运行实验或者它是当前配置的默认后端。会话剧本session playbook会写明配置的默认值一个裸的orx exp run expId会直接使用它而已连接某个远程凭据并不构成切换到远程后端的信号——除非用户点名否则不要擅自更换计算来源。orx exp run expId --backend local与其他后端Hugging Face Jobs、Modal、Kubernetes、SSH、Slurm、Ray、OpenResearch、Tinker相比local 后端的特点是没有 flavor、host、image、timeout 标志它不使用任何云端实例规格不使用远程主机不拉取容器镜像也不施加超时上限。从源码看这些限制在提交阶段就被硬性拒绝src/local/localrun.rs中的submit_controller_run对--flavor与--image直接返回错误--backend local does not take --flavor、--image doesnt apply to --backend local因为控制器使用的是本机自身环境。与其他工作共享 CPU、RAM 和 GPUlocal 后端不隔离硬件资源它启动的进程与本机其他工作同时竞争资源。因此它优先服务于小规模任务或 CPU 规模的工作重型任务默认应交给远程计算除非用户另有要求。在 compute 后端抽象 中local 后端的能力表Capabilities被描述为remote: false、flavors: false、requires_flavor: false、source_transport: local archive标签为This machine——这从实现层面印证了它零运输、零规格的定位源码快照不需要任何网络传输直接以本地归档的形式进入 run 目录。二、最小工作流从提交到运行local 后端与所有后端共享同一个通用启动契约universal launch contract完整流程如下所有实验计算都必须用orx exp run启动。不要直接调用 provider CLI、调度器、裸 SSH 或训练命令本身。工作区只用于编辑、Git、编排和轻量检查直接运行的任务不受跟踪可能执行的不是记录提交对应的代码。保持 run 命令固定。在基线分支上一次性设置 run command后续通过子分支上的代码或配置变化来做实验变体。如果还没有设置先执行orx project edit projectId --run-command cmd启动前先提交。每个后端运行的都是记录提交的不可变源码快照未提交的文件会被排除在外任何后端都不需要 GitHub push。orx exp run只是入队并立即返回。后续用orx runs、orx logs、orx exp wait或orx exp wake跟进。关于并发--force允许在同一个实验上刻意地并发运行不带--force时如果该节点上已有在途 runorx会拒绝启动。这一行为在 compute.rs 的reserve_run中实现——它通过 per-experiment 的文件锁submission-locks/expId检查是否存在非终态 run若存在则报错并提示orx exp cancel expId或--force。三、run 目录布局与文件合同local 后端是 SSH 后端 的无运输孪生体两者共享相同的 run 目录布局只是 local 版位于 orx 数据目录下而非远端主机上orx data dir/local-runs/runId/ ├── run.sh 启动器导出环境变量 解包快照并执行 payload ├── log 合并的 stdout/stderr 流 ├── pid 分离的进程组领导者 PID └── exit_code payload 结束时写入的退出码数据目录orx data dir的解析顺序在 src/store.rs 中定义$ORX_DATA_DIR—— 显式强制覆盖最高优先级settings.json中持久化的dataDir用户选择$XDG_DATA_HOME/openresearch—— 系统默认基础目录~/.local/share/openresearch—— 硬编码兜底。run.sh的生成逻辑在 src/jobs/localbox.rs 的run_job中。它的形状是#!/usr/bin/env bash export KEYvalue # 导出的环境变量sh_quote 转义 cd run dir || exit 97 ( set -eo pipefail; mkdir -p repo; tar -xf snapshot -C repo; cd repo; run command ) log 21 echo $? exit_code这个( … )子 shell 结构是有意为之的内部exit或set -e失败只会终结子 shell 而不会终结run.sh本体因此exit_code总是会被写入。payload 脚本本体来自 compute.rs 的snapshot_scriptset -eo pipefail; mkdir -p repo; tar -xf archive -C repo; cd repo; command。文件权限与安全run.sh中导出的环境变量可能包含同步的 API token因此 Unix 下 run 目录会被设置为0o700、run.sh设置为0o600仅属主可读写见localbox.rs中的权限设置代码。测试 local_job_lifecycle 还验证了另一个细节secret 环境变量如TINKER_API_KEY不会出现在run.sh文件中而是通过Command::envs直接继承给子进程。四、环境传递local 运行拿到什么环境local 后端启动的进程使用本机环境但并不是简单的继承一切。从 src/local/localrun.rs 的submit_controller_run可以看到运行环境由以下几部分拼装用户同步的环境变量list_synced_env()如 API 密钥HF_TOKEN如果本地解析到 Hugging Face token则注入entry.or_insert不覆盖用户已有值PATH非 Windows 平台下使用 shell 的搜索路径确保从 macOS App 启动的 run 也能找到 python/uv/condaWindows 因 bash 以:切分 PATH、而C:会崩坏而跳过PYTHONUNBUFFERED1与PYTHONIOENCODINGutf-8由 src/jobs/mod.rs 的default_python_env注入用户显式设置时以用户为准、绝不覆盖保证 Python 输出实时流入log文件而非阻塞缓冲并避免 Windows 重定向输出使用 ANSI 代码页常为 cp1252导致非 ASCII 字符崩溃。secret 环境的特殊处理Tinker 相关的 API 密钥走secret_env它被控制器继承用于后续远程模型操作但不会持久化进run.sh。对应测试local_job_lifecycle断言run.sh内容不包含s3cr3t-value同时stream_logs能读到hello-42的正常输出。五、不可变快照契约绝不从 worktree 训练local 后端与所有后端共享同一条铁律提交的快照被解压到隔离的 run 目录后才执行固定命令绝不直接从工作区worktree训练。快照的生成在 compute.rs 的SourceSnapshot::create中完成读取实验分支的 HEAD SHAgit log层面用git archive --formattar revision一次性归档记录提交的完整文件树计算归档的 SHA-256 摘要以digest.tar为文件名做内容寻址存储同内容复用不重复归档含摘要与大小双重校验快照目录限制为仅属主可访问0o700归档文件0o600。run.sh中执行的 payload 会在 run 目录内mkdir -p repo tar -xf snapshot -C repo cd repo因此训练进程看到的永远是记录提交的不可变源码。这也意味着未提交的工作区改动不会进入任何 runrun 目录与工作区完全隔离agent 后续对代码的编辑不会污染正在运行的实验。值得注意的推论SourceSnapshot的信息revision、digest、size、path会被写入BackendDescriptor并随 run 持久化即使 supervisor 重启也能从 compute.rs 的SourceSnapshot::from_run重新加载归档并通过摘要校验恢复——这保证了运行什么这一事实不依赖工作树当前状态。六、进程生命周期与状态判定local run 从入队到终态的状态流转由 src/commands/supervise.rs 的run_local循环驱动每 5 秒轮询一次 localbox.rs 的inspect_job。状态判定规则清晰条件判定状态exit_code文件存在且内容非空按值判定0→COMPLETED非 0 →ERROR附exited with code Nexit_code存在但为空非终态——run.sh正在写入先截断再落地pid存在且进程存活RUNNINGpid存在但进程已死、无exit_code先短轮询重读防竞态仍无则判ERROR: process died without an exit code (killed?)pid尚未写入RUNNING正在启动存活探测刻意不用kill -0而用ps -o stat僵尸进程spawner 仍存活但尚未 reap对kill -0有响应却并未运行。pid_alive检查进程状态不以Z开头才视为存活Windows 下则用OpenProcess 零超时WaitForSingleObject真实退出码 259 被识别为存活。日志方面stream_logs按行号游标增量读取 run 目录的log文件缺失的日志文件只意味着 payload 还没输出。supervisor 中的tail_logs_local将该文件镜像到 store 的标准日志路径因此orx logs与仪表盘读到的都是同一个来源。七、取消机制终止整个进程组local 后端的取消通过TERM 进程组实现。由于run_job在 Unix 上用process_group(0)启动pid pgid一次kill -TERM -- -pid就能终止包括训练进程在内的整棵进程树Unix先尝试 TERM 进程组失败则回退为 TERM 单个进程见terminate_groupWindows使用taskkill /PID pid /T /F终止进程树并通过轮询领导者存活确认成功terminate_tree。被取消的 run 通常表现为进程已死且无 exit_code因此最终落入ERRORsupervisor 在已发送取消请求的前提下会将其报告为cancelled而非failedrun_status_for_stage与should_report_cancelled的组合逻辑。取消意图本身是持久化的cancel_requested标志 cancel.lock即使 supervisor 意外退出重启后的 supervisor 也能接续执行取消。八、后台监督进程orx supervise不要杀掉它orx exp run --backend local在完成提交后会通过 src/commands/exp.rs 的spawn_detached_supervise启动一个完全分离的orx supervise runId它拥有自己的进程组、无 stdio因此能存活于发起命令的终端和 SSH 会话之外。supervisor 承担三件事状态轮询每 5 秒调用inspect_job判定 run 状态并写入本地 store日志镜像并发地把 run 目录的log增量地镜像到 store 标准日志路径取消执行检测到本地持久化的取消意图后负责向进程组发送 TERM。因此文档中的告诫是硬性的不要杀掉这个分离的orx supervise进程。杀掉它等于断开 run 与 orx 状态机之间的眼睛——虽然训练进程仍在跑但状态、日志、取消与失败归因都会失联。supervisor 的设计是重启幂等的它只依赖本地 store 后端本身的状态含 supervisor.lock 防重入任何时刻重启都能从当前事实恢复跟踪。九、等待与唤醒orx exp wait/orx exp wakelocal run 与其他后端一样遵循wait 与 wake 二选一的跟进方式。阻塞式等待想尽快对 run 的终态作出反应时使用orx exp wait expId # 等待该实验最新一次 run 到达终态 orx exp wait --project projectId # 项目内首个 run 完成即返回 orx exp wait expId --interval 10 --timeout 3600必须且只能传expId与--project之一--project是预算循环budget-loop原语它只在首个 run 完成进入终态时返回run 启动、排队→运行等转换会被有意忽略每次循环 tick 重新发起wait 是睡眠直到变化的信号不是事实来源——每次返回后都要读orx runs projectId并对齐所有新终态的 run没有在途 run 时项目等待返回drained: no runs in flight默认 interval 为 5 秒、timeout 为 1800 秒超时以非零退出结束含义是尚无变化而非run 失败实现见 exp.rs 的waitinterval.unwrap_or(5).max(1)、timeout.unwrap_or(1800)失败的 run 会带reason:行提供方容量类失败通常可重试启动后的失败则需要读orx logs runId定位失败不等于新节点——按 orx-experiment-tree 的流程修复并重启动同一实验。休眠式唤醒想结束当前回合、等 run 成功或失败后再恢复orx exp wake expId唤醒是 opt-in 的只对done或failed触发并且排队在用户消息之后一个 run 上 wait 与 wake 只用其一。十、排障要点启动即报错不接收 --flavor/--image这是 local 后端的正确行为控制器使用本机环境没有实例规格概念run 长时间停留在 starting检查 run 目录是否已生成pidsupervisor 的inspect_job对pid 未写入视为 RUNNING通常只是启动瞬间日志不刷新确认PYTHONUNBUFFERED未被用户的显式设置覆盖default_python_env以用户设置优先进程莫名死亡无exit_code的死亡会被判为ERROR: process died without an exit code (killed?)排查是否有人向进程组发送了信号需要重放状态重启的 supervisor 会从 store 后端事实重新附着切勿删除local-runs/runId目录或 kill supervise 进程。十一、local 在计算路由中的位置在 SKILL.md 的决策表中local 是九个后端之一也是唯一零远程运输的选项不需要凭据、不需要 login、不需要 flavor。与需要--flavor的 hf/modal/openresearch、需要--host的 ssh/slurm、需要集群的 k8s/ray 相比local 是唯一一个 preflight 恒为 ready的后端compute.rs 的LocalCompute适配器preflight | _args | ready()。其源码索引后端参考文档local.md技能总纲后端选择与通用契约SKILL.md本地任务执行实现run.sh / pid / exit_code / 进程组取消src/jobs/localbox.rs本地控制器提交环境拼装 / 参数校验 / 监督启动src/local/localrun.rs后端无关的不可变快照与启动流水线src/compute.rssupervisor 本地循环状态轮询与日志镜像src/commands/supervise.rsorx exp命令族wait / wake / 分离监督src/commands/exp.rs数据目录解析src/store.rs适用前提总结local 后端适合小规模、CPU 规模、或用户明确指定本机的实验重型 GPU 工作请选择远程后端。run 之间共享本机资源运行内容严格锁定为已提交快照生命周期完全由分离的orx supervise托管——理解了这份文件合同与状态机你就能安全、可预测地把本机纳入 Orx 的实验编排体系。赞分享人工智能AI Agent深度研究自主智能体Agent 编排【免费下载链接】OpenResearchTurn your coding agents into research agents项目地址https://gitcode.com/GitHub_Trending/op/OpenResearch点击查看免费下载相关推荐OpenResearch orx 的 SSH 计算后端实战在自有服务器上以快照方式运行实验的完整指南OpenResearch orx 的 SSH 计算后端实战在自有服务器上以快照方式运行实验的完整指南 导读 在 OpenResearchorx的计算体系中人工智能AI Agent深度研究自主智能体Agent 编排ZenML Local Docker Orchestrator 实战指南用 Docker 在本地隔离环境运行流水线ZenML Local Docker Orchestrator 实战指南用 Docker 在本地隔离环境运行流水线 Local Docker OrchestrMLOps机器学习后端工作流自动化AI AgentFlower Agent 本地实战使用本地 SuperLink 在开发机上运行 AgentAppFlower Agent 本地实战使用本地 SuperLink 在开发机上运行 AgentApp 本文讲解 Flower 官方文档 Run an AgentA人工智能联邦学习机器学习深度学习创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考