数据导入导出类任务模板

需要把外部数据源/数据集/模型/标注结果导入或导出到平台目录时，查这些算子的参数与行为。

05-任务模板 / 数据导入导出

dataxdatax-importdataset数据集下载model-download模型下载label-studio-import标注导出huggingfacemodelscope魔塔DataXCOCOYOLO数据导入数据导出

数据导入导出类任务模板

本家族包含 4 个算子，统一解决「外部 → 平台目录」「平台 → 目录」的数据/模型/标注搬运问题：

算子	平台模板	用途
datax	datax / datax-import	异构数据源同步与数据库表导出 CSV
dataset	dataset	下载数据集到目录
model-download	model-download	下载模型到目录
label-studio-import	label-studio-import	导出 Label Studio 标注数据

交叉引用：dataset / model-download 与平台「数据集」「模型管理」「推理服务」功能配套使用，平台侧功能见数据资产与处理与服务化与推理；label-studio-import 与数据标注配套。

datax

基于阿里巴巴 DataX 的异构数据源同步/导入算子，提供两个子模板。

镜像：ccr.ccs.tencentyun.com/cube-studio/datax:20240501
实现目录：job-template/job/datax
镜像默认入口：Dockerfile 的 ENTRYPOINT 为 python start.py（即 datax-import 子模板）；datax 原生子模板由模板的启动命令改用 start.sh。

子模板一：datax（手写 job.json）

入口：start.sh，解析 -f 后执行 python datax.py <job.json路径>。
适用：需要完整 DataX 能力（任意 Reader/Writer、复杂映射/过滤），愿意手写 DataX job JSON。

参数	类型	必填	说明
`-f`	文件路径	是	DataX job.json 文件地址（如 `/mnt/{{creator}}/pipeline/example/ml/mysql-csv.json`）。JSON 写法见 DataX 官方文档

镜像内自带若干示例 job 配置：mysql-csv.json、postgresql-csv.json、clickhouse-csv.json、hive-csv.json、hive-stream.json，可参考改写。

子模板二：datax-import（表单化导出数据库表为 CSV）

入口：start.py，读取内置模板 to-csv.json，把表单参数替换进占位符（READER/USERNAME/PASSWORD/HOST/DATABASE/TABLE/COLUMNS/OUTDIR/OUTNAME），生成临时 DataX 配置 <db_type>_csv.json 再执行 python datax.py，最后把带随机后缀的输出文件重命名为 --save_path。
适用：从数据库表导出为 CSV，免写 JSON。

参数	类型	必填	说明
`--db_type`	str	是	数据库类型，对应 DataX reader 名（如 `mysql`→mysqlreader、`postgresql`、`clickhouse`）
`--host`	str	是	数据库地址含端口（如 `mysql-service.infra:3306`），拼进 jdbcUrl
`--username`	str	是	数据库用户名
`--password`	str	是	数据库密码
`--database`	str	是	库名
`--table`	str	是	表名
`--columns`	str	是	要导出的列名，逗号分隔（如 `id,name,age`）
`--save_path`	文件路径	是	导出 CSV 的保存地址
`--query_sql`	str	否	自定义查询 SQL

注意：--query_sql 虽在 start.py:31 通过 argparse 定义，但在 to-csv.json 占位符替换逻辑（start.py:41-49）与最终命令拼接（start.py:55）里均未被使用（脚本中再无 args.query_sql 引用）；即当前 datax-import 实际只能整表+指定列导出，query_sql 不生效。

注意：start.py:45 中 config.replace('DATABASE', args.databasen if '?' in args.database else ...) 引用了不存在的属性 args.databasen（应为 args.database 笔误，argparse 只定义了 --database）；当 --database 含 ? 时会走到该分支抛 AttributeError，是代码 bug。

选型

需求	推荐子模板
任意 DataX 读写组合 / 复杂配置	datax（手写 job.json + `start.sh`）
MySQL/PostgreSQL/ClickHouse 表导出为 CSV、快速配置	datax-import（表单 + `start.py`）

dataset

把数据集下载到指定目录，支持三种来源。

镜像：ccr.ccs.tencentyun.com/cube-studio/dataset:20250301（job-template/job/dataset/build.sh 当前构建版本；README 正文里写的是旧版 20240501，以 build.sh 为准）
实现：job-template/job/dataset/launcher.py
平台 API 地址：环境变量 HOST（或 KFJ_MODEL_REPO_API_URL），默认 http://kubeflow-dashboard.infra；请求头 Authorization 取环境变量 SECRET（默认等于 KFJ_CREATOR）。

来源（--src_type）

取值	行为
`当前平台` / `cube-studio`	调平台 API `/dataset_modelview/api/` 按 name+version 查询数据集，再按 `/dataset_modelview/api/download/{id}[/{partition}]` 取多个 `download_urls`，并行 HTTP 下载，下载后自动解压目录下 `.zip` / `.tar.gz` / `.gz`
`huggingface`	`huggingface-cli download --repo-type dataset --resume-download {name} --revision {version} --local-dir {save_dir} --local-dir-use-symlinks False`
`modelscope` / `魔塔`	`modelscope download --dataset {name} --local_dir {save_dir}`（当前实现未把 `--version` 传入 ModelScope 命令）

参数

参数	类型	必填	默认	说明
`--src_type`	str	是	`当前平台`	来源：`当前平台`/`cube-studio`/`huggingface`/`modelscope`/`魔塔`
`--name`	str	是	-	数据集名（平台名 / HF 仓库名 / ModelScope 数据集名）
`--version`	str	是	`latest`	版本/分支（当前平台与 HF 用，HF 映射为 `--revision`；ModelScope 未传）
`--partition`	str	否	`''`	分区/子集名，仅当前平台生效
`--save_dir`	str	否	见下	本地保存目录

save_dir 默认：无分区 /mnt/{KFJ_CREATOR}/dataset/{name}/{version}；有分区 /mnt/{KFJ_CREATOR}/dataset/{name}/{version}/{partition}。

# 当前平台（带分区）
python launcher.py --src_type cube-studio --name my-dataset --version v1 --partition train --save_dir /data/dataset/train
# Hugging Face
python launcher.py --src_type huggingface --name squad --version main --save_dir /data/squad
# 魔塔
python launcher.py --src_type modelscope --name 某数据集 --version latest --save_dir /data/ms-dataset

model-download

从多种来源下载模型到指定目录，常用作流水线首节点拉取基线模型。

镜像：ccr.ccs.tencentyun.com/cube-studio/model_download:20250301
实现：job-template/job/model_download/launcher.py
平台 API / 鉴权：同 dataset，使用 HOST/KFJ_MODEL_REPO_API_URL（默认 http://kubeflow-dashboard.infra）与 SECRET（默认 KFJ_CREATOR）。
Hugging Face 可配 HF_ENDPOINT（如 https://hf-mirror.com）、HF_HUB_ENABLE_HF_TRANSFER 加速。

来源（--from）

取值	行为
`模型管理`（或含 `model`）	调 `/training_model_modelview/api/` 按「模型名+版本」查 `path`；path 为 JSON 时用 `--sub_model_name` 取子路径；path 为 URL 则 HTTP 下载、为本地路径则拷贝到 `--save_path`；并把模型元数据写入 `{name}.{version}.json`
`推理服务`（或含 `inference`）	调 `/inferenceservice_modelview/api/` 按「模型名+版本(+可选 model_status)」查 `model_path`，同样支持 JSON 子模型与 URL/本地路径下载或拷贝
`huggingface`	`huggingface-cli download --repo-type model --resume-download {model_name} [--revision {model_version}] --local-dir {save_path} --local-dir-use-symlinks False`
`魔塔` / `modelscope`	`modelscope download --model {model_name} --local_dir {save_path}`

参数

参数	类型	必填	默认	说明
`--from`	str	是	模板默认 `模型管理`（代码 argparse 默认为 `train_model`，含 `model` 故等同模型管理）	模型来源：`模型管理`/`推理服务`/`huggingface`/`魔塔`
`--model_name`	str	是	-	模型名 / HF 仓库名 / ModelScope 模型 ID
`--sub_model_name`	str	否	`''`	多子模型时指定子模型键名（path 为 JSON 时）
`--model_version`	str	否	`''`	版本号；HF 时为 revision
`--model_status`	str	否	`''`	`online`/`offline`/`test`，仅来源为推理服务时有效
`--save_path`	str	是	-	下载目的目录（需容器内可写，建议挂载持久化路径）

python3 launcher.py --from 模型管理   --model_name my-model --model_version v1.0 --save_path /mnt/workspace/model
python3 launcher.py --from 推理服务   --model_name my-model --model_version v1.0 --model_status online --save_path /mnt/workspace/model
python3 launcher.py --from huggingface --model_name bert-base-chinese --model_version main --save_path /mnt/workspace/model
python3 launcher.py --from 魔塔        --model_name damo/xxx --save_path /mnt/workspace/model

label-studio-import

从 Label Studio 标注平台的数据库中批量导出指定项目的标注数据，默认导出 JSON，可额外导出 COCO / YOLO / YOLOv8-OBB 数据集格式，便于直接喂给训练任务。

该算子在分组上归入「数据导入导出」家族：它把 Label Studio 中的标注结果导入/导出到平台用户目录，是标注 → 训练之间的桥梁。平台标注功能见数据标注。

镜像：ccr.ccs.tencentyun.com/cube-studio/label-studio-import:20260601
实现：job-template/job/label-studio-import/launcher.py，直接连 Label Studio 使用的 PostgreSQL 库查询。
连接配置（环境变量）：
- POSTGRES_HOST：Label Studio 数据库连接串，默认 postgresql+psycopg2://postgres:postgres@postgresql.kubeflow:5432/labelstudio；自建 Label Studio 时在模板高级配置覆盖。
- LABELSTUDIO_BASE_URL：默认 http://labelstudio.kubeflow:8080。
- SECRET：作为 Label Studio token（LABELSTUDIO_TOKEN）。
查询逻辑：先校验 project 表中项目存在；再查 task（total_annotations>0 且符合过滤条件）；为每个 task 关联 task_completion（标注 annotations）、prediction（predictions），并附上所属 project 信息。导出 JSON 为任务字典列表。

参数

参数	类型	必填	平台默认	说明
`--project_id`	str	是	`2`	Label Studio 项目 ID（`project.id`）；不存在则任务失败
`--filter`	str	是	`updated_at>'2024-02-08'`	task 表过滤条件片段，多条用 `,`/`&`/`;` 分隔，内部用 SQL `AND` 拼接，双引号 `"` 会被替换为单引号 `'`
`--output_format`	str	是	`json`	输出格式：`json`/`coco`/`yolo`/`yolov8_obb`（值会小写并把 `-` 转 `_`）
`--save_path`	str(workdir)	是	`/mnt/{{creator}}/pipeline/example/label-studio/result.json`	json 时填文件地址，非 json 时填目录

提示：--project_id / --filter 上述默认值来自平台模板配置；脚本 argparse 的代码默认值为空字符串。--output_format 为 json 时仅导出 JSON；为 coco/yolo/yolov8_obb 时会在目录额外生成对应数据集（COCO 需要 Pillow）。

过滤条件写法举例：

只按更新时间：updated_at>'2024-02-08'
多条件：updated_at>'2024-02-08', is_labeled=true → 等价 ... AND updated_at>'2024-02-08' AND is_labeled=true
ID 集合：id in (1,2,3)

请确保过滤条件字段与所用 Label Studio 版本的 task 表字段一致，时间/字符串使用引号。

最后更新 2026-06-30完整文档以官方仓库为准：GitHub Wiki