marimo-batch

Pydantic 是宣告批次工作事實來源的好方法，特別是在機器學習中。你可以宣告類似這樣的內容：

from pydantic import BaseModel, Field

class ModelParams(BaseModel):
    sample_size: int = Field(
        default=1024 * 4, description="每個 epoch 的訓練樣本數。"
    )
    learning_rate: float = Field(default=0.01, description="最佳化器的學習率。")

你也可以用兩種方式填入這些模型參數，例如在 UI 中建立表單。

el = mo.md("""
{sample_size} 
{learning_rate}
""").batch(
    sample_size=mo.ui.slider(1024, 1024 * 10, value=1024 * 4, step=1024, label="樣本數"),
    learning_rate=mo.ui.slider(0.001, 0.1, value=0.01, step=0.001, label="學習率"),
).form()
el

但也可以使用 marimo 的命令列介面。

if mo.app_meta().mode == "script":
    if "help" in mo.cli_args() or len(cli_args) == 0:
        print("用法: uv run git_archaeology.py --repo <網址> [--samples <n>]")
        print()
        for name, field in ModelParams.model_fields.items():
            default = f" (預設: {field.default})" if field.default is not None else " (必填)"
            print(f"  --{name:12s} {field.description}{default}")
        exit()
    model_params = ModelParams(
        **{k.replace("-", "_"): v for k, v in mo.cli_args().items()
    })
else: 
    model_params = ModelParams(**el.value)

使用者現在可以透過命令列執行：

uv run notebook.py --sample-size 4096 --learning-rate 0.005

這是最好的雙贏局面，你可以使用 UI 進行測試和迭代，然後使用命令列執行批次工作。另一個好處是，你可以用快速執行的設定來執行筆記本，檢查是否有錯誤。

使用者希望能夠使用這種模式執行筆記本，所以請務必詢問使用者想要透過命令列設定哪些參數，然後對筆記本進行修改。在修改之前，請務必與使用者確認變更。

Weights and Biases

使用者可能對加入 Weights and Biases 支援有興趣。請務必確認是否為是/否。如果是，請確保這些 ModelParams 被記錄下來。你也需要確保 wandb_project 和 wandb_run_name 是 ModelParams 的一部分，如果使用者想要走這條路的話。

如果使用者想要開始機器學習的訓練工作，請務必使用這個起點。請確保保留此筆記本中的欄位！

環境變數

你可能需要讀取工作的環境變數。使用 python-dotenv 來讀取 .env 檔案（如果存在），但也加入一個 EnvConfig，讓使用者可以在 UI 中手動加入金鑰。

from wigglystuff import EnvConfig

# 帶有驗證器
config = EnvConfig({
    "OPENAI_API_KEY": lambda k: openai.Client(api_key=k).models.list(),
    "WANDB_API_KEY": lambda k: wandb.login(key=k, verify=True)
})

# 阻塞直到有效，適用於需要金鑰的儲存格
config.require_valid()

# 存取值
config["OPENAI_API_KEY"]
config.get("OPENAI_API_KEY", "some default")

請確保將這個 EnvConfig 加入筆記本的頂端。

欄位

較大的 marimo 筆記本通常會使用欄位功能來方便導覽。如果是這種情況，你必須保留這些欄位！

@app.cell(column=0, hide_code=True)
def _(mo):
    mo.md(r"""demo""")

運算平台

當工作準備好要進行大量運算時，務必記住良好的實務做法。考慮資料集的批次大小，並確保有足夠的日誌，讓使用者能夠發現問題。

網格搜尋

當使用者想要執行超參數搜尋時，請引導他們使用這個網格啟動器。它可以直接與 references/starting-point.py 中的筆記本搭配使用：它從符合筆記本 ModelParams 欄位的搜尋空間中隨機取樣組合，並將每個組合作為獨立工作啟動。

預設情況下，腳本會進行乾執行（uv run grid.py），讓使用者可以在花費運算資源前檢查組合。傳遞 --launch 來實際提交工作。--count 和 --seed 旗標控制要取樣的組合數量和亂數種子。

參考範例使用 Hugging Face Jobs 作為運算提供者，但這只是一個選項。使用者可以將其替換為 Modal、RunPod 或任何其他可以執行 uv 腳本的提供者。