truefoundry-workflows

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Routing note: For ambiguous user intents, use the shared clarification templates in references/intent-clarification.md.

路由说明：如果用户意图不明确，请使用references/intent-clarification.md中的通用澄清模板。

TrueFoundry Workflows

Create, configure, and deploy workflows on TrueFoundry. Workflows are built on Flyte, an open-source orchestration platform, and use Python decorators (

@task

@workflow

) to define structured sequences of tasks as directed acyclic graphs (DAGs).

Workflow definition uses Python SDK (

@task

@workflow

decorators). Workflow deployment uses

tfy deploy workflow

CLI command. Alternative:

tfy apply

with a YAML manifest. REST API fallback when CLI unavailable.

在TrueFoundry上创建、配置和部署工作流。工作流基于开源编排平台Flyte构建，使用Python装饰器（

@task

、

@workflow

）将结构化的任务序列定义为有向无环图（DAG）。

工作流定义使用Python SDK（

@task

@workflow

装饰器）实现。工作流部署使用

tfy deploy workflow

CLI命令，也可选择搭配YAML清单使用

tfy apply

，CLI不可用时可降级使用REST API。

When to Use

适用场景

User wants to create a data processing or ML training pipeline
User says "create a workflow", "deploy a workflow", "run a pipeline"
User wants to schedule recurring batch operations (cron workflows)
User wants to orchestrate multi-step tasks: ETL, feature engineering, model training, batch inference
User asks about Flyte tasks, map tasks, conditional tasks, or Spark tasks on TrueFoundry

用户需要创建数据处理或ML训练流水线
用户提及「创建工作流」、「部署工作流」、「运行流水线」
用户需要调度周期性批量操作（cron工作流）
用户需要编排多步骤任务：ETL、特征工程、模型训练、批量推理
用户询问TrueFoundry上的Flyte任务、map任务、条件任务或Spark任务相关问题

When NOT to Use

不适用场景

User wants to deploy a web service or API -> prefer
```
deploy
```
skill; ask if the user wants another valid path
User wants to deploy a one-off job (not a multi-step pipeline) -> prefer
```
deploy
```
skill; ask if the user wants another valid path with job type
User wants to check running applications -> prefer
```
applications
```
skill; ask if the user wants another valid path
User wants to monitor job runs -> prefer
```
jobs
```
skill; ask if the user wants another valid path
User wants to serve an ML model behind an endpoint -> prefer
```
llm-deploy
```
or
```
deploy
```
; ask which path they want

</objective> <context>

用户需要部署Web服务或API -> 优先使用
```
deploy
```
技能，询问用户是否需要其他可行路径
用户需要部署一次性任务（非多步骤流水线） -> 优先使用
```
deploy
```
技能，询问用户是否需要其他任务类型的可行路径
用户需要查看运行中的应用 -> 优先使用
```
applications
```
技能，询问用户是否需要其他可行路径
用户需要监控任务运行情况 -> 优先使用
```
jobs
```
技能，询问用户是否需要其他可行路径
用户需要将ML模型部署为可访问的端点 -> 优先使用
```
llm-deploy
```
或
```
deploy
```
，询问用户想要哪种路径

</objective> <context>

Prerequisites

前置要求

Always verify before creating a workflow:

Credentials —
```
TFY_BASE_URL
```
and
```
TFY_API_KEY
```
must be set (env or
```
.env
```
)
Workspace —
```
TFY_WORKSPACE_FQN
```
required. Never auto-pick. Ask the user if missing.
SDK — Install the TrueFoundry SDK with workflow extras (required for defining tasks/workflows):
bash
```
pip install "truefoundry[workflow]"
```
CLI login — Authenticate the CLI (required for deployment):
bash
```
tfy login --host "$TFY_BASE_URL"
```
Python — Python 3.9+ required for workflow definition code
Cluster setup — The Flyte data plane must be installed on the target cluster. The control plane ships with TrueFoundry (no additional setup). If the user gets errors about Flyte not being available, they need to contact their platform admin to install the data plane components.

For credential check commands and .env setup, see

references/prerequisites.md

创建工作流前必须先核验以下条件：

凭证 — 必须配置
```
TFY_BASE_URL
```
和
```
TFY_API_KEY
```
（环境变量或
```
.env
```
文件）
工作区 — 需要
```
TFY_WORKSPACE_FQN
```
，绝对不要自动选择，缺失时请询问用户。
SDK — 安装带工作流扩展的TrueFoundry SDK（定义任务/工作流必需）：
bash
```
pip install "truefoundry[workflow]"
```
CLI登录 — 完成CLI身份认证（部署必需）：
bash
```
tfy login --host "$TFY_BASE_URL"
```
Python版本 — 工作流定义代码要求Python 3.9+
集群配置 — 目标集群上必须安装Flyte数据平面，控制平面随TrueFoundry内置（无需额外配置）。如果用户收到Flyte不可用的错误，需要联系平台管理员在目标集群安装数据平面组件。

凭证检查命令和.env配置方法请查看

references/prerequisites.md

。

CLI Detection

CLI版本检测

bash

tfy --version

CLI Output	Status	Action
`tfy version X.Y.Z` (>= 0.5.0)	Current	Use `tfy apply` for deployment as documented below.
`tfy version X.Y.Z` (0.3.x-0.4.x)	Outdated	Upgrade: install a pinned version (e.g. `pip install 'truefoundry==0.5.0'` ). Core `tfy apply` should still work.
Command not found	Not installed	Install: `pip install 'truefoundry==0.5.0' && tfy login --host "$TFY_BASE_URL"`
CLI unavailable (no pip/Python)	Fallback	Use REST API via `tfy-api.sh` . See `references/cli-fallback.md` .

bash

tfy --version

CLI输出	状态	操作
`tfy version X.Y.Z` (>= 0.5.0)	版本正常	按下文文档使用 `tfy apply` 进行部署。
`tfy version X.Y.Z` (0.3.x-0.4.x)	版本过旧	升级：安装指定版本（例如 `pip install 'truefoundry==0.5.0'` ），核心 `tfy apply` 功能仍可正常使用。
命令未找到	未安装	安装： `pip install 'truefoundry==0.5.0' && tfy login --host "$TFY_BASE_URL"`
CLI不可用（无pip/Python）	降级方案	通过 `tfy-api.sh` 使用REST API，详情查看 `references/cli-fallback.md` 。

Core Concepts

核心概念

Task -- The smallest unit of execution. A Python function decorated with
```
@task
```
. Each task runs in its own container with configurable resources and dependencies.
Workflow -- A composition of tasks arranged as a DAG using the
```
@workflow
```
decorator. Defines execution order and data flow between tasks.
Task Config -- Specifies the container image, Python version, pip packages, and compute resources for each task.
Execution Config -- Controls scheduling (cron), launch plans, and runtime parameters.

Critical rule: The workflow function must contain only task calls and control flow. Do not put business logic directly in the workflow function -- all computation must live inside

@task

functions.

</context> <instructions>

Task -- 最小执行单元，是被
```
@task
```
装饰的Python函数，每个任务在独立的容器中运行，支持配置资源和依赖。
Workflow -- 由多个任务通过
```
@workflow
```
装饰器编排为DAG的组合，定义任务的执行顺序和数据流转规则。
Task Config -- 为每个任务指定容器镜像、Python版本、pip包和计算资源。
Execution Config -- 控制调度规则（cron）、启动计划和运行时参数。

关键规则： 工作流函数中只能包含任务调用和控制流逻辑，不要直接在工作流函数中编写业务逻辑——所有计算逻辑必须放在

@task

装饰的函数内。

</context> <instructions>

Basic Workflow Example

基础工作流示例

python

from truefoundry.workflow import (
    PythonTaskConfig,
    TaskPythonBuild,
    conditional,
    task,
    workflow,
)
from truefoundry.deploy import Resources

python

from truefoundry.workflow import (
    PythonTaskConfig,
    TaskPythonBuild,
    conditional,
    task,
    workflow,
)
from truefoundry.deploy import Resources

Define task configuration

定义任务配置

cpu_task_config = PythonTaskConfig( image=TaskPythonBuild( python_version="3.9", pip_packages=["truefoundry[workflow]"], ), resources=Resources(cpu_request=0.5, memory_request=500), )

@task(task_config=cpu_task_config) def fetch_data(source: str) -> dict: """Fetch and return raw data.""" data = {"records": 1000, "source": source} return data

@task(task_config=cpu_task_config) def process_data(raw_data: dict) -> dict: """Clean and transform the data.""" processed = { "records": raw_data["records"], "source": raw_data["source"], "status": "processed", } return processed

@task(task_config=cpu_task_config) def train_model(data: dict) -> str: """Train a model on processed data.""" return f"model_trained_on_{data['records']}_records"

@workflow def ml_pipeline(source: str = "default") -> str: """End-to-end ML pipeline.""" raw = fetch_data(source=source) processed = process_data(raw_data=raw) result = train_model(data=processed) return result


**Note:** Workflows REQUIRE the Python SDK for definition -- this is the exception to the CLI-first approach. Only the deploy step uses CLI.

cpu_task_config = PythonTaskConfig( image=TaskPythonBuild( python_version="3.9", pip_packages=["truefoundry[workflow]"], ), resources=Resources(cpu_request=0.5, memory_request=500), )

@task(task_config=cpu_task_config) def fetch_data(source: str) -> dict: """拉取并返回原始数据。""" data = {"records": 1000, "source": source} return data

@task(task_config=cpu_task_config) def process_data(raw_data: dict) -> dict: """清洗并转换数据。""" processed = { "records": raw_data["records"], "source": raw_data["source"], "status": "processed", } return processed

@task(task_config=cpu_task_config) def train_model(data: dict) -> str: """基于处理后的数据训练模型。""" return f"model_trained_on_{data['records']}_records"

@workflow def ml_pipeline(source: str = "default") -> str: """端到端ML流水线。""" raw = fetch_data(source=source) processed = process_data(raw_data=raw) result = train_model(data=processed) return result


**注意：** 工作流定义必须使用Python SDK——这是CLI优先原则的例外情况，仅部署步骤使用CLI。

Task Configuration

任务配置

PythonTaskConfig

Every task needs a

PythonTaskConfig

that defines its execution environment:

python

from truefoundry.workflow import PythonTaskConfig, TaskPythonBuild
from truefoundry.deploy import Resources

每个任务都需要

PythonTaskConfig

来定义执行环境：

python

from truefoundry.workflow import PythonTaskConfig, TaskPythonBuild
from truefoundry.deploy import Resources

CPU task

CPU任务

cpu_task_config = PythonTaskConfig( image=TaskPythonBuild( python_version="3.9", pip_packages=[ "truefoundry[workflow]", "pandas==2.1.0", "numpy", ], # Or use a requirements file: # requirements_path="requirements.txt", ), resources=Resources( cpu_request=0.5, memory_request=500, ), )

cpu_task_config = PythonTaskConfig( image=TaskPythonBuild( python_version="3.9", pip_packages=[ "truefoundry[workflow]", "pandas==2.1.0", "numpy", ], # 也可使用依赖文件： # requirements_path="requirements.txt", ), resources=Resources( cpu_request=0.5, memory_request=500, ), )

GPU task (for training or inference steps)

GPU任务（用于训练或推理步骤）

gpu_task_config = PythonTaskConfig( image=TaskPythonBuild( python_version="3.9", pip_packages=[ "truefoundry[workflow]", "torch", "transformers", ], ), resources=Resources( cpu_request=2.0, cpu_limit=4.0, memory_request=8192, memory_limit=16384, devices=[ GPUDevice(name="T4", count=1), ], ), )


**Key points:**
- `truefoundry[workflow]` must always be in `pip_packages` (or in the requirements file)
- `pip_packages` takes a list of pip-installable package specifiers
- `requirements_path` can point to a requirements file instead of inline packages
- Resource `memory_request` and `memory_limit` are in MB
- Different tasks can have different configs (e.g., lightweight preprocessing vs GPU-heavy training)


**核心要点：**
- `truefoundry[workflow]`必须始终包含在`pip_packages`中（或依赖文件中）
- `pip_packages`接受pip可安装的包规范列表
- 可以使用`requirements_path`指定依赖文件路径，代替内联的包列表
- 资源配置中的`memory_request`和`memory_limit`单位为MB
- 不同任务可以使用不同配置（例如轻量预处理任务和GPU密集型训练任务）

Container Tasks

容器任务

For tasks that need a pre-built Docker image instead of a Python build:

python

from truefoundry.workflow import task, ContainerTask

container_task = ContainerTask(
    name="my-container-task",
    image="my-registry/my-image:latest",
    command=["python", "run.py"],
    resources=Resources(
        cpu_request=1.0,
        memory_request=2048,
    ),
)

Use container tasks when:

You need a custom base image with system-level dependencies
The task runs non-Python code
You have a pre-built image with all dependencies baked in

Security: Verify container image sources before using them in workflow tasks. Pin image tags to specific versions — do not use
:latest
. For
pip_packages
, pin package versions to avoid supply-chain risks from unvetted upstream changes.

如果任务需要使用预构建的Docker镜像而非Python构建，可以使用容器任务：

python

from truefoundry.workflow import task, ContainerTask

container_task = ContainerTask(
    name="my-container-task",
    image="my-registry/my-image:latest",
    command=["python", "run.py"],
    resources=Resources(
        cpu_request=1.0,
        memory_request=2048,
    ),
)

容器任务适用场景：

需要带有系统级依赖的自定义基础镜像
任务运行非Python代码
已经有预构建好所有依赖的镜像

安全提示： 在工作流任务中使用容器镜像前请核验来源，镜像标签需指定具体版本——不要使用
:latest
。
pip_packages
也请固定包版本，避免未经审核的上游变更带来供应链风险。

Cron Workflows (Scheduling)

Cron工作流（定时调度）

Schedule workflows to run at fixed intervals using cron syntax. The schedule is always in UTC timezone.

python

from truefoundry.workflow import workflow, ExecutionConfig

@workflow(
    execution_configs=[
        ExecutionConfig(schedule="0 6 * * *"),  # Every day at 6:00 AM UTC
    ]
)
def daily_etl_pipeline() -> str:
    raw = fetch_data(source="production_db")
    processed = process_data(raw_data=raw)
    return processed["status"]

使用cron语法调度工作流按固定间隔运行，调度时间始终使用UTC时区。

python

from truefoundry.workflow import workflow, ExecutionConfig

@workflow(
    execution_configs=[
        ExecutionConfig(schedule="0 6 * * *"),  # 每天UTC时间早上6点
    ]
)
def daily_etl_pipeline() -> str:
    raw = fetch_data(source="production_db")
    processed = process_data(raw_data=raw)
    return processed["status"]

Common Cron Patterns

常用Cron规则

Schedule	Cron Expression	Description
Every 10 minutes	`/10 * * *`	Frequent data sync
Every hour	`0 * * * *`	Hourly aggregation
Daily at midnight UTC	`0 0 * * *`	Nightly batch jobs
Daily at 6 AM UTC	`0 6 * * *`	Morning data refresh
Every Monday at 9 AM UTC	`0 9 * * 1`	Weekly reports
First of month at midnight	`0 0 1 * *`	Monthly processing

Cron format:

minute hour day-of-month month day-of-week

调度规则	Cron表达式	说明
每10分钟	`/10 * * *`	高频数据同步
每小时	`0 * * * *`	每小时聚合
每天UTC零点	`0 0 * * *`	夜间批量任务
每天UTC早上6点	`0 6 * * *`	晨间数据刷新
每周一UTC早上9点	`0 9 * * 1`	周度报表
每月1号UTC零点	`0 0 1 * *`	月度处理

Cron格式：

分钟 小时 日期 月份 星期

Advanced Patterns

高级模式

For map tasks (parallel execution), conditional tasks (branching logic), and Spark tasks (large-scale data processing), see references/workflow-advanced-patterns.md.

关于map任务（并行执行）、条件任务（分支逻辑）和Spark任务（大规模数据处理）的使用方法，请查看references/workflow-advanced-patterns.md。

Deploying Workflows

部署工作流

After the user writes their workflow code (Python file with

@task

and

@workflow

decorators), deploy using

tfy deploy workflow

用户编写好工作流代码（包含

@task

和

@workflow

装饰器的Python文件）后，使用

tfy deploy workflow

进行部署。

Approach A: Via

tfy deploy workflow

(CLI -- Primary)

方案A：通过

tfy deploy workflow

（CLI——首选方式）

bash

tfy deploy workflow \
  --name my-ml-pipeline \
  --file workflow.py \
  --workspace_fqn "$TFY_WORKSPACE_FQN"

Important: After deployment, the workflow must be triggered manually. The TrueFoundry UI shows a yellow banner indicating the workflow is deployed but not yet running. The user can trigger it from the dashboard or via a launch plan.

bash

tfy deploy workflow \
  --name my-ml-pipeline \
  --file workflow.py \
  --workspace_fqn "$TFY_WORKSPACE_FQN"

重要提示： 部署完成后需要手动触发工作流，TrueFoundry UI会显示黄色横幅提示工作流已部署但尚未运行，用户可以从控制台触发或通过启动计划触发。

Approach B: Via

tfy apply

(YAML Manifest -- Alternative)

方案B：通过

tfy apply

（YAML清单——替代方式）

1. Generate the workflow deployment manifest:

yaml

undefined

1. 生成工作流部署清单：

yaml

undefined

workflow-manifest.yaml

name: my-ml-pipeline type: workflow workflow_file: workflow.py workspace_fqn: "YOUR_WORKSPACE_FQN"


**2. Preview:**

```bash
tfy apply -f workflow-manifest.yaml --dry-run --show-diff

3. Apply:

bash

tfy apply -f workflow-manifest.yaml

name: my-ml-pipeline type: workflow workflow_file: workflow.py workspace_fqn: "YOUR_WORKSPACE_FQN"


**2. 预览变更：**

```bash
tfy apply -f workflow-manifest.yaml --dry-run --show-diff

3. 执行部署：

bash

tfy apply -f workflow-manifest.yaml

Approach C: Via Python SDK

方案C：通过Python SDK

python

from truefoundry.workflow import WorkflowDeployment

deployment = WorkflowDeployment(
    name="my-ml-pipeline",
    workflow_file="workflow.py",
    workspace_fqn="your-workspace-fqn",
)
deployment.deploy()

python

from truefoundry.workflow import WorkflowDeployment

deployment = WorkflowDeployment(
    name="my-ml-pipeline",
    workflow_file="workflow.py",
    workspace_fqn="your-workspace-fqn",
)
deployment.deploy()

Deployment Checklist

部署检查清单

Before deploying, confirm with the user:

Workflow name -- a descriptive name for the workflow
Workspace --
```
TFY_WORKSPACE_FQN
```
is set (never auto-pick)
Task configs -- each task has appropriate resources, Python version, and packages
Pip packages --
```
truefoundry[workflow]
```
is included in every task's packages
Schedule -- if cron, confirm the cron expression and timezone (always UTC)
Workflow file -- path to the Python file containing
```
@workflow
```
and
```
@task
```
definitions

Post-deploy: Remind the user that the workflow must be triggered manually after deployment. The TrueFoundry dashboard shows a yellow banner for newly deployed workflows that have not been triggered yet.

部署前请与用户确认以下内容：

工作流名称 — 工作流的描述性名称
工作区 — 已配置
```
TFY_WORKSPACE_FQN
```
（绝对不要自动选择）
任务配置 — 每个任务都有合适的资源、Python版本和依赖包
Pip依赖 — 每个任务的依赖包中都包含
```
truefoundry[workflow]
```
调度规则 — 如果使用cron，确认cron表达式和时区（始终为UTC）
工作流文件 — 包含
```
@workflow
```
和
```
@task
```
定义的Python文件路径正确

部署后： 提醒用户部署完成后需要手动触发工作流，TrueFoundry控制台会为已部署但尚未触发的新工作流显示黄色横幅。

Monitoring Workflow Runs

监控工作流运行

After deployment, monitor runs through:

TrueFoundry Dashboard -- Navigate to Workflows in the dashboard to see run history, task status, logs, and DAG visualization.

Applications skill -- Use the

applications

skill to list workflow applications:

tfy_applications_list(filters={"application_type": "workflow"})

Jobs skill -- Use the
```
jobs
```
skill to inspect individual workflow run details and status.

部署完成后可以通过以下方式监控运行情况：

TrueFoundry控制台 — 进入工作流页面查看运行历史、任务状态、日志和DAG可视化

Applications技能 — 使用

applications

技能列出工作流应用：

tfy_applications_list(filters={"application_type": "workflow"})

Jobs技能 — 使用
```
jobs
```
技能查看单个工作流运行的详情和状态

Run States

运行状态

State	Meaning
QUEUED	Run is waiting to be scheduled
RUNNING	Tasks are actively executing
SUCCEEDED	All tasks completed successfully
FAILED	One or more tasks failed
TIMED_OUT	Run exceeded its timeout
ABORTED	Run was manually cancelled

</instructions>

<success_criteria>

The user has a workflow file with properly decorated @task and @workflow functions
The agent has confirmed that all @task functions include truefoundry[workflow] in their pip_packages
The workflow was successfully deployed to the specified workspace using
```
tfy deploy workflow
```
(or
```
tfy apply
```
as alternative)
The user can monitor workflow runs via the dashboard or
```
applications
```
skill
The agent has set up a cron schedule if the user requested recurring execution

</success_criteria>

状态	含义
QUEUED	运行任务等待调度中
RUNNING	任务正在执行
SUCCEEDED	所有任务执行成功
FAILED	一个或多个任务执行失败
TIMED_OUT	运行超出超时时间
ABORTED	运行被手动取消

</instructions>

<success_criteria>

用户拥有包含正确装饰的@task和@workflow函数的工作流文件
Agent已确认所有@task函数的pip_packages中都包含truefoundry[workflow]
工作流已通过
```
tfy deploy workflow
```
（或替代方案
```
tfy apply
```
）成功部署到指定工作区
用户可以通过控制台或
```
applications
```
技能监控工作流运行
如果用户需要周期性执行，Agent已完成cron调度配置

</success_criteria>

Composability

可组合能力

Check credentials first: Use
```
status
```
skill to verify TrueFoundry connection
Find workspace: Use
```
workspaces
```
skill to list available workspaces

List workflows: Use

applications

skill with

application_type: "workflow"

Monitor runs: Use
```
jobs
```
skill to check run status and history
View logs: Use
```
logs
```
skill to inspect task-level logs
Manage secrets: Use
```
secrets
```
skill to set up secret groups for workflow tasks that need API keys or credentials

</references> <troubleshooting>

优先检查凭证：使用
```
status
```
技能核验TrueFoundry连接
查找工作区：使用
```
workspaces
```
技能列出可用工作区

列出工作流：使用

applications

技能筛选

application_type: "workflow"

监控运行：使用
```
jobs
```
技能查看运行状态和历史
查看日志：使用
```
logs
```
技能查看任务级日志
管理密钥：使用
```
secrets
```
技能为需要API密钥或凭证的工作流任务配置密钥组

</references> <troubleshooting>

Error Handling

错误处理

CLI Errors

CLI错误

tfy: command not found
Install the TrueFoundry CLI:
  pip install 'truefoundry==0.5.0'
  tfy login --host "$TFY_BASE_URL"

Manifest validation failed.
Check:
- YAML syntax is valid
- Required fields: name, type, workflow_file, workspace_fqn
- Workflow file path is correct and accessible

tfy: command not found
安装TrueFoundry CLI：
  pip install 'truefoundry==0.5.0'
  tfy login --host "$TFY_BASE_URL"

清单校验失败
检查：
- YAML语法正确
- 必填字段：name、type、workflow_file、workspace_fqn
- 工作流文件路径正确且可访问

SDK Not Installed

SDK未安装

The truefoundry[workflow] package is required for defining tasks and workflows:
  pip install "truefoundry[workflow]"

定义任务和工作流需要安装truefoundry[workflow]包：
  pip install "truefoundry[workflow]"

TFY_WORKSPACE_FQN Not Set

TFY_WORKSPACE_FQN未设置

TFY_WORKSPACE_FQN is required. Get it from:
- TrueFoundry dashboard -> Workspaces
- Or use the `workspaces` skill to list available workspaces
Do not auto-pick a workspace.

TFY_WORKSPACE_FQN是必填项，可以从以下位置获取：
- TrueFoundry控制台 -> 工作区页面
- 或使用`workspaces`技能列出可用工作区
不要自动选择工作区。

Flyte Data Plane Not Available

Flyte数据平面不可用

Flyte data plane is not installed on this cluster.
The control plane ships with TrueFoundry, but the data plane must be installed
on each cluster separately. Contact your platform admin to set up the Flyte
data plane components on the target cluster.

该集群未安装Flyte数据平面。
控制平面随TrueFoundry内置，但数据平面需要在每个集群单独安装。请联系平台管理员在目标集群安装Flyte数据平面组件。

Business Logic in Workflow Function

工作流函数中包含业务逻辑

Error: Workflow function contains non-task code.
The @workflow function must only contain task calls and control flow.
Move all computation into @task-decorated functions.

Bad:
  @workflow
  def my_wf():
      data = pd.read_csv("file.csv")  # NOT allowed in workflow function
      return process(data)

Good:
  @workflow
  def my_wf():
      data = load_data()              # Call a @task instead
      return process(data)

错误：工作流函数包含非任务代码。
@workflow函数只能包含任务调用和控制流逻辑。
请将所有计算逻辑移动到@task装饰的函数中。

错误示例：
  @workflow
  def my_wf():
      data = pd.read_csv("file.csv")  # 工作流函数中不允许
      return process(data)

正确示例：
  @workflow
  def my_wf():
      data = load_data()              # 改为调用@task
      return process(data)

Missing truefoundry[workflow] in Task Packages

任务依赖中缺失truefoundry[workflow]

Each task's PythonTaskConfig must include "truefoundry[workflow]" in pip_packages.
Without it, the task container cannot communicate with the Flyte backend.

Fix: Add "truefoundry[workflow]" to the pip_packages list in every PythonTaskConfig.

每个任务的PythonTaskConfig的pip_packages中必须包含"truefoundry[workflow]"。
缺少该依赖时，任务容器无法与Flyte后端通信。

修复方案：在每个PythonTaskConfig的pip_packages列表中添加"truefoundry[workflow]"。

Task Resource Errors

任务资源错误

Task failed due to resource limits (OOMKilled or CPU throttled).
Increase memory_limit or cpu_limit in the task's Resources config.
Check the task logs in the TrueFoundry dashboard for details.

任务因资源限制失败（OOMKilled或CPU被限流）。
请调大任务Resources配置中的memory_limit或cpu_limit。
可在TrueFoundry控制台查看任务日志获取详情。

Cron Schedule Not Triggering

Cron调度未触发

Cron schedules use UTC timezone. Verify your cron expression accounts for
UTC offset from your local timezone.
Use https://crontab.guru to validate your cron expression.

Cron调度使用UTC时区，请确认你的cron表达式已考虑本地时区与UTC的偏移。
可使用https://crontab.guru验证cron表达式的正确性。

REST API Fallback Errors

REST API降级方案错误

401 Unauthorized — Check TFY_API_KEY is valid
404 Not Found — Check TFY_BASE_URL and API endpoint path
422 Validation Error — Check manifest fields match expected schema

</troubleshooting>

401 未授权 — 检查TFY_API_KEY是否有效
404 未找到 — 检查TFY_BASE_URL和API端点路径是否正确
422 校验错误 — 检查清单字段是否符合预期schema

</troubleshooting>

truefoundry-workflows

Original

Translation

TrueFoundry Workflows

TrueFoundry Workflows

When to Use

适用场景

When NOT to Use

不适用场景

Prerequisites

前置要求

CLI Detection

CLI版本检测

Core Concepts

核心概念

Basic Workflow Example

基础工作流示例

Define task configuration

定义任务配置

Task Configuration

任务配置

PythonTaskConfig

PythonTaskConfig

CPU task

CPU任务

GPU task (for training or inference steps)

GPU任务（用于训练或推理步骤）

Container Tasks

容器任务

Cron Workflows (Scheduling)

Cron工作流（定时调度）

Common Cron Patterns

常用Cron规则

Advanced Patterns

高级模式

Deploying Workflows

部署工作流

Approach A: Via tfy deploy workflow (CLI -- Primary)

方案A：通过tfy deploy workflow（CLI——首选方式）

Approach B: Via tfy apply (YAML Manifest -- Alternative)

方案B：通过tfy apply（YAML清单——替代方式）

workflow-manifest.yaml

workflow-manifest.yaml

Approach C: Via Python SDK

方案C：通过Python SDK

Deployment Checklist

部署检查清单

Monitoring Workflow Runs

监控工作流运行

Run States

运行状态

Composability

可组合能力

Error Handling

错误处理

CLI Errors

CLI错误

SDK Not Installed

SDK未安装

TFY_WORKSPACE_FQN Not Set

TFY_WORKSPACE_FQN未设置

Flyte Data Plane Not Available

Flyte数据平面不可用

Business Logic in Workflow Function

工作流函数中包含业务逻辑

Missing truefoundry[workflow] in Task Packages

任务依赖中缺失truefoundry[workflow]

Task Resource Errors

任务资源错误

Cron Schedule Not Triggering

Cron调度未触发

REST API Fallback Errors

REST API降级方案错误

Approach A: Via
`tfy deploy workflow`
(CLI -- Primary)

方案A：通过
`tfy deploy workflow`
（CLI——首选方式）

Approach B: Via
`tfy apply`
(YAML Manifest -- Alternative)

方案B：通过
`tfy apply`
（YAML清单——替代方式）