English | 简体中文

Python 实验管理 Web UI 工具：参数可视化编辑、批量任务生成、任务调度管理、实时日志流式查看与 CSV 指标导出。
全流程本地运行，围绕磁盘工作区组织状态，让脚本实验这件事终于变得清楚、直接、可追踪。

Pyruns 为 Python 脚本提供基于本地浏览器的图形界面。它的核心思路不是“接管你的工程”，而是尽量贴着你已经在用的工作方式走：

• 继续使用原脚本
• 继续使用原终端 / shell
• 继续使用原 conda 环境与环境变量
• 把任务、配置、日志、备注、运行历史稳稳落在 _pyruns_ 工作区里

无需注册账号 · 无需联网 · 无需数据库 · 所有流程均在本地执行

pip install pyruns
pyr train.py
pyr train.py my_config.yaml
pyr train.py -p 9000
pyruns train.py -p 9000
pyruns train.py -p 9000 --no-browser
pyr

在 tmux、SSH 或无图形界面的服务器里，Pyruns 默认只打印本地 URL，不会自动调用系统浏览器；如需强制打开浏览器，可使用 --browser 或设置 PYRUNS_OPEN_BROWSER=1。

推荐优先从这两条主路径开始：

• pyr train.py
• pyr train.py my_config.yaml

这两条是 Pyruns 最自然、也最应该被用户第一眼看到的接入方式。
pyr 仍然可用，但更适合作为 shell / 命令任务的补充入口。

除了 Generator / Manager / Monitor，现在首页也会先把系统状态、任务概览和 GPU 资源收拢成一个更适合“刚打开就快速判断下一步”的入口。

很多实验工具做得很大，但真正落到日常工作里，最麻烦的问题往往还是这些：

没有 Pyruns 时，你常常要写这种让人头皮发麻的嵌套循环：

for lr in 0.001 0.01 0.1; do
  for bs in 32 64 128; do
    for opt in adam sgd; do
      python train.py --lr $lr --batch_size $bs --optimizer $opt \
        > logs/lr${lr}_bs${bs}_${opt}.log 2>&1 &
    done
  done
done
wait

用了 Pyruns，在 Form 模式里写成这样就够了：

lr: 0.001 | 0.01 | 0.1
batch_size: 32 | 64 | 128
optimizer: adam | sgd

点击生成后，就会自动展开成多组独立任务，每个任务都拥有自己的配置快照、运行目录和日志文件。

“上周那组 lr=0.01 的实验，用的到底是哪个 batch_size？”
“那次 shell 任务跑在什么环境里？”
“日志在哪个目录？”

Pyruns 会为每个任务保存：

• config.yaml 或 config.sh
• task_info.json
• run_logs/runN.log
• 运行时间线、PID、备注、环境信息

这意味着任务不是跑完就散掉，而是会留下完整、可检索、可复用的历史。

多个任务一起跑的时候，最难受的就是终端输出互相穿插。Pyruns 把每个任务的输出都隔离到独立日志文件，并在 Monitor 页面里提供更像真实终端的实时查看体验。

对于 shell 工作流，这点尤其重要：

先用一句话区分：

• script 模式：围绕一个 Python 脚本建立工作区
• shell 模式：围绕一个目录里的命令任务建立工作区

最重要的区别不是页面像不像，而是 Pyruns 正在管理什么：

• script 模式管理的是“脚本 + 配置任务”
• shell 模式管理的是“目录 + 命令任务”

当你打开一个普通 Python 脚本时，Pyruns 会围绕它创建一个独立工作区：

project/
├─ train.py
└─ _pyruns_/
   ├─ _pyruns_settings.yaml
   └─ train/
      ├─ script_info.json
      ├─ config_default.yaml
      └─ tasks/

这一模式适合：

• argparse 脚本
• pyruns.load() / pyruns.read() 风格脚本
• 希望每个任务都带独立 config.yaml 的 Python 任务
• 把参数调优、模板配置、批量生成放在首位的工作流

当你切到 shell 模式时，Pyruns 管理的对象不再是某个 .py 文件，而是一个目录。
也就是说，shell workspace 的起点是“文件夹”，不是“Python 脚本”。

当你切到 shell 模式，工作区会变成：

project/
└─ _pyruns_/
   └─ _shell_/
      ├─ script_info.json
      └─ tasks/

每个 shell 任务落盘为：

_pyruns_/_shell_/tasks/<task_name>/config.sh

最重要的语义是：

• 默认 shell_mode: follow
• 默认跟随启动 pyr 的当前终端
• 当前 Python 进程环境会继续继承给子进程
• 不自动做跨 shell 语法翻译

所以 shell 模式更像是：

• 把原本散落在终端历史里的命令整理成任务
• 把同一目录下的一组命令工作流纳入 Manager / Monitor
• 保留“像在原终端里执行”这件事本身

也就是说，shell task 的目标语义就是：

尽量等价于“在你启动 pyr 的那个终端里，再手动执行一次同样的命令”

如果你的脚本本来就是用 argparse：

pyr train.py

Pyruns 会尝试提取参数定义，生成可编辑表单，并把你在界面里修改后的值再拼回命令行参数。

如果你的脚本通过 pyruns.load() 读取配置：

pyr train.py my_config.yaml

首次运行时，Pyruns 会把这份模板作为 config_default.yaml 保存下来。之后再次运行：

pyr train.py

系统会继续围绕这个工作区进行调参、生成和运行。

如果从 UI Launcher 里选择脚本，规则也一样：argparse 脚本可以直接打开；pyruns.load() 脚本第一次没有 config_default.yaml 时，需要先选择一份 YAML 作为默认模板。之后只要工作区里已有 config_default.yaml，就会直接复用；如果是 argparse 脚本，默认模板会按当前脚本参数重新刷新。

Pyruns 暴露给训练脚本的 API 很少，基本就这几个：

最常见的脚本写法：

import os
import pyruns

cfg = pyruns.load()

for epoch in range(cfg.training.epochs):
    loss = train_one_epoch(cfg)
    pyruns.track(loss=loss)

pyruns.record(final_loss=loss, seed=cfg.training.seed)

artifact_dir = pyruns.artifact_dir()
metrics_path = os.path.join(artifact_dir, "metrics.json")
with open(metrics_path, "w", encoding="utf-8") as f:
    f.write("{}")

如果你在无头服务器上，或者更偏爱命令行操作，可以直接进入 CLI 交互模式：

pyr cli train.py

CLI 和 Web UI 使用同一套磁盘工作区与任务数据，操作结果天然互通。

如果你现在没有固定的 Python 入口脚本，只是想在当前目录直接管理一组命令：

pyr

这会直接创建并打开：

<current_dir>/_pyruns_/_shell_

这条链路尤其适合：

• 命令型实验
• PowerShell / cmd / bash 任务
• 先从 shell 起步，再慢慢沉淀成稳定脚本工作流

仓库中的 examples/ 已经提供了可以直接运行的示例。

目录：

examples/1_argparse_script/

适合展示的页面通常是：

• Generator 表单页
• Manager 中展开后的任务卡片

目录：

examples/2_pyruns_config/

这一类脚本更适合展示：

• 独立 config.yaml 任务快照
• Task Info / Env 等任务详情

Home 是进入工作区后的第一眼总览。
它负责先把“现在这台机器和这份工作区处于什么状态”讲清楚，而不是让你一上来就扎进任务列表。

这一页适合先看：

• 当前任务总览
• 活跃 / 已完成 / 失败的状态分布
• GPU 与系统资源占用
• 接下来该去 Generator、Manager 还是 Monitor

Generator 是参数编辑与任务生成的入口。
这一页要做的不是“展示所有字段”，而是让你在高密度信息里依然能快速找到重点参数、快速生成任务。

你可以在这里做这些事：

• 选择模板
• 用 Form 模式快速调整参数
• 用 YAML 模式编辑完整配置
• 用 Shell 模式直接写命令正文
• 使用 pin 把关键参数固定在视线里
• 预览 batch 展开的结果

Manager 是任务调度台。
这里不只是“看任务”，更是“处理任务”。

它支持：

• 多行搜索
• 状态筛选
• 批量运行 / 删除
• pinned tasks 独立展示
• 任务详情抽屉
• 一键跳转到 Monitor 看日志

Monitor 是运行中任务的观测面。
它承担的是“让日志真正变得可工作”，而不是只把 stdout 放在页面上。

它支持：

• 实时日志流
• 历史日志切换
• 终端复制
• 按任务勾选导出 CSV
• 与 Manager / Task Detail 形成来回联动

工作区配置文件位于：

<project>/_pyruns_/_pyruns_settings.yaml

比较重要的键包括：

• header_refresh_interval
• generator_form_columns
• manager_columns
• manager_execution_mode
• monitor_sidebar_width_pct
• shell_mode
• shell_executable
• python_executable
• conda_env
• conda_executable
• global_env

其中 shell 相关最重要的理解方式是：

• 默认保持 shell_mode: follow
• 只有明确需要固定某个 shell 时，才切到 custom

运行环境切换会同时作用于 Python 任务和 Shell 任务：

conda_env: eval-env
conda_executable: conda

也可以直接指定 Python：

python_executable: /shared/ywl/miniconda3/envs/eval-env/bin/python

global_env 是工作区级别环境变量，覆盖顺序为：终端环境 < global_env < 任务 Env。任务级 Env 里的 PYRUNS_CONDA_ENV、PYRUNS_CONDA_EXE、PYRUNS_PYTHON_EXECUTABLE 会覆盖工作区默认运行环境。

UI 里的 Workspace Env 支持接近 .bashrc 的安全赋值子集：

CUDA_VISIBLE_DEVICES=0
export TOKENIZERS_PARALLELISM=false
HF_HOME="/data/hf cache"

支持单双引号和行首注释；不执行命令替换、变量展开或任意 shell 代码。

直接用 CLI 运行任务时，例如 pyr run 1，会继承当前终端环境；Web UI 的 Runtime / Workspace Env 设置只影响 UI 发起的任务运行。

• 快速开始
• 页面展示
• 界面指南
• 配置说明
• 架构说明
• 批量语法
• CLI 指南

MIT