From efbcd78ced94463b07604fc8124fa0728a10b3aa Mon Sep 17 00:00:00 2001 From: njzjz-bot Date: Mon, 24 Aug 2026 04:04:44 +0800 Subject: [PATCH] docs: explain runtime package signature skew Clarify that optional_parameter is internal and document version alignment through upload_python_packages. Coding-Agent: Codex Codex-Version: codex-cli 0.149.1 Model: gpt-5.6-sol Reasoning-Effort: xhigh --- docs/quickcli.md | 14 ++++++++++++++ dpgen2/entrypoint/args.py | 6 +++++- 2 files changed, 19 insertions(+), 1 deletion(-) diff --git a/docs/quickcli.md b/docs/quickcli.md index e9003715..cc58ba5b 100644 --- a/docs/quickcli.md +++ b/docs/quickcli.md @@ -73,3 +73,17 @@ If a workflow stopped abnormally, one may submit a new workflow with some steps dpgen2 resubmit input.json WFID --reuse 0-41 ``` The steps of workflow WDID 0-41 (0<=id<41, note that 41 is not included) will be reused in the new workflow. The indexes of the steps are printed by `dpgen2 showkey`. In the example, all the steps before the `iter-000001--run-fp-000000` will be used in the new workflow. + +## Troubleshoot an `optional_parameter` KeyError + +`optional_parameter` is an internal parameter passed between DPGEN2 workflow operators; it is not a field users should add to the input file. A runtime `KeyError: optional_parameter` normally means the code that submitted the workflow and the DPGEN2 package inside the runtime image define different operator signatures. + +Use the same DPGEN2 release in both environments. During local development, the most reliable option is to upload the exact checkout used for submission: + +```json +{ + "upload_python_packages": ["/absolute/path/to/dpgen2"] +} +``` + +The path must be visible on the submission machine and should contain the `dpgen2` package. For production images, install the same pinned DPGEN2 version instead. Resubmit the workflow after aligning the versions because already generated operator scripts retain the old signature. diff --git a/dpgen2/entrypoint/args.py b/dpgen2/entrypoint/args.py index df11ff7f..37f385b6 100644 --- a/dpgen2/entrypoint/args.py +++ b/dpgen2/entrypoint/args.py @@ -810,7 +810,11 @@ def dpgen_step_config_args(default_config): def submit_args(default_step_config=normalize_step_dict({})): doc_bohrium_config = "Configurations for the Bohrium platform." doc_step_configs = "Configurations for executing dflow steps" - doc_upload_python_packages = "Upload python package, for debug purpose" + doc_upload_python_packages = ( + "Local Python package directories uploaded with every dflow Python " + "operator. Use this to keep the runtime DPGEN2 code identical to the " + "submission environment when the remote image contains another version." + ) doc_inputs = "The input parameter and artifacts for dpgen2" doc_train = "The configuration for training" doc_explore = "The configuration for exploration"