run-cherries-experiments

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Run Cherries Experiments

运行Cherries实验

Workflow

工作流程

Use Cherries as the experiment runner and the run evidence source.

Turn the user's request into an experiment group:

text

exp/<YYYY>/<mm>/<dd>/<group-name>/
├── src/10-<script-name>.py
├── data/
├── logs/
├── tmp/
└── docs/10-<report-name>.md

Use the current local date unless the user gives another date. Use
```
10-
```
for the first script/report in a group, or follow the next numbered local convention when extending an existing group.
Create or modify the script under
```
src/
```
before running it. Keep outputs under Cherries-managed paths instead of ad hoc repo paths.
Run the script with a human-readable
```
CHERRIES_NAME
```
and comma-separated
```
CHERRIES_TAGS
```
.
Wait for the process and Cherries shutdown hooks to finish. Preserve the terminal output; if it is unavailable, inspect
```
logs/*.log
```
and
```
.cherries/runs/**/logs/*.log
```
.
Read the generated
```
data/
```
,
```
tmp/
```
,
```
logs/
```
, and relevant
```
.cherries/runs/
```
snapshot files.
Write the report under
```
docs/
```
with the command, Comet/Cherries summary, observed outputs, analysis, limitations, and reproducibility notes.

将Cherries用作实验运行器和运行证据来源。

将用户的需求转化为一个实验组：

text

exp/<YYYY>/<mm>/<dd>/<group-name>/
├── src/10-<script-name>.py
├── data/
├── logs/
├── tmp/
└── docs/10-<report-name>.md

除非用户指定其他日期，否则使用当前本地日期。组内第一个脚本/报告使用
```
10-
```
前缀，扩展现有组时遵循本地的编号约定。
在运行前创建或修改
```
src/
```
下的脚本。将输出保存在Cherries管理的路径下，而非临时的仓库路径。
使用可读性强的
```
CHERRIES_NAME
```
和逗号分隔的
```
CHERRIES_TAGS
```
运行脚本。
等待进程和Cherries关闭钩子执行完成。保留终端输出；若终端输出不可用，则检查
```
logs/*.log
```
和
```
.cherries/runs/**/logs/*.log
```
。
读取生成的
```
data/
```
、
```
tmp/
```
、
```
logs/
```
以及相关的
```
.cherries/runs/
```
快照文件。
在
```
docs/
```
下编写报告，包含命令、Comet/Cherries摘要、观测到的输出、分析、局限性和可复现性说明。

Script Pattern

脚本模板

Prefer this shape:

python

import logging
from pathlib import Path

from liblaf import cherries

logger = logging.getLogger(__name__)


class Config(cherries.BaseConfig):
    output: Path = cherries.output("result.txt", mkdir=True)
    steps: int = 10


def main(cfg: Config) -> None:
    for step in range(cfg.steps):
        cherries.set_step(step)
        cherries.log_metrics({"train/loss": 1 / (step + 1)})

    cfg.output.write_text("done\n")
    logger.info("Wrote %s", cfg.output)


if __name__ == "__main__":
    cherries.main(main)

Use these Cherries conventions:

Use
```
cherries.BaseConfig
```
for typed settings;
```
cherries.main()
```
instantiates it and logs the model as parameters.
Pass config overrides as kebab-case CLI flags, for example
```
--learning-rate 0.01
```
for a
```
learning_rate
```
field.
Use normal
```
logging
```
for progress and notes; Cherries writes the run log under
```
logs/
```
.
Use
```
cherries.input()
```
for existing inputs under
```
data/
```
; it logs immediately.
Use
```
cherries.output()
```
for outputs under
```
data/
```
and
```
cherries.temp()
```
for temporary artifacts under
```
tmp/
```
; they queue paths and log existing files at run end.

Use

cherries.log_asset()

cherries.log_input()

cherries.log_output()

, or

cherries.log_temp()

only when logging an already-created path outside the helper defaults.

Use
```
cherries.set_step()
```
,
```
cherries.log_metric()
```
, and
```
cherries.log_metrics()
```
for scalar metrics. Nested metric mappings flatten with
```
/
```
, such as
```
train/loss
```
.
Do not hardcode
```
profile="debug"
```
in the script. Select debug/default behavior from the run command.

优先使用以下结构：

python

import logging
from pathlib import Path

from liblaf import cherries

logger = logging.getLogger(__name__)


class Config(cherries.BaseConfig):
    output: Path = cherries.output("result.txt", mkdir=True)
    steps: int = 10


def main(cfg: Config) -> None:
    for step in range(cfg.steps):
        cherries.set_step(step)
        cherries.log_metrics({"train/loss": 1 / (step + 1)})

    cfg.output.write_text("done\n")
    logger.info("Wrote %s", cfg.output)


if __name__ == "__main__":
    cherries.main(main)

遵循以下Cherries约定：

使用
```
cherries.BaseConfig
```
定义类型化配置；
```
cherries.main()
```
会实例化配置并将其作为参数记录。
使用短横线命名的CLI标志覆盖配置，例如针对
```
learning_rate
```
字段使用
```
--learning-rate 0.01
```
。
使用常规
```
logging
```
记录进度和说明；Cherries会将运行日志写入
```
logs/
```
目录。
使用
```
cherries.input()
```
处理
```
data/
```
下的现有输入；它会立即记录该输入。
使用
```
cherries.output()
```
处理
```
data/
```
下的输出，使用
```
cherries.temp()
```
处理
```
tmp/
```
下的临时产物；它们会对路径进行排队，并在运行结束时记录现有文件。
仅当需要记录助手默认路径之外已创建的路径时，才使用
```
cherries.log_asset()
```
、
```
cherries.log_input()
```
、
```
cherries.log_output()
```
或
```
cherries.log_temp()
```
。
使用
```
cherries.set_step()
```
、
```
cherries.log_metric()
```
和
```
cherries.log_metrics()
```
记录标量指标。嵌套的指标映射会通过
```
/
```
展开，例如
```
train/loss
```
。
不要在脚本中硬编码
```
profile="debug"
```
。通过运行命令选择调试/默认行为。

Run Commands

运行命令

Run from the experiment group so Cherries records a readable command and resolves paths below that group:

bash

cd exp/<YYYY>/<mm>/<dd>/<group-name>
CHERRIES_NAME="Human readable run name" CHERRIES_TAGS="tag-a,tag-b" uv run python src/10-<script-name>.py --example-config value

For a quick local smoke run, add

DEBUG=1

to select the debug profile. Debug keeps local snapshots and logs, but disables remote Comet recording and Git commits. For the report-worthy run that should produce the normal Comet.ml summary, omit

DEBUG=1

unless the user asked for a local-only run.

uv run

is unsuitable in the target repo, use the active Python interpreter, but still run the script directly and keep the same environment variables.

从实验组目录运行，以便Cherries记录可读的命令并解析该组下的路径：

bash

cd exp/<YYYY>/<mm>/<dd>/<group-name>
CHERRIES_NAME="Human readable run name" CHERRIES_TAGS="tag-a,tag-b" uv run python src/10-<script-name>.py --example-config value

如需快速本地冒烟测试，添加

DEBUG=1

以选择调试配置。调试模式会保留本地快照和日志，但禁用远程Comet记录和Git提交。如需生成可用于报告的正常Comet.ml摘要运行，除非用户要求仅本地运行，否则不要添加

DEBUG=1

。

若目标仓库中不适合使用

uv run

，则使用当前激活的Python解释器，但仍需直接运行脚本并保持相同的环境变量。

Inspect Results

检查结果

After the run exits:

Confirm expected outputs exist under
```
data/
```
and temporary artifacts under
```
tmp/
```
.
Read
```
logs/10-<script-name>.log
```
; also inspect
```
.cherries/runs/
```
when local snapshots contain copied source, logs, or assets needed for the report.
Use actual generated files as evidence. Do not rely only on terminal summaries when artifacts are available.
If the process appears idle near Comet shutdown, verify whether files and logs have already been written before deciding the run failed.

运行结束后：

确认预期输出存在于
```
data/
```
下，临时产物存在于
```
tmp/
```
下。
读取
```
logs/10-<script-name>.log
```
；当本地快照包含报告所需的复制源代码、日志或资产时，同时检查
```
.cherries/runs/
```
目录。
使用实际生成的文件作为证据。当有产物可用时，不要仅依赖终端摘要。
若进程在Comet关闭阶段看似处于空闲状态，在判定运行失败前，先验证文件和日志是否已写入。

Report

报告

Write the report at:

text

exp/<YYYY>/<mm>/<dd>/<group-name>/docs/10-<report-name>.md

Include these sections when applicable:

Purpose: what the experiment tested and why.
Command: exact working directory, environment variables, script command, and important CLI overrides.
Summary: the
```
Comet.ml Experiment Summary
```
block from terminal output or logs when present; include any Cherries metadata such as name, tags, entrypoint, experiment directory, Git SHA, and Comet URL.
Outputs and assets: generated files, tables, plots, model artifacts, logs, and where they live.
Results: metrics, qualitative observations, and comparisons with baselines or expectations.
Analysis: interpretation, anomalies, failure modes, limitations, and what evidence supports the conclusion.
Reproducibility: current git state when relevant, dependency/runtime notes, random seeds, and follow-up experiments.

Write the report after reading the assets and logs, not from the intended design alone.

在以下路径编写报告：

text

exp/<YYYY>/<mm>/<dd>/<group-name>/docs/10-<report-name>.md

适当时包含以下章节：

目的：实验测试的内容及原因。
命令：确切的工作目录、环境变量、脚本命令和重要的CLI覆盖参数。
摘要：终端输出或日志中的
```
Comet.ml Experiment Summary
```
块（若存在）；包含所有Cherries元数据，如名称、标签、入口点、实验目录、Git SHA和Comet URL。
输出与资产：生成的文件、表格、图表、模型产物、日志及其存储位置。
结果：指标、定性观测结果，以及与基线或预期结果的对比。
分析：解释、异常、失败模式、局限性，以及支持结论的证据。
可复现性：相关的当前Git状态、依赖/运行时说明、随机种子，以及后续实验建议。

需在读取资产和日志后再编写报告，不能仅基于预期设计撰写。