학습 생성

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

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

요청

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

메서드	URI
POST	/tuning/v2/tasks

요청 헤더

요청 헤더에 대한 설명은 다음과 같습니다.

필드	필수 여부	설명
`Authorization`	Required	인증을 위한 API 키 <예시> `Bearer nv-************`
`X-NCP-CLOVASTUDIO-REQUEST-ID`	Optional	요청에 대한 아이디
`Content-Type`	Required	요청 데이터의 형식 `application/json`

요청 바디

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

필드	타입	필수 여부	설명
`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)
`trainingDatasetFilePath`	String	Conditional	학습할 데이터셋 파일 경로 (버킷명을 제외한 버킷 내 경로) Object Storage 서비스에 업로드한 경우 필수 입력
`trainingDatasetBucket`	String	Conditional	학습할 데이터셋 파일을 업로드한 버킷 이름 `trainingDatasetFilePath` 입력한 경우 필수 입력
`trainingDatasetAccessKey`	String	Conditional	학습할 데이터셋 파일 접근을 위한 Access key `trainingDatasetFilePath` 입력한 경우 필수 입력
`trainingDatasetSecretKey`	String	Conditional	학습할 데이터셋 파일 접근을 위한 Secret key `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"
}'

응답

응답 형식을 설명합니다.

응답 헤더

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

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

응답 바디

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

필드	타입	필수 여부	설명
`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	-	학습 진행 상태의 상세 정보
`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`) 이유
`message`	String	-	학습 실패(`FAILED`) 이유의 상세 메시지
`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"
    }
}

실패

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