# 获取模型调优任务列表
> 全部文档的索引见 [llms.txt](https://ark.volcengine.com/llms.txt)；在任一文档页面地址后追加 `.md` 可获取该页的 Markdown 版本。
`POST https://ark.cn-beijing.volcengineapi.com/?Action=ListModelCustomizationJobs&Version=2024-01-01`
获取模型调优任务列表，支持按条件筛选、分页查询和排序。
## 鉴权
本接口支持鉴权方式如下，详情请参见 [Base URL 及鉴权](/docs/base-url-and-authentication)。
* Access Key 鉴权，请在 [Access Key 管理](https://console.volcengine.com/iam/keymanage) 页面，获取 Access Key。本接口仅支持 Access Key 鉴权。
---
## 请求参数
### Body 参数
**Filter** `object` | 过滤条件
模型调优任务过滤条件
**CreateTimeAfter** `string` | 创建时间晚于
`Filter.CreateTimeAfter`
创建时间过滤条件，格式为 RFC3339 时间戳，过滤创建时间晚于该时间戳的模型调优任务
**CreateTimeBefore** `string` | 创建时间早于
`Filter.CreateTimeBefore`
创建时间过滤条件，格式为 RFC3339 时间戳，过滤创建时间早于该时间戳的模型调优任务
**CustomizationTypes** `string[]` | 调优类型过滤
`Filter.CustomizationTypes`
调优类型过滤条件
**CustomModelIds** `string[]` | 定制模型 ID 过滤
`Filter.CustomModelIds`
定制模型 ID 过滤条件
**FoundationModels** `object[]` | 基座模型过滤
`Filter.FoundationModels`
基座模型过滤条件
**Name** `string` `必选` | 模型名称
`Filter.FoundationModels.Name`
基础模型名称
**ModelVersions** `string[]` | 模型版本
`Filter.FoundationModels.ModelVersions`
基础模型版本
**Ids** `string[]` | 任务 ID 过滤
`Filter.Ids`
ID 过滤条件
**Name** `string` | 任务名过滤
`Filter.Name`
模型调优任务名过滤条件（模糊匹配）
**Phases** `string[]` | 状态过滤
`Filter.Phases`
模型调优任务状态过滤条件
**ResourceGroup** `string` | 资源组 ID
`Filter.ResourceGroup`
资源组 id
**PageNumber** `integer` `默认值 1` | 翻页页码
翻页页码，从 1 开始计数。
**PageSize** `integer` `默认值 10` | 每页记录数
每页返回的记录数量。
**ProjectName** `string` | 项目名称
项目名称过滤条件，用于筛选指定项目下的调优任务
**SortBy** `string` `默认值 CreateTime` | 排序字段
排序字段。取值：`CreateTime`（按创建时间排序）。
**SortOrder** `string` `默认值 Desc` | 排序顺序
排序顺序。取值：`Desc`（降序）、`Asc`（升序）。
**TagFilters** `object[]` | 标签过滤条件
按标签过滤调优任务
**Key** `string` `必选` | 标签键
`TagFilters.Key`
**Values** `string[]` | 标签值列表
`TagFilters.Values`
标签值
## 响应参数
**Items** `object[]` | 调优任务列表
当前页的模型调优任务列表
**CreateTime** `string` | 创建时间
`Items.CreateTime`
资源创建时间戳
**CustomizationType** `string` | 训练类型
`Items.CustomizationType`
训练类型。取值范围：`FinetuneSft`、`FunetuneLoRA`、`Pretrain`、`DPOLoRA`、`DPO`。
**Data** `object` | 数据集配置
`Items.Data`
模型微调使用的数据集
**TrainingSet** `object` | 训练数据集
`Items.Data.TrainingSet`
**Datasets** `object[]` | 数据集列表
`Items.Data.TrainingSet.Datasets`
数据集列表，当此字段不为空时表示使用数据集数据训练。不可与 TosBucket，TosPaths 同时存在
**DatasetId** `string` | 数据集 ID
`Items.Data.TrainingSet.Datasets.DatasetId`
**DatasetVersionId** `string` | 版本 ID
`Items.Data.TrainingSet.Datasets.DatasetVersionId`
数据集版本 ID
**Multiplier** `string` | 采样倍率
`Items.Data.TrainingSet.Datasets.Multiplier`
**SampleCount** `number` | 样本数
`Items.Data.TrainingSet.Datasets.SampleCount`
采样的样本数
**PresetData** `string` | 预置数据集名
`Items.Data.TrainingSet.PresetData`
预置数据集名称，不填不适用预置数据集
**PresetDataPercentage** `integer` | 预置数据集比例
`Items.Data.TrainingSet.PresetDataPercentage`
预置数据集使用百分比（0-100），仅在填写了 PresetData 时有效
**PresetDatasets** `object[]` | 预置数据集列表
`Items.Data.TrainingSet.PresetDatasets`
**DatasetVersionId** `string` | 预置数据集版本
`Items.Data.TrainingSet.PresetDatasets.DatasetVersionId`
**InjectMultiplier** `string` | 混入倍率
`Items.Data.TrainingSet.PresetDatasets.InjectMultiplier`
预置数据集混入倍率
**InjectSampleCount** `number` | 混入样本数
`Items.Data.TrainingSet.PresetDatasets.InjectSampleCount`
预置数据集混入的样本数
**TosBucket** `string` | TOS 桶名
`Items.Data.TrainingSet.TosBucket`
TOS 桶名，需与 TosPaths 同时存在，当此字段不为空时表示使用直接使用 TOS 数据训练，不可与 Datasets 同时存在
**TosPaths** `string[]` | TOS 存储路径
`Items.Data.TrainingSet.TosPaths`
TOS 存储路径，需与 TosBucket 同时存在，当此字段不为空时表示使用直接使用 TOS 数据训练，不可与 Datasets 同时存在
**EncryptionKeyringType** `string` | 加密密钥类型
`Items.Data.EncryptionKeyringType`
数据集加密密钥类型。取值范围：`ManagedKeyring`、`CustomKeyring`。默认值：`ManagedKeyring`
**KMSTrn** `string` | KMS 密钥 TRN
`Items.Data.KMSTrn`
加密密钥 TRN，可在 KMS 控制台获取。当 *EncryptionKeyringType* 为 `ManagedKeyring`（默认）时自动生成且不可填写；为 `CustomKeyring` 时必填。
**ValidationPercentage** `integer` | 验证集比例
`Items.Data.ValidationPercentage`
使用训练集数据作为验证集的比例（0-100）
**ValidationSet** `object` | 验证数据集
`Items.Data.ValidationSet`
**Datasets** `object[]` | 数据集列表
`Items.Data.ValidationSet.Datasets`
**DatasetId** `string` | 数据集 ID
`Items.Data.ValidationSet.Datasets.DatasetId`
**DatasetVersionId** `string` | 版本 ID
`Items.Data.ValidationSet.Datasets.DatasetVersionId`
数据集版本 ID
**Multiplier** `string` | 采样倍率
`Items.Data.ValidationSet.Datasets.Multiplier`
**SampleCount** `number` | 样本数
`Items.Data.ValidationSet.Datasets.SampleCount`
采样的样本数
**TosBucket** `string` | TOS 桶名
`Items.Data.ValidationSet.TosBucket`
TOS 桶名，需与 TosPaths 同时存在，当此字段不为空时表示使用直接使用 TOS 数据，不可与 Datasets 同时存在
**TosPaths** `string[]` | TOS 存储路径
`Items.Data.ValidationSet.TosPaths`
TOS 存储路径，需与 TosBucket 同时存在，当此字段不为空时表示使用直接使用 TOS 数据，不可与 Datasets 同时存在
**Id** `string` | 任务 ID
`Items.Id`
模型调优任务资源 ID
**ModelReference** `object` | 基础模型
`Items.ModelReference`
微调基于的模型
**CustomModelId** `string` | 定制模型 ID
`Items.ModelReference.CustomModelId`
定制模型的 ID
**FoundationModel** `object` | 基础模型
`Items.ModelReference.FoundationModel`
**ModelVersion** `string` | 模型版本
`Items.ModelReference.FoundationModel.ModelVersion`
基础模型版本
**Name** `string` | 模型名称
`Items.ModelReference.FoundationModel.Name`
基础模型名称
**Name** `string` | 任务名称
`Items.Name`
模型调优任务名称
**ProjectName** `string` | 项目名
`Items.ProjectName`
**PublishedOutputCount** `integer` | 已导出产物数
`Items.PublishedOutputCount`
已导出模型产物总数
**SaveModelLimit** `integer` | 保存模型上限
`Items.SaveModelLimit`
SaveModel 数量的最大限制
**Status** `object` | 任务状态
`Items.Status`
模型精调任务状态
**Phase** `string` | 任务阶段
`Items.Status.Phase`
模型微调任务状态
**PhaseTime** `string` | 阶段时间戳
`Items.Status.PhaseTime`
模型微调任务进入到当前状态的时间戳
**RetryLimit** `integer` | 重试次数上限
`Items.Status.RetryLimit`
模型精调任务可以被重试的次数上限
**BillableTokens** `number` | 计费 tokens 数
`Items.Status.BillableTokens`
训练 tokens 量，用于精调任务计费
**Message** `string` | 状态说明
`Items.Status.Message`
对当前模型微调任务所处状态的解释性信息
**OutputExpiredTime** `string` | 产物过期时间
`Items.Status.OutputExpiredTime`
模型微调产物（如果有）计划过期的时间戳
**QueuePosition** `integer` | 排队位次
`Items.Status.QueuePosition`
排队时，模型微调任务在所属队列中的当前位次
**Resumable** `boolean` | 是否可重试
`Items.Status.Resumable`
任务处于失败状态时，是否可以被重试
**RetryCount** `integer` | 重试次数
`Items.Status.RetryCount`
模型微调任务已经失败重试的次数
**TrainingTokensPerEpoch** `number` | 单轮训练 tokens
`Items.Status.TrainingTokensPerEpoch`
数据集总 tokens，包括训练集、验证集和混入数据
**UpdateTime** `string` | 更新时间
`Items.UpdateTime`
资源更新时间戳
**Description** `string` | 任务描述
`Items.Description`
模型调优任务描述
**Hyperparameters** `object[]` | 超参数列表
`Items.Hyperparameters`
微调配置的超参数
**Name** `string` | 超参数名
`Items.Hyperparameters.Name`
超参数的参数名
**Value** `string` | 超参数值
`Items.Hyperparameters.Value`
超参数的参数值
**Outputs** `object[]` | 精调产物列表
`Items.Outputs`
精调产物
**Index** `integer` | 产物索引
`Items.Outputs.Index`
索引
**Name** `string` | 产物名称
`Items.Outputs.Name`
模型产物名称
**Status** `string` | 产物状态
`Items.Outputs.Status`
模型产物状态。可选值：`Available`、`Exported`、`Expired`。
**CustomModelCreateTimeUnix** `number` | 模型创建时间
`Items.Outputs.CustomModelCreateTimeUnix`
自定义模型创建时间
**CustomModelId** `string` | 自定义模型 ID
`Items.Outputs.CustomModelId`
自定义模型 id
**Reason** `string` | 失败原因
`Items.Reason`
失败任务原因。可选值：`InvalidData`、`InternalError`、`UnknownError`。
**Tags** `object[]` | 标签列表
`Items.Tags`
标签
**Key** `string` | 标签键
`Items.Tags.Key`
**Value** `string` | 标签值
`Items.Tags.Value`
**TotalOutputCount** `integer` | 产物总数
`Items.TotalOutputCount`
精调产物总数
**PageNumber** `integer` | 当前页码
翻页页码，从 1 开始计数。默认值为 1
**PageSize** `integer` | 每页记录数
每页返回的记录数量。默认值为 10
**TotalCount** `integer` | 总记录数
符合查询条件的调优任务总数
## 代码示例
## 默认
### cURL
#### Request
```bash
curl 'https://ark.cn-beijing.volcengineapi.com/?Action=ListModelCustomizationJobs&Version=2024-01-01' \
-H 'Content-Type: application/json' \
-H 'X-Date: ' \
-H 'X-Content-Sha256: ' \
-H 'Authorization: HMAC-SHA256 Credential=//cn-beijing/ark/request, SignedHeaders=content-type;host;x-content-sha256;x-date, Signature=' \
-d '{
"PageNumber": 1,
"PageSize": 10,
"ProjectName": "default",
"TagFilters": [
{
"Key": "sys:ark:createdBy",
"Values": ["IAMUser/23454321/test.user@bytedance.com"]
}
],
"Filter": {
"Ids": ["mcj-20240101000000-a1b2c"]
}
}
'
```
#### Response
```
{
"ResponseMetadata": {
"RequestId": "20240401114541B47C3EAD9F6D204E77",
"Action": "ListModelCustomizationJobs",
"Version": "2024-01-01",
"Service": "ark",
"Region": "cn-beijing"
},
"Result": {
"TotalCount": 1,
"PageNumber": 1,
"PageSize": 10,
"Items": [
{
"Id": "mcj-20240401114541-5gzd8",
"Name": "测试任务",
"Description": "这是一个测试任务",
"Tags": [
{
"Key": "sys:ark:createdBy",
"Value": "IAMUser/23454321/test.user@bytedance.com"
}
],
"ProjectName": "default",
"CustomizationType": "FinetuneLoRA",
"ModelReference": {
"FoundationModel": {
"Name": "doubao-seed-2-0-pro",
"ModelVersion": "260215",
"ConfigurationId": "fmvc-20240401114541-8h9pk"
}
},
"Hyperparameters": [
{
"Name": "epoch",
"Value": "6"
},
{
"Name": "learning_rate",
"Value": "0.00001"
}
],
"SaveModelLimit": 1,
"Data": {
"TrainingSet": {
"TosBucket": "ark-auto-2100466578-cn-beijing-default",
"TosPaths": [
"model-customization-job-upload-set/1712561985763/test.jsonl"
]
}
},
"Status": {
"Phase": "Completed",
"PhaseTime": "2024-04-04T07:04:29Z"
},
"CreateTime": "2024-04-01T11:54:41Z",
"UpdateTime": "2024-04-04T07:04:29Z"
}
]
}
}
```