Palantir Foundry中@transform未识别ctx参数致参数缺失报错问题

出现这个问题的核心是**@transform装饰器未被框架正确识别**，导致你的函数被当作普通Python函数执行，而不是框架托管的转换任务——框架本应自动注入ctx、输入输出这些参数，现在却要求你手动传入，所以会提示缺少必需位置参数。

常见原因及对应解决方法：

1. 装饰器导入或应用错误 #

• 你可能没正确导入框架的@transform装饰器，或者把它和其他装饰器（比如@task）搞混了。比如在Flytekit中，必须从flytekit包导入：

  from flytekit import transform
  

• 检查函数上方是否正确加了@transform，不要漏写@符号，也不要画蛇添足加括号（比如写成@transform()，多数框架的@transform不需要括号）。

2. 函数参数定义不符合规范 #

框架对@transform函数的参数顺序和注解有严格要求，错了就会识别失败：

• 第一个参数必须是上下文对象（比如Flyte中的Context），要明确标注类型：ctx: Context
• 输入参数必须用Input[...]注解，输出参数必须用Output[...]注解
• 参数顺序要遵循：ctx → 输入参数 → 输出参数

正确的参数定义示例：

from flytekit import transform, Input, Output, Context
from flytekit.types.dataset import Dataset

@transform
def split_data(
    ctx: Context,
    input_ds: Input[Dataset],
    o1: Output[Dataset],
    o2: Output[Dataset]
):
    # 读取输入数据集
    df = input_ds.open().all()
    # 拆分逻辑示例：按行拆分
    split_idx = len(df) // 2
    df1 = df[:split_idx]
    df2 = df[split_idx:]
    # 写入输出数据集
    o1.write(df1)
    o2.write(df2)

3. 多输出声明方式错误 #

如果你期望生成o1和o2两个输出，不能用普通函数的return返回多个值——@transform任务需要通过显式的Output参数来写入结果，而不是return。如果用return返回，框架无法识别输出参数，会导致装饰器失效。

4. 框架版本兼容性问题 #

部分旧版本的框架（比如早期Flytekit）对@transform的语法要求不同，比如需要在装饰器中显式声明输入输出：

@transform(
    inputs={"input_ds": Input[Dataset]},
    outputs={"o1": Output[Dataset], "o2": Output[Dataset]}
)
def split_data(ctx: Context, input_ds):
    df = input_ds.open().all()
    split_idx = len(df) // 2
    ctx.outputs["o1"].write(df[:split_idx])
    ctx.outputs["o2"].write(df[split_idx:])

如果你用了新版本框架却写了旧版本语法，也会导致装饰器无法正确识别函数。

内容的提问来源于stack exchange，提问作者Greg Werner