---
title: "학습 생성"
slug: "clovastudio-posttask"
tags: ["CLOVA Studio"]
updated: 2026-09-17T09:15:56Z
published: 2026-09-17T09:15:56Z
canonical: "api.ncloud-docs.com/clovastudio-posttask"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://api.ncloud-docs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 학습 생성

Classic/VPC 환경에서 이용 가능합니다.

학습을 생성합니다. 생성한 학습이 완료된 후 대화형 문장을 생성하는 [Chat Completions API](/docs/clovastudio-chatcompletions), [Chat Completions V3 API](/docs/clovastudio-chatcompletionsv3)를 호출하여 CLOVA Studio가 생성한 답변을 확인할 수 있습니다.

## 요청

요청 형식을 설명합니다. 요청 형식은 다음과 같습니다.

| 메서드 | URI |
| --- | --- |
| POST | /tuning/v2/tasks |

### 요청 헤더

CLOVA Studio API에서 공통으로 사용하는 헤더에 대한 정보는 [CLOVA Studio 요청 헤더](/docs/ai-naver-clovastudio-summary#%EC%9A%94%EC%B2%AD%ED%97%A4%EB%8D%94)를 참조해 주십시오.

### 요청 바디

요청 바디에 대한 설명은 다음과 같습니다.

| 필드 | 타입 | 필수 여부 | 설명 |
| --- | --- | --- | --- |
| `name` | String | Optional | 학습 이름 - 미 입력 시 학습 생성 날짜로 자동 생성 |
| `model` | String | Required | 튜닝에 사용할 모델 이름 |
| `tuningType` | String | Optional | 튜닝 기법 - `PEFT` (기본값) |
| `trainEpochs` | String | Optional | 모델을 학습한 에폭 수 - 1 ≤ `trainEpochs` ≤ 20 (기본값: 8) |
| `learningRate` | String | Optional | 학습률(튜닝 시 모델 파라미터를 재학습하는 수준 및 정도) - 1 ≤ `learningRate` ≤ 1.0E-6 (기본값: 1.0E-4) |
| `validationSplitRatio` | Double | Optional | 검증에 사용할 데이터셋 비율 - 0.0~0.1 (기본값: 0.0) |
| `loraR` | Integer | Optional | PEFT 학습 시 사용할 저차원 행렬의 차원 수 - 2~8 (기본값: 8) |
| `loraAlpha` | Integer | Optional | PEFT 학습 결과 반영 시 적용할 스케일 계수 - 2~512 (기본값: 64) |
| `trainingDatasetFilePath` | String | Conditional | 학습할 데이터셋 파일 경로 (버킷명을 제외한 버킷 내 경로) - Object Storage 서비스에 업로드한 경우, 필수 입력 |
| `trainingDatasetBucket` | String | Conditional | 학습할 데이터셋 파일을 업로드한 버킷 이름 - `trainingDatasetFilePath` 입력한 경우, 필수 입력 |
| `trainingDatasetAccessKey` | String | Conditional | 학습할 데이터셋 파일 접근을 위한 액세스 키 - `trainingDatasetFilePath` 입력한 경우, 필수 입력 |
| `trainingDatasetSecretKey` | String | Conditional | 학습할 데이터셋 파일 접근을 위한 시크릿 키 - `trainingDatasetFilePath` 입력한 경우, 필수 입력 |

### 요청 예시

요청 예시는 다음과 같습니다.

```
curl --location --request POST 'https://clovastudio.stream.ntruss.com/tuning/v2/tasks' \
--header 'Authorization: Bearer {API Key}' \
--header 'Content-Type: multipart/form-data' \
--header 'X-NCP-CLOVASTUDIO-REQUEST-ID: {Request ID}' 
--data '{
  "name": "generation_task",
  "model": "HCX-003",
  "tuningType": "PEFT",
  "trainEpochs": 8,
  "learningRate": 1e-5f,
  "trainingDatasetFilePath": "root_path/sub_path/file_name",
  "trainingDatasetBucket": "bucket_name",
  "trainingDatasetAccessKey": "access_key",
  "trainingDatasetSecretKey": "secret_key",
   "validationSplitRatio": 0,
   "loraR": 8,
   "loraAlpha": 64
}'
```

## 응답

응답 형식을 설명합니다.

### 응답 헤더

응답 헤더에 대한 설명은 다음과 같습니다.

| 헤더 | 필수 여부 | 설명 |
| --- | --- | --- |
| Content-Type | - | 응답 데이터의 형식 - `application/json` |

### 응답 바디

응답 바디에 대한 설명은 다음과 같습니다.

| 필드 | 타입 | 필수 여부 | 설명 |
| --- | --- | --- | --- |
| `status` | Object | - | [응답 상태](/docs/ai-naver-clovastudio-summary#%EC%9D%91%EB%8B%B5) 참조 |
| `result` | Object | - | 응답 결과 |
| `result.id` | String | - | 학습 아이디 |
| `result.name` | String | - | 학습 이름 |
| `result.model` | String | - | 튜닝 모델 이름 |
| `result.taskType` | String | - | 작업 유형 - GENERATION: 생성 (기본값) - CLASSIFICATION: 분류 |
| `result.trainEpochs` | Integer | - | 모델을 학습한 에폭 수 |
| `result.learningRate` | Double | - | 학습률(튜닝 시 모델 파라미터를 재학습하는 수준 및 정도) |
| `result.status` | String | - | 학습 진행 상태 - `WAIT` \| `RUNNING` \| `FAILED` \| `SUCCEEDED` - `WAIT`: 학습 대기 중 - `RUNNING`: 학습 중 - `FAILED`: 학습 중단 - `SUCCEEDED`: 학습 완료 |
| `result.statusInfo` | Array | - | 학습 진행 상태의 상세 정보: [statusInfo](/docs/clovastudio-posttask#statusInfo) |
| `result.createdClientType` | String | - | 학습을 요청한 클라이언트 유형 - `API` \| `WEB` - `API`: API 클라이언트 - `WEB`: 웹 클라이언트 |
| `result.createdDate` | String | - | 학습 생성 날짜 - ISO 8601 형식 |
| `result.updatedDate` | String | - | 학습 수정 날짜 - ISO 8601 형식 |

#### `statusInfo`

`statusInfo`에 대한 설명은 다음과 같습니다.

| 필드 | 타입 | 필수 여부 | 설명 |
| --- | --- | --- | --- |
| `label` | Array | - | - 학습 유형이 `CLASSIFICATION`인 경우: 사용자 데이터 라벨 표시 - 학습 유형이 `GENERATION`인 경우: `null` |
| `dataRows` | Integer | - | 데이터 수 |
| `numOfTokens` | Integer | - | 데이터 토큰 수 |
| `currStep` | Integer | - | 학습 현재 스텝 수 |
| `totalTrainSteps` | Integer | - | 학습 총 스텝 수 |
| `currEpoch` | Integer | - | 현재 에폭 |
| `totalTrainEpochs` | Integer | - | 전체 학습 에폭 |
| `estimatedTime` | Integer | - | 예상 소요 시간 - 1 에폭 평균 시간과 전체 학습 에폭 수를 곱해 도출 |
| `trainLoss` | Double | - | 학습 손실량 |
| `sendWeightSuccess` | Boolean | - | 학습 결과 저장 여부 - `false` \| `true` - `false`: 저장 안 함 - `true`: 저장 |
| `failureReason` | String | - | [학습 실패(`FAILED`) 이유](/docs/clovastudio-posttask#failureReasonmessage) |
| `message` | String | - | [학습 실패(`FAILED`) 이유의 상세 메시지](/docs/clovastudio-posttask#failureReasonmessage) |
| `endDatetime` | String | - | 학습 종료 날짜 - ISO 8601 형식 |

#### `failureReason`, `message`

학습 실패 이유(`failureReason`)와 학습 실패 이유의 상세 메시지(`message`)에 대한 설명은 다음과 같습니다.

| 학습 실패 이유 | 상세 메시지 | 설명 |
| --- | --- | --- |
| `file.extension` | `Unavailable file extension. Please check the file extension again.` | 요청한 `tuningType`에 부합하지 않는 데이터 파일 확장자 |
| `file.size` | `Exceeded the disk usage limit. Please check if the file size is {limit} or less.` | 학습 요청에서 기대하는 파일 크기 초과 |
| `file.encoding` | `Unsupported charset` | UTF8-sig 인코딩이 아닌 경우 |
| `file.format` | `Invalid json format. {reason}` | 데이터셋 파일(.json/.jsonl)의 디코딩이 불가능한 경우 |
| `file.format` | `Invalid dataset: required field empty. {column}` | 데이터셋 파일에 필수 column 누락 |
| `file.format` | `Invalid dataset: unexpected column. {column}` | 데이터셋 파일에 예상 밖의 column 존재 |
| `file.format` | `Invalid dataset: duplicate columns. {column}` | 데이터셋 파일에 대소문자 구별이 되지 않아 중복되는 column 발생 |
| `file.format` | `Invalid dataset: column order` | 데이터셋 파일의 column 순서가 System_Prompt, C_ID, T_ID, Text, Completion이 아닌 경우 |
| `file.format` | `Invalid dataset: {column}` | 데이터셋 파일의 C_ID 또는 T_ID가 0부터 시작해서 1씩 커지는 패턴을 만족하지 않거나 값이 비어 있는 경우 |
| `file.error` | - | 학습 시 파일 읽기 오류 |
| `file.noexist` | - | 데이터셋 파일이 존재하지 않는 경우 |
| `File not found` | - | Object Storage에서 파일을 찾을 수 없는 경우 |
| `resource.timeout` | - | GPU 확보 실패로 응답 시간 초과. 다시 시도 필요 |
| `clops.error` | - | 학습 중 CLOps 오류 |
| `train.unknown` | - | 학습 중 파일 관련 외 오류 |

### 응답 예시

응답 예시는 다음과 같습니다.

#### 성공

호출이 성공한 경우의 응답 예시는 다음과 같습니다.

```
{
    "status": {
        "code": "20000",
        "message": "OK"
    },
"result": {
    "id": "czf9fbky",
    "name": "230821-130704",
    "model": "HCX-003",
    "trainEpochs": 8,
    "learningRate": 1.0E-4,
    "status": "WAIT",
    "statusInfo": {
        "label": null,
        "dataRows": null,
        "numOfTokens": null,
        "currStep": null,
        "totalTrainSteps": null,
        "currEpoch": null,
        "totalTrainEpochs": null,
        "estimatedTime": null,
        "trainLoss": null,
        "sendWeightSuccess": null,
        "failureReason": null,
        "message":null,
        "endDatetime": null
        },
        "createdClientType": "API",
        "createdDate": "2023-08-21T13:07:06+0900",
        "updatedDate": "2023-08-21T13:07:06+0900"
    }
}
```

#### 실패

호출이 실패한 경우의 응답 예시는 다음과 같습니다.

- [클라이언트 공통 오류 문제(4xx)](/docs/clovastudio-troubleshoot-c4xx)
- [서버 공통 오류 문제(5xx)](/docs/clovastudio-troubleshoot-c5xx)