mcpField
J
jinko-trial

jinko-trial

github.com/novainsilico数据与数据库4161 次安装1 周前更新
代码仓库

关于 jinko-trial

jinko-trial 是面向 Jinkō SDK 用户的试验工作流技能，涵盖创建、检查、运行试验及获取结果。它强调运行前必须进行试验级 sanity 检查，并提供结果分析与下载流程。

主要功能

  1. 01创建试验及简单输出集
  2. 02运行前执行试验级检查
  3. 03运行并轮询试验状态
  4. 04下载时间序列与标量结果
  5. 05汇总、筛选和绘制结果

适用场景

  1. 01根据模型和输入资产建立试验
  2. 02运行前定位试验配置错误
  3. 03获取已完成试验的结果数据

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/novainsilico/jinko-skills --skill jinko-trial

安装后在 Claude Code 中输入/jinko-trial确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

agents/
openai.yaml
evals/
evals.json
references/
trial-plot-data.md
trial-plots.md
trial-results.md
trial-setup.md

详细介绍

Jinkō Trial SDK 工作流

此技能适用于试验设置、健全性检查、运行与轮询，以及下载结果。请使用各自专用的技能创建上游资源：jinko-model、jinko-vpop、jinko-protocol、jinko-data-table 和 jinko-output-set（简单和高级输出集）。

前置条件： 此技能需要已初始化的 jinko-sdk 连接，以及满足其 metadata.requires_sdk 范围要求的 SDK。请运行 jinko-sdk-setup 技能（../jinko-sdk-setup/SKILL.md），并且仅在检查通过后继续。会话代码只能兑换一次，因此在启动此技能自己的 SDK 进程前，请再次调用 get_session_code。如果找不到该技能，请从 novainsilico/jinko-skills 安装。

最小试验

最小试验由以下部分组成：

  • 计算模型。
  • 求解选项；除非明确提供覆盖值，否则使用模型默认值。
  • 简单输出集，即需要保存和可视化的组件时间序列列表。如果用户未指定 ID，请将 model.time_dependent_ids() 用作默认输出 ID。

可选的试验输入：

  • Vpop。
  • 方案设计。
  • 数据表设计。
  • 高级输出集／评分设计。

健全性约束

如果试验健全性检查报告错误，请勿启动。务必通过调用 trial.sanity() 确认这一点，而不是重新运行上游技能中的独立检查（validate_scoring_formula、client.validate_scoring_condition、scoring_design.diagnostics 等）。 这些检查只会单独验证资源，无法判断该资源绑定到此具体试验后会如何表现。trial.sanity() 与 Jinkō UI 在启动前运行的试验上下文检查相同，也是判断是否具备启动条件的权威依据；请参阅 references/trial-setup.md，了解启动前工作流以及“独立验证通过后仍出现错误”的故障排除方法。

试验健全性检查通常会报告以下约束：

  • 计算模型不得存在健全性错误。
  • 方案中的所有描述符都必须对应模型组件。
  • vpop 中的所有描述符都必须对应模型组件。
  • 数据表 obsId 列中的所有描述符都必须对应模型组件。
  • 使用方案时，所有数据表 armScope 值都必须对应方案臂。
  • 高级输出集（评分设计）必须能与此试验的模型输出和简单输出集正确匹配；即使 jinko-output-set 的独立验证已通过，这里仍可能失败（ADVANCED_OUTPUTS_ERRORS）。

如果报告健全性错误，请向用户展示这些错误，并询问他们是否需要帮助修复上游资源。

核心 SDK 方法

  • 创建简单输出集：除非明确指定了输出 ID，否则使用 client.create_simple_output_set(model, model.time_dependent_ids())。有关测量形状和高级输出集（约束／标量／目标），请参阅 jinko-output-set。
  • 创建试验：client.create_trial(model, data_tables=..., vpop=..., protocol=..., simple_output_set=..., advanced_output_set=...)。
  • 创建后编辑求解选项：使用 trial.edit_solving_options({...})，只传入要更改的选项。创建时传入不完整的 solving_* 参数会引发 ValueError。使用 trial.get_solving_options() 查看原始 ISO 8601 时长字符串，或使用 trial.get_solving_options(duration_format="timedelta") 获取 timedelta 值。若要针对特定项进行编辑，可使用 trial.set_solving_times(t_max=timedelta(days=28), t_step="P1D")，两种表示形式均可。
  • 启动前的健全性检查（调用 run() 前必须执行）：trial.sanity() —— 返回原始 dict（JSON 响应，而非类型化对象），其中每个键对应一份组件报告（简单输出集对应 model、protocol、vpop、outputSet；高级输出集对应 scorings；此外还有 dataTables、solvingTimes），每份报告包含 ["sanity"]["errors"]／["sanity"]["warnings"]，以及用于提供各组件详细信息的 ["sanity"]["componentsSanity"]。
  • 运行试验：trial.run()。
  • 轮询：trial.wait_until_completed(timeout=1800)。
  • 发现时间序列：trial.output_ids()。
  • 发现标量和试验组：trial.results.summary()。
  • 在可用时，将时间序列下载为 pandas 格式：trial.results.timeseries({...}).to_dataframe()。
  • 在可用时，将标量下载为 pandas 格式：trial.results.scalars([...]).to_dataframe()。
  • 若没有 pandas，请使用 TabularDownload.raw_bytes；结果载荷可能是 CSV 或 ZIP 格式的 CSV。
  • 计算绘图数据，只读且类型化：trial.results.aggregate_scalars(...)、aggregate_timeseries(...)、tornado_sensitivity(...)、survival_analysis(...)、scalars_per_population(...)（散点图）。筛选器和分组均使用描述符句柄（age.gte(18)、sex.in_levels([...])、auc.group_by_quantiles(4)、sex.group_by_levels()），并可使用 trial.results.group_by_arm()。无需导入 JinkoClient 以外的内容。直接查询试验，不要仅为读取数据而创建 TrialVisualization。每个响应都有一个 to_dataframe() 方法（需要 pandas），可返回整洁格式的数据框。默认情况下，使用 Jinkō 绘图样式绘制数据框（jinko.plotting；需要当前 Python 环境中安装 matplotlib 和 pandas），其样式与 Web 应用中的图表一致：请参阅 references/trial-plots.md。jinko-trial-viz 中的已存储可视化也使用相同的筛选和分组语法进行配置。
  • 忽略 ID 以 __jinko 开头的所有时间序列和标量。这些是平台遥测数据，例如 __jinkoSolvingTime、__jinkoAllocationMiB 和 __jinkoNumSteps。同一试验的任意两次运行之间，这些数据都可能不同，且不具有科学意义，因此在比较结果、报告一致性或计算任何指标前，请先将其排除。

附加数据表时，请通过受支持的 data_tables= 参数传入。创建试验前，必须确认每个数据表报告的 metadata.public.validForFitnessFunction 为 True；若值为 False、缺失或格式错误，则拒绝创建。

项目文件夹规范

  • 优先在专用的 Jinkō 文件夹中创建输出集和试验，而不是放在项目根目录中。工作流开始时，请询问或建议一个文件夹名称，例如 YYYY-MM-DD-<experiment-name>。
  • 尽可能复用名称完全匹配的现有文件夹：client.get_folder_by_name(name, exact_match_only=True)。
  • 如果文件夹不存在，只能在用户确认后创建，或在使用 --apply 运行脚本时创建。
  • 解析出一个文件夹对象或文件夹 ID，然后在创建试验时传入 folder=folder。对于简单输出集，请先创建，再使用 output_set.move_to_folder(folder) 将其移入文件夹。

重试与复用规范

  • 对于一项用户请求，请保留一个命名的本地设置脚本并对其进行更新，而不是创建 run_v2.py、run_v3.py 等类似副本。
  • 当试验或输出集未通过验证时，请先检查并修复现有项目。修复后重新运行 trial.sanity()。
  • 仅当用户要求独立场景、现有项目不可修改或不兼容，或修复会破坏用户要求保留的结果时，才创建新的试验或输出集。创建替代项时，请说明原因。

SDK 脚本

安装 SDK 后，这些脚本会作为控制台脚本出现在 PATH 中，也可以通过 python -m 按如下方式运行。

  • jinko.cli.find_completed_trial_results：列出试验，查找第一个已完成的试验，打印其摘要，并将 TimeSeries 和 Scalar 结果下载到 pandas DataFrame 中。
  • jinko.cli.setup_and_run_trial：创建一个简单的输出集，根据模型和可选资产创建试验，执行健全性检查，可选择运行试验、轮询状态并下载结果。

示例：

python -m jinko.cli.find_completed_trial_results --limit 20 --output-dir trial-results
python -m jinko.cli.setup_and_run_trial --model-sid cm-...
python -m jinko.cli.setup_and_run_trial --model-sid cm-... --output-id Drug
python -m jinko.cli.setup_and_run_trial --model-sid cm-... --output-id Drug --folder 2026-06-15-trial-run --create-folder --apply --run
python -m jinko.cli.setup_and_run_trial --model-sid cm-... --output-id Drug --vpop-sid vp-... --protocol-design-sid pd-... --data-table-sid dt-... --apply --run --download-results

参考资料指引

  • 阅读 references/trial-setup.md，了解试验创建、安全的启动前健全性检查工作流，以及如何排查 ADVANCED_OUTPUTS_ERRORS/"The following advanced outputs have errors"。
  • 阅读 references/trial-results.md，了解如何查找已完成的试验并下载结果。
  • 阅读 references/trial-plots.md，了解如何以 Jinkō 风格将绘图数据绘制为图表：时间序列、标量分布、龙卷风图、生存图和散点图。

评论

支持 Markdown