jinko-output-set

Jinkō 输出集 SDK 工作流

使用此技能通过 SDK 处理输出集：创建、验证、检查简单和高级输出集，并逐步编辑。 试验的关联操作放在 jinko-trial，校准的关联操作放在 jinko-calibration-cmaes，数据表放在 jinko-data-table。

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

核心概念

Jinkō 在 UI、API 和 SDK 中对相同对象使用不同名称。

UI 中的名称	API 项目项类型	SDK 入口点
简单输出集	MeasureDesign	client.create_simple_output_set(...)、SimpleOutputSet
高级输出集	ScoringDesign	client.create_advanced_output_set(...)、AdvancedOutputSet

高级输出集包含三种组件：约束（针对每位患者的布尔资格表达式）、标量（根据模拟输出推导的数值公式）和目标（带权重的范围评分规则）。 标量会序列化到原始 JSON 键 components.measures 下——不要将其与简单输出集中的“测量项”混淆。

发现输出 ID

切勿臆造输出 ID。 创建简单输出集之前，请调用 model.time_dependent_ids() 来发现模型有效的输出 ID，jinko-trial 也是如此。 高级输出集公式通过名称引用输出 ID 或其他标量 ID。 评分公式中的时间值始终以秒为单位，无论模型采用何种时间单位。 公式不支持时间单位注释：请显式转换科学时间。因此，int(X) 和 auc(X) 都包含以秒为单位的时间分量； 请使用 *s 声明其标量单位。 如果不确定某种公式语法是否仍受支持，请使用 client.validate_scoring_formula(...) 验证，不要假设旧示例仍然适用。 在编写任何非简单的约束、标量或目标公式，或组件筛选条件之前，请阅读 references/formula-language.md。其中介绍了实际语法（时间归约函数、时间索引、分组引用），并记录了验证消息。

简单输出集工作流

model = client.get_model("cm-...")
output_set = client.create_simple_output_set(model, model.time_dependent_ids())
# Equivalently: model.create_simple_output_set([...])

测量项可接受输出 ID 字符串（{"timeseriesId": id} 的简写），也可接受用于自定义名称、来源以及时点/跨时间函数的字典。 使用 .content()、.measures、.replace_all_measures()、.add_measures()、.remove_measures()、.update_measure() 进行编辑。 完整架构请参阅 references/simple-output-set.md。

高级输出集工作流

scoring_design = client.create_advanced_output_set(
    constraints=[{"id": "adults", "constraint": "age >= 18"}],
    scalars=[{"id": "auc", "formula": "auc(Drug)", "unit": "mg/L*s"}],
    objectives=[
        {
            "id": "obj_auc",
            "formula": {
                "target": "auc(Drug)",
                "range": {
                    "narrowRangeLowBound": 8.0,
                    "narrowRangeHighBound": 12.0,
                    "wideRangeLowBound": 5.0,
                    "wideRangeHighBound": 15.0,
                },
            },
            "weight": 1.0,
        }
    ],
    name="PK scoring",
)

使用 scoring_design.components.add_constraint(...)、.add_scalar(...)、.add_objective(...) 逐步添加组件——每次调用都会创建一个新的版本快照。批量添加时，请在首次调用前验证每个组件并检查所有 ID 是否冲突；如果后续请求失败，请报告已应用的 ID。 完整架构、组件服务和原始 JSON 备用方案请参阅 references/advanced-output-set.md。

验证与诊断

约束和公式表达式会在 create() 和 components.add_*() 中自动验证。 验证失败时始终会引发 ValidationError——show_validation 仅控制是否打印报告，不会抑制异常。

if scoring_design.diagnostics.errors():
    print(scoring_design.diagnostics.errors().explain())

sd.diagnostics 支持链式调用：.for_kind(...)、.with_severity(...)、.with_code(...)、.for_component(...)、.errors()、.warnings()、.has_errors()、.by_component()、.by_kind()、.by_severity()、.explain()。 使用 sd.diagnostics_at(revision) 获取历史快照。

这些验证会检查什么，不会检查什么。 client.validate_scoring_formula(...)/validate_scoring_condition(...) 和 sd.diagnostics 只会单独检查评分设计——公式语法、引用的 ID 是否能解析为某个对象、约束/目标的结构。 它们不了解任何具体试验。公式可能通过这里的所有检查，但在将高级输出集绑定到试验后仍然失败（例如，它引用了此模型中存在但不在该试验简单输出集中的测量值，或与试验方案的单位/时间窗口不匹配）。 通过独立验证是兼容试验的必要条件，但不是充分条件——切勿仅根据此技能的检查就将高级输出集报告为“可用于试验”。将输出集附加到具体试验后，使用 jinko-trial 的试验 sanity 检查步骤（trial.sanity()）。

附加到试验/校准

此技能仅创建、检查和编辑输出集——不会附加输出集或运行任何内容，也无法确认试验兼容性（见上文）。 对于试验，请使用 jinko-trial：model.create_trial(simple_output_set=..., advanced_output_set=..., ...)，然后在启动前运行 trial.sanity()——参见 jinko-trial 的启动前检查。 对于校准，请使用 jinko-calibration-cmaes 中的 SDK 调用（model.create_calibration(simple_output_set=..., advanced_output_set=..., ...)）。 校准至少需要一个适应度函数来源：validForFitnessFunction: True 的数据表（见 jinko-data-table），和/或包含目标的高级输出集。

SDK 脚本

安装 SDK 后，这些脚本会作为控制台脚本位于 PATH 中，也可以按下方所示通过 python -m 运行。

• jinko.cli.create_simple_output_set：默认执行试运行；使用 --apply 创建简单输出集。
• jinko.cli.create_advanced_output_set：默认执行试运行；使用 --apply 创建高级输出集。
• jinko.cli.inspect_output_set：检查现有的简单或高级输出集。
• jinko.cli.edit_advanced_output_set：向现有高级输出集添加约束/标量/目标。

python -m jinko.cli.create_simple_output_set --model-sid cm-... --output-id Drug
python -m jinko.cli.create_simple_output_set --model-sid cm-... --output-id Drug --folder 2026-07-07-output-sets --create-folder --apply
python -m jinko.cli.create_advanced_output_set --constraint "adults:age >= 18" --scalar "auc:auc(Drug)" --name "PK scoring"
python -m jinko.cli.create_advanced_output_set --from-json skills/jinko-output-set/assets/advanced_output_set_example.json --apply
python -m jinko.cli.inspect_output_set --kind advanced --sid sc-... --diagnostics
python -m jinko.cli.edit_advanced_output_set --sid sc-... --add-objective "obj_auc:auc(Drug):8:12:5:15:1.0" --show-diagnostics --apply

参考资料路由

• 阅读 references/simple-output-set.md，了解测量字典的结构和编辑方法。
• 阅读 references/advanced-output-set.md，了解约束/标量/目标的结构、验证、诊断和标签。
• 阅读 references/formula-language.md，了解约束/标量/目标公式语法（函数、时间索引、臂引用）及其易错之处。