--- title: "학습 생성" slug: "clovastudio-posttask" tags: ["AI", "CLOVA Studio", "HyperCLOVA"] updated: 2026-10-22T10:46:35Z published: 2026-10-22T10:46:35Z canonical: "api-gov.ncloud-docs.com/clovastudio-posttask" --- > ## Documentation Index > Fetch the complete documentation index at: https://api-gov.ncloud-docs.com/llms.txt > Use this file to discover all available pages before exploring further. # 학습 생성 Classic/VPC 환경에서 이용 가능합니다. 생성한 학습이 완료된 후 대화형 문장을 생성하는 API를 호출하여 CLOVA Studio가 생성한 답변을 확인할 수 있습니다. ## 요청 요청 형식을 설명합니다. 요청 형식은 다음과 같습니다. | 메서드 | URI | | --- | --- | | POST | /tuning/v2/tasks | ### 요청 헤더 헤더에 대한 설명은 다음과 같습니다. | 필드 | 필수 여부 | 설명 | | --- | --- | --- | | Authorization | Required | 인증을 위한 API 키 <예시> `Bearer nv-***********` | | Content-Type | Required | application/json | | X-NCP-CLOVASTUDIO-REQUEST-ID | Optional | 각 요청에 대한 요청 아이디 | ### 요청 바디 바디에 대한 설명은 다음과 같습니다. | 필드 | 타입 | 필수 여부 | 설명 | | --- | --- | --- | --- | | name | string | N | 학습 이름 (기본값: 학습 생성 날짜) | | model | string | Y | 튜닝 모델 이름 | | tuningType | string | N | 튜닝 기법 - PEFT (기본값) | | taskType | string | N | 학습 유형 - GENERATION: 생성 (기본값) - CLASSIFICATION: 분류 | | trainEpochs | Integer | N | 모델을 학습한 에폭 수 - 1~20 (기본값: 8) | | learningRate | Double | N | 학습률: 튜닝 시 모델 파라미터를 재학습하는 수준이나 정도 - 1~1.0E-6 (기본값: 1.0E-4) | | validationSplitRatio | Double | N | 검증에 사용할 데이터셋 비율 - 0.0~0.1 (기본값: 0.0) | | loraR | Integer | N | PEFT 학습 시 사용할 저차원 행렬의 차원 수 - 2~8 (기본값: 8) | | loraAlpha | Integer | N | PEFT 학습 결과 반영 시 적용할 스케일 계수 - 2~512 (기본값: 64) | | trainingDatasetUri | string | Y | 학습할 대용량 데이터셋 파일이 업로드 되어 있는 OBS 접근 URI, OBS 리전에 맞는 공인 도메인 입력 (Object Storage에 업로드한 경우) - 수도권: kr.object.gov-ncloudstorage.com - 남부: krs.object.gov-ncloudstorage.com | | trainingDatasetBucket | string | Y | 학습할 데이터셋 파일이 업로드되어 있는 버킷 이름 (trainingDatasetUri 입력 시 필수 입력) | | trainingDatasetFilePath | string | Y | 학습할 데이터셋 파일 경로, 버킷명 하위 경로 (trainingDatasetUri 입력 시 필수 입력) | | trainingDatasetAccessKey | string | Y | 학습할 데이터셋 파일 접근을 위한 액세스 키 (trainingDatasetUri 입력 시 필수 입력) | | trainingDatasetSecretKey | string | Y | 학습할 데이터셋 파일 접근을 위한 시크릿 키 (trainingDatasetUri 입력 시 필수 입력) | ### 요청 구문 구문 예시는 다음과 같습니다. ``` curl --location --request POST 'clovastudio.stream.gov-ntruss.com/tuning/v2/tasks' \ --header 'Content-Type: multipart/form-data' \ --header 'Authorization: Bearer ' \ --header 'X-NCP-CLOVASTUDIO-REQUEST-ID: ' \ --data '{ "name": "generation_task", "model": "HCX-003", "taskType": "GENERATION", "trainEpochs": 8, "learningRate": 1e-5f, "trainingDatasetUri" : "kr.object.gov-ncloudstorage.com" "trainingDatasetBucket": "bucket_name", "trainingDatasetFilePath": "root_path/sub_path/file_name", "trainingDatasetAccessKey": "access_key", "trainingDatasetSecretKey": "secret_key", "validationSplitRatio": 0, "loraR": 8, "loraAlpha": 64 } ``` ## 응답 응답 형식을 설명합니다. ### 응답 헤더 헤더에 대한 설명은 다음과 같습니다. | 헤더 | 필수 여부 | 설명 | | --- | --- | --- | | Content-Type | - | application/json | ### 응답 바디 바디에 대한 설명은 다음과 같습니다. | 필드 | 타입 | 필수 여부 | 설명 | | --- | --- | --- | --- | | result | object | - | 응답 결과 | | result.id | string | - | 학습 아이디 | | result.name | string | - | 학습 이름 | | result.model | string | - | 튜닝 모델 이름 | | result.method | string | - | 튜닝 기법 - LoRA | | result.taskType | string | - | 학습 유형 - GENERATION: 생성 - CLASSIFICATION: 분류 | | result.trainEpochs | integer | - | 모델을 학습한 에폭 수 | | result.learningRate | double | - | 학습률: 튜닝 시 모델 파라미터를 재학습하는 수준이나 정도 | | result.status | string | - | 학습 진행 상태 - WAIT - RUNNING - FAILED - SUCCEEDED | | result.statusInfo | array | - | 학습 진행 상태 상세 정보 | | result.statusInfo.label | array | - | 학습 유형이 classification인 경우, 사용자 데이터 라벨 (학습 유형이 GENERATION인 경우, null) | | result.statusInfo.dataRows | int | - | 데이터 수 | | result.statusInfo.numOfTokens | int | - | 데이터 토큰 수 | | result.statusInfo.currStep | int | - | 학습 현재 스텝 수 | | result.statusInfo.totalTrainSteps | int | - | 학습 총 스텝 수 | | result.statusInfo.currEpoch | int | - | 현재 에폭 | | result.statusInfo.totalTrainEpochs | int | - | 전체 학습 에폭 | | result.statusInfo.estimatedTime | int | - | 예상 소요 시간 (평균 1 에폭 시간 * 전체 학습 에폭) | | result.statusInfo.trainLoss | double | - | 학습 손실값 | | result.statusInfo.validLoss | double | - | 검증 손실값 | | result.statusInfo.sendWeightSuccess | boolean | - | 학습 결과물 저장 여부 | | result.statusInfo.endDatetime | string | - | 학습 종료 날짜 | | result.statusInfo.failureReason | string | - | [학습 진행 상태가 `FAILED`인 이유](/docs/clovastudio-posttask#failureReason%EC%83%81%EC%84%B8%EB%A9%94%EC%8B%9C%EC%A7%80) | | result.statusInfo.message | string | - | [`failureReason` 상세 메시지](/docs/clovastudio-posttask#failureReason%EC%83%81%EC%84%B8%EB%A9%94%EC%8B%9C%EC%A7%80) | | result.createdClientType | string | - | 학습을 요청한 클라이언트 유형 - API: API 클라이언트 - WEB: 웹 클라이언트 | | result.createdDate | string | - | 학습 생성 날짜 (ISO 8601 형식) | | result.updatedDate | string | - | 학습 수정 날짜 (ISO 8601 형식) | #### failureReason 상세 메시지 학습 실패 이유(`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 (or t_id)가 0부터 시작해서 1씩 늘어나는 패턴을 만족하지 않거나 값이 비어 있는 경우 | | file.error | - | 파일 읽기 오류 | | resource.timeout | - | GPU 확보 실패로 응답 시간 초과. 다시 시도 필요 | | clops.error | - | 학습 중 CLOps 오류 | | train.unknown | - | 학습 중 파일 관련 외 오류 | ### 응답 구문 구문 예시는 다음과 같습니다. #### 성공 호출이 성공한 경우의 구문 예시는 다음과 같습니다. ``` { "status": { "code": "20000", "message": "OK" }, "result": { "id": "czf9fbky", "name": "230821-130704", "model": "HCX-003", "method": "LoRA", "taskType": "GENERATION", "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)