# 创建模型调优任务

> 全部文档的索引见 [llms.txt](https://ark.volcengine.com/llms.txt)；在任一文档页面地址后追加 `.md` 可获取该页的 Markdown 版本。

`POST https://ark.cn-beijing.volcengineapi.com/?Action=CreateModelCustomizationJob&Version=2024-01-01`

创建一个模型调优任务，支持全量 SFT、SFT-LoRA、继续预训练、DPO-LoRA、DPO、GRPO、GRPOLoRA、PPO、OPD、OPDLoRA 等训练类型。

> **说明**
>
> - 训练类型 *CustomizationType* 一经创建即不可修改；如需更换类型请新建任务。
> - 任务创建后会进入排队（`Queue`）→ 运行中（`Running`）→ 完成（`Completed`）/ 失败（`Failed`）/ 取消（`Cancelled`）的阶段流转，可通过 *GetModelCustomizationJob* 接口查询当前 *Status.Phase*。
> - *Hyperparameters* 数组中每一项的 *Name* 不能重复；具体可用超参数因训练类型不同而异，请参考训练类型文档。
> - 强化学习类训练（`GRPO`、`GRPOLoRA`、`PPO` 等）需配合 *RewardConfigs* 或 *CustomRLPipelineConfig* 使用。

## 鉴权

本接口支持鉴权方式如下，详情请参见 [Base URL 及鉴权](/docs/base-url-and-authentication)。

* Access Key 鉴权，请在 [Access Key 管理](https://console.volcengine.com/iam/keymanage) 页面，获取 Access Key。本接口仅支持 Access Key 鉴权。

---

<span id="request-parameters"></span>
## 请求参数

### Body 参数

**CustomizationType** `string` `必选` | 训练类型

训练类型。取值范围：`FinetuneSft`（全量 SFT）、`FinetuneLoRA`（SFT-LoRA）、`Pretrain`（继续预训练）、`DPOLoRA`、`DPO`、`GRPO`、`GRPOLoRA`、`PPO`、`OPD`、`OPDLoRA`。一经创建不可修改。

**Data** `object` `必选` | 微调数据集

模型微调数据集，包含训练集和可选的验证集配置

**TrainingSet** `object` `必选` | 训练数据集

`Data.TrainingSet`

**Datasets** `object[]` | 数据集列表

`Data.TrainingSet.Datasets`

数据集列表，当此字段不为空时表示使用数据集数据训练。不可与 TosBucket，TosPaths 同时存在

**DatasetId** `string` `必选` | 数据集 ID

`Data.TrainingSet.Datasets.DatasetId`

**DatasetVersionId** `string` `必选` | 版本 ID

`Data.TrainingSet.Datasets.DatasetVersionId`

数据集版本 ID

**Multiplier** `string` | 采样倍率

`Data.TrainingSet.Datasets.Multiplier`

**SampleCount** `number` | 样本数

`Data.TrainingSet.Datasets.SampleCount`

采样的样本数

**PresetData** `string` | 预置数据集名称

`Data.TrainingSet.PresetData`

预置数据集名称，不填不适用预置数据集

**PresetDataPercentage** `integer` `默认值 10` | 预置数据集占比

`Data.TrainingSet.PresetDataPercentage`

预置数据集使用百分比（0-100），仅在填写了 PresetData 时有效。

**PresetDatasets** `object[]` | 预置数据集列表

`Data.TrainingSet.PresetDatasets`

**DatasetVersionId** `string` `必选` | 预置数据集版本

`Data.TrainingSet.PresetDatasets.DatasetVersionId`

**InjectMultiplier** `string` | 混入倍率

`Data.TrainingSet.PresetDatasets.InjectMultiplier`

预置数据集混入倍率

**InjectSampleCount** `number` | 混入样本数

`Data.TrainingSet.PresetDatasets.InjectSampleCount`

预置数据集混入的样本数

**TosBucket** `string` | TOS 桶名

`Data.TrainingSet.TosBucket`

TOS 桶名，需与 TosPaths 同时存在，当此字段不为空时表示使用直接使用 TOS 数据训练，不可与 Datasets 同时存在

**TosPaths** `string[]` | TOS 存储路径

`Data.TrainingSet.TosPaths`

TOS 存储路径，需与 TosBucket 同时存在，当此字段不为空时表示使用直接使用 TOS 数据训练，不可与 Datasets 同时存在

**EncryptionKeyringType** `string` `默认值 ManagedKeyring` | 加密密钥类型

`Data.EncryptionKeyringType`

加密密钥类型。取值范围：`ManagedKeyring`、`CustomKeyring`。

**KMSTrn** `string` | 加密密钥 TRN

`Data.KMSTrn`

加密密钥 TRN，可在 KMS 控制台获取。当 *EncryptionKeyringType* 为 `ManagedKeyring`（默认）时自动生成且不可填写；为 `CustomKeyring` 时必填。

**ValidationPercentage** `integer` | 验证集采样比例

`Data.ValidationPercentage`

使用训练集数据作为验证集的比例（0-100）

**ValidationSet** `object` | 验证数据集

`Data.ValidationSet`

**Datasets** `object[]` | 数据集列表

`Data.ValidationSet.Datasets`

**DatasetId** `string` `必选` | 数据集 ID

`Data.ValidationSet.Datasets.DatasetId`

**DatasetVersionId** `string` `必选` | 版本 ID

`Data.ValidationSet.Datasets.DatasetVersionId`

数据集版本 ID

**Multiplier** `string` | 采样倍率

`Data.ValidationSet.Datasets.Multiplier`

**SampleCount** `number` | 样本数

`Data.ValidationSet.Datasets.SampleCount`

采样的样本数

**TosBucket** `string` | TOS 桶名

`Data.ValidationSet.TosBucket`

TOS 桶名，需与 TosPaths 同时存在，当此字段不为空时表示使用直接使用 TOS 数据，不可与 Datasets 同时存在

**TosPaths** `string[]` | TOS 存储路径

`Data.ValidationSet.TosPaths`

TOS 存储路径，需与 TosBucket 同时存在，当此字段不为空时表示使用直接使用 TOS 数据，不可与 Datasets 同时存在

**ModelReference** `object` `必选` | 微调基础模型

微调基于的模型，必须在定制模型和基座模型中二选一

**CustomModelId** `string` | 定制模型 ID

`ModelReference.CustomModelId`

定制模型的 ID

**FoundationModel** `object` | 基础模型

`ModelReference.FoundationModel`

**ModelVersion** `string` `必选` | 模型版本

`ModelReference.FoundationModel.ModelVersion`

基础模型版本

**Name** `string` `必选` | 模型名称

`ModelReference.FoundationModel.Name`

基础模型名称

**Name** `string` `必选` | 任务名称

模型调优任务名称

**BillingMethod** `string` | 计费方式

任务计费方式。取值范围：`Instance`、`InstanceByCheckpoint`、`Token`、`TokenByCheckpoint`。其中带 Checkpoint 后缀表示按检查点计费。

**CustomRLPipelineConfig** `object` | RL 流水线配置

自定义强化学习流水线配置，用于配置 RL 训练流水线的插件和混合策略

**PipelinePlugins** `object[]` `必选` | 插件列表

`CustomRLPipelineConfig.PipelinePlugins`

RL 训练流水线插件列表，定义流水线中各阶段使用的插件

**Name** `string` `必选` | 插件名称

`CustomRLPipelineConfig.PipelinePlugins.Name`

**Description** `string` | 插件描述

`CustomRLPipelineConfig.PipelinePlugins.Description`

**Embedded** `object` | 内嵌插件

`CustomRLPipelineConfig.PipelinePlugins.Embedded`

内嵌插件配置

**FunctionMeta** `object` `必选` | 函数元信息

`CustomRLPipelineConfig.PipelinePlugins.Embedded.FunctionMeta`

**FunctionIdentifier** `string` `必选` | 函数标识

`CustomRLPipelineConfig.PipelinePlugins.Embedded.FunctionMeta.FunctionIdentifier`

**Source** `string` `必选` | 源

`CustomRLPipelineConfig.PipelinePlugins.Embedded.FunctionMeta.Source`

**SourceType** `string` `必选` | 源类型

`CustomRLPipelineConfig.PipelinePlugins.Embedded.FunctionMeta.SourceType`

**Type** `string` `必选` | 函数类型

`CustomRLPipelineConfig.PipelinePlugins.Embedded.FunctionMeta.Type`

**FunctionConfig** `object` | 函数配置

`CustomRLPipelineConfig.PipelinePlugins.Embedded.FunctionConfig`

**CpuMilli** `integer` | CPU 毫核

`CustomRLPipelineConfig.PipelinePlugins.Embedded.FunctionConfig.CpuMilli`

**EnvVars** `object[]` | 环境变量列表

`CustomRLPipelineConfig.PipelinePlugins.Embedded.FunctionConfig.EnvVars`

**Key** `string` `必选` | 环境变量名

`CustomRLPipelineConfig.PipelinePlugins.Embedded.FunctionConfig.EnvVars.Key`

**Value** `string` `必选` | 环境变量值

`CustomRLPipelineConfig.PipelinePlugins.Embedded.FunctionConfig.EnvVars.Value`

**MaxConcurrency** `integer` | 最大并发数

`CustomRLPipelineConfig.PipelinePlugins.Embedded.FunctionConfig.MaxConcurrency`

**MaxReplica** `integer` | 最大副本数

`CustomRLPipelineConfig.PipelinePlugins.Embedded.FunctionConfig.MaxReplica`

**MemoryMB** `integer` | 内存 MB

`CustomRLPipelineConfig.PipelinePlugins.Embedded.FunctionConfig.MemoryMB`

**MinReplica** `integer` | 最小副本数

`CustomRLPipelineConfig.PipelinePlugins.Embedded.FunctionConfig.MinReplica`

**RequestConcurrency** `integer` | 单实例并发

`CustomRLPipelineConfig.PipelinePlugins.Embedded.FunctionConfig.RequestConcurrency`

单实例请求并发数

**RequestTimeoutSeconds** `integer` | 请求超时秒数

`CustomRLPipelineConfig.PipelinePlugins.Embedded.FunctionConfig.RequestTimeoutSeconds`

**Runtime** `string` | 运行时

`CustomRLPipelineConfig.PipelinePlugins.Embedded.FunctionConfig.Runtime`

**Tags** `object[]` | 标签列表

`CustomRLPipelineConfig.PipelinePlugins.Embedded.FunctionConfig.Tags`

**Key** `string` `必选` | 标签键

`CustomRLPipelineConfig.PipelinePlugins.Embedded.FunctionConfig.Tags.Key`

**Value** `string` `必选` | 标签值

`CustomRLPipelineConfig.PipelinePlugins.Embedded.FunctionConfig.Tags.Value`

**Weight** `number` | 权重

`CustomRLPipelineConfig.PipelinePlugins.Embedded.FunctionConfig.Weight`

**Managed** `object` | 托管插件

`CustomRLPipelineConfig.PipelinePlugins.Managed`

托管插件配置

**SID** `string` `必选` | 插件 SID

`CustomRLPipelineConfig.PipelinePlugins.Managed.SID`

**FunctionConfig** `object` | 函数配置

`CustomRLPipelineConfig.PipelinePlugins.Managed.FunctionConfig`

**CpuMilli** `integer` | CPU 毫核

`CustomRLPipelineConfig.PipelinePlugins.Managed.FunctionConfig.CpuMilli`

**EnvVars** `object[]` | 环境变量列表

`CustomRLPipelineConfig.PipelinePlugins.Managed.FunctionConfig.EnvVars`

**Key** `string` `必选` | 环境变量名

`CustomRLPipelineConfig.PipelinePlugins.Managed.FunctionConfig.EnvVars.Key`

**Value** `string` `必选` | 环境变量值

`CustomRLPipelineConfig.PipelinePlugins.Managed.FunctionConfig.EnvVars.Value`

**MaxConcurrency** `integer` | 最大并发数

`CustomRLPipelineConfig.PipelinePlugins.Managed.FunctionConfig.MaxConcurrency`

**MaxReplica** `integer` | 最大副本数

`CustomRLPipelineConfig.PipelinePlugins.Managed.FunctionConfig.MaxReplica`

**MemoryMB** `integer` | 内存 MB

`CustomRLPipelineConfig.PipelinePlugins.Managed.FunctionConfig.MemoryMB`

**MinReplica** `integer` | 最小副本数

`CustomRLPipelineConfig.PipelinePlugins.Managed.FunctionConfig.MinReplica`

**RequestConcurrency** `integer` | 单实例并发

`CustomRLPipelineConfig.PipelinePlugins.Managed.FunctionConfig.RequestConcurrency`

单实例请求并发数

**RequestTimeoutSeconds** `integer` | 请求超时秒数

`CustomRLPipelineConfig.PipelinePlugins.Managed.FunctionConfig.RequestTimeoutSeconds`

**Runtime** `string` | 运行时

`CustomRLPipelineConfig.PipelinePlugins.Managed.FunctionConfig.Runtime`

**Tags** `object[]` | 标签列表

`CustomRLPipelineConfig.PipelinePlugins.Managed.FunctionConfig.Tags`

**Key** `string` `必选` | 标签键

`CustomRLPipelineConfig.PipelinePlugins.Managed.FunctionConfig.Tags.Key`

**Value** `string` `必选` | 标签值

`CustomRLPipelineConfig.PipelinePlugins.Managed.FunctionConfig.Tags.Value`

**Weight** `number` | 权重

`CustomRLPipelineConfig.PipelinePlugins.Managed.FunctionConfig.Weight`

**Tags** `object[]` | 标签列表

`CustomRLPipelineConfig.PipelinePlugins.Tags`

**Key** `string` `必选` | 标签键

`CustomRLPipelineConfig.PipelinePlugins.Tags.Key`

**Value** `string` `必选` | 标签值

`CustomRLPipelineConfig.PipelinePlugins.Tags.Value`

**GraderMixer** `string` | 评分混合策略

`CustomRLPipelineConfig.GraderMixer`

评分混合策略，控制多个奖励函数的混合方式

**TeacherConfigs** `string` | 教师模型配置

`CustomRLPipelineConfig.TeacherConfigs`

教师模型配置，用于蒸馏类训练场景

**DebugConfig** `object` | 调试配置

调试配置，包含 RL 调试相关设置

**RLDebugConfig** `object` | RL 调试配置

`DebugConfig.RLDebugConfig`

强化学习训练的调试配置

**APIKey** `string` `必选` | API Key

`DebugConfig.RLDebugConfig.APIKey`

调用推理接入点鉴权使用的 API Key

**EndpointID** `string` `必选` | Endpoint ID

`DebugConfig.RLDebugConfig.EndpointID`

用于 RL 调试的推理接入点 ID

**Description** `string` | 任务描述

模型调优任务描述

**EnableTrajectory** `boolean` | 启用轨迹采集

是否启用轨迹记录

**Hyperparameters** `object[]` | 训练超参

训练超参数配置。数组中每一项的 *Name* 不能重复；可用超参数因训练类型而异。

**Name** `string` `必选` | 参数名

`Hyperparameters.Name`

超参数的参数名

**Value** `string` `必选` | 参数值

`Hyperparameters.Value`

超参数的参数值

**OutputConfig** `object` | 输出配置

输出配置，包含输出压缩策略等选项

**OutputCompressionStrategies** `string[]` | 输出压缩策略

`OutputConfig.OutputCompressionStrategies`

输出压缩策略列表，控制模型产物的压缩方式

**Priority** `string` | 调度优先级

任务调度优先级。`Allocated` 表示使用预留资源调度，优先级较高；`Spot` 表示使用抢占式资源调度，成本更低但可能被高优任务抢占。

**ProjectName** `string` `默认值 default` | 所属项目

资源所属的项目名称。若资源不在默认项目中，需填写正确的项目名称。

**RewardConfigs** `object[]` | 奖励规则配置

奖励规则配置，用于强化学习训练类型（如 GRPO、PPO）

**CustomRewardFunction** `object` | 自定义奖励

`RewardConfigs.CustomRewardFunction`

自定义奖励函数配置

**FaaSFunctionID** `string` `必选` | veFaaS 函数 ID

`RewardConfigs.CustomRewardFunction.FaaSFunctionID`

veFaaS 函数 id

**PresetRewardFunction** `object` | 预置奖励函数配置

`RewardConfigs.PresetRewardFunction`

**Hyperparameters** `object[]` `必选` | 参数列表

`RewardConfigs.PresetRewardFunction.Hyperparameters`

**Name** `string` `必选` | 参数名

`RewardConfigs.PresetRewardFunction.Hyperparameters.Name`

超参数的参数名

**Value** `string` `必选` | 参数值

`RewardConfigs.PresetRewardFunction.Hyperparameters.Value`

超参数的参数值

**Name** `string` `必选` | 预置奖励函数名

`RewardConfigs.PresetRewardFunction.Name`

**Weight** `number` | 权重

`RewardConfigs.Weight`

**SaveModelLimit** `integer` `默认值 1` | 保存模型上限

保存模型的最大数量限制，取值范围为 1~10。

**取值范围**：`[1, 10]`

**Tags** `object[]` | 标签列表

标签信息配置，用于对任务进行分类管理

**Key** `string` `必选` | 标签键

`Tags.Key`

**Value** `string` `必选` | 标签值

`Tags.Value`

**TestOptions** `object` | 测试选项（内部）

测试选项，仅用于内部测试

**DisableAutoCompression** `number` | 禁用自动压缩

`TestOptions.DisableAutoCompression`

内部测试用，是否禁用自动压缩

**FoundationModelVersionConfigurationId** `string` | 配置 ID

`TestOptions.FoundationModelVersionConfigurationId`

内部测试用的基础模型版本配置 ID

**SpecifiedClusterID** `string` | 指定集群 ID

`TestOptions.SpecifiedClusterID`

内部测试用的指定训练集群 ID

**TrainingConfigOverridePolicyIndices** `integer[]` | 训练配置覆盖索引

`TestOptions.TrainingConfigOverridePolicyIndices`

内部测试用的训练配置覆盖策略索引列表

## 响应参数

**Id** `string` | 任务 ID

创建好的模型调优任务的 ID


## 代码示例

## 默认

### cURL

#### Request

```bash
curl 'https://ark.cn-beijing.volcengineapi.com/?Action=CreateModelCustomizationJob&Version=2024-01-01' \
  -H 'Content-Type: application/json' \
  -H 'X-Date: <X-Date>' \
  -H 'X-Content-Sha256: <X-Content-Sha256>' \
  -H 'Authorization: HMAC-SHA256 Credential=<AK>/<X-Date>/cn-beijing/ark/request, SignedHeaders=content-type;host;x-content-sha256;x-date, Signature=<Signature>' \
  -d '{
    "Name": "测试任务",
    "Description": "这是一个测试任务",
    "Tags": [
        {
            "Key": "test_key",
            "Value": "test_value"
        }
    ],
    "ProjectName": "default",
    "CustomizationType": "FinetuneLoRA",
    "ModelReference": {
        "FoundationModel": {
            "Name": "skylark2-lite-8k",
            "ModelVersion": "1.0"
        }
    },
    "Hyperparameters": [
        {
            "Name": "epoch",
            "Value": "6"
        },
        {
            "Name": "learning_rate",
            "Value": "0.00001"
        }
    ],
    "SaveModelLimit": 1,
    "Data": {
        "TrainingSet": {
            "TosBucket": "ark-auto-created-required-2100000000-cn-beijing",
            "TosPaths": [
                "model-customization-job-upload-set/1712561985763/test.jsonl"
            ]
        }
    }
}
'
```

#### Response

```
{
    "ResponseMetadata": {
        "RequestId": "20240401114541A47B2E9C8F5D103E76",
        "Action": "CreateModelCustomizationJob",
        "Version": "2024-01-01",
        "Service": "ark",
        "Region": "cn-beijing"
    },
    "Result": {
        "Id": "mcj-20240401114541-5gzd8"
    }
}
```