- 인쇄
- PDF
학습 모델 Chat Completions
- 인쇄
- PDF
Classic/VPC 환경에서 이용 가능합니다.
학습 모델을 활용하여 대화형 문장을 생성합니다. 만약 원하는 대화형 문장이 생성되지 않았다면 데이터셋을 정제하여 학습을 다시 수행하거나, 요청 파라미터 값을 수정한 후 다시 호출하여 의도했던 결괏값에 최적으로 수렴하도록 조정합니다.
요청
요청 형식을 설명합니다. 요청 형식은 다음과 같습니다.
메서드 | URI |
---|---|
POST | /v1/tasks/{taskId}/chat-completions |
헤더
헤더에 대한 설명은 다음과 같습니다.
헤더 | 필수 여부 | 설명 |
---|---|---|
X-NCP-CLOVASTUDIO-API-KEY | Y | 테스트 앱이나 서비스 앱 생성 시 발급 받은 API KEY |
X-NCP-APIGW-API-KEY | Y | 테스트 앱이나 서비스 앱 생성 시 발급 받은 API Gateway KEY |
X-NCP-CLOVASTUDIO-REQUEST-ID | N | 각 요청에 대한 요청 아이디 |
Content-Type | Y | application/json |
Accept | N | text/event-stream |
- 응답 결과는 기본적으로 JSON 형태로 반환되지만,
Accept
를text/event-stream
으로 지정 시 응답 결과를 스트림 형태로 반환합니다. - 응답 스트림 이용 시 API URL은
https://clovastudio.stream.ntruss.com/
으로 사용해 주십시오.
경로 파라미터
파라미터에 대한 설명은 다음과 같습니다.
필드 | 타입 | 필수 여부 | 설명 |
---|---|---|---|
taskId | string | Y | 학습 아이디 |
바디
요청 바디의 각 필드에 대한 설명은 다음과 같습니다.
필드 | 타입 | 필수 여부 | 설명 |
---|---|---|---|
messages | array | Y | 대화 메시지 |
messages.role | enum | Y | 대화 메시지의 역할 |
messages.content | string | Y | 대화 메시지 내용 |
temperature | double | N | 생성 토큰에 대한 다양성 정도(설정값이 높을수록 다양한 문장 생성) |
topK | int | N | 생성 토큰 후보군에서 확률이 높은 k개를 후보로 지정하여 샘플링 |
topP | double | N | 생성 토큰 후보군을 누적 확률을 기반으로 샘플링 |
repeatPenalty | double | N | 같은 토큰을 생성하는 것에 대한 패널티 정도(설정값이 높을수록 같은 결괏값을 반복 생성할 확률 감소) |
stopBefore | string | N | 토큰 생성 중단 문자 |
maxTokens | int | N | 최대 생성 토큰 수 |
messages
에서 입력한 토큰 수와 maxTokens
에서 입력한 토큰 수의 합은 4096 토큰을 초과할 수 없습니다. messages
에서 입력한 토큰 수는 Chat Completions 토큰 계산 API를 호출하여 확인할 수 있습니다. Chat Completions 토큰 계산 API 명세는 CLOVA Studio 웹에서 확인해 주십시오.
구문
구문 예시는 다음과 같습니다.
curl --location --request POST 'https://clovastudio.stream.ntruss.com/testapp/v1/tasks/{taskId}/chat-completions' \
--header 'X-NCP-CLOVASTUDIO-API-KEY: <X-NCP-CLOVASTUDIO-API-KEY>' \
--header 'X-NCP-APIGW-API-KEY: <X-NCP-APIGW-API-KEY>' \
--header 'X-NCP-CLOVASTUDIO-REQUEST-ID: <X-NCP-CLOVASTUDIO-REQUEST-ID>' \
--header 'Content-Type: application/json' \
--header 'Accept: text/event-stream' \
--data '{
"topK" : 0,
"includeAiFilters" : true,
"maxTokens" : 100,
"temperature" : 0.3,
"messages" : [ {
"role" : "user",
"content" : "오늘 날씨 어때?"
}, {
"role" : "assistant",
"content" : "폭풍전야입니다."
}, {
"role" : "user",
"content" : "내일 날씨는 어때?"
} ],
"stopBefore" : [ ],
"repeatPenalty" : 1,
"topP" : 0.8
}'
응답
응답 형식을 설명합니다.
헤더
헤더에 대한 설명은 다음과 같습니다.
헤더 | 필수 여부 | 설명 |
---|---|---|
Content-Type | - | application/json |
바디
바디의 각 필드에 대한 설명은 다음과 같습니다.
필드 | 타입 | 필수 여부 | 설명 |
---|---|---|---|
result | - | - | 응답 결과 |
result.message | array | Y | 대화 메시지 |
result.message.role | enum | Y | 대화 메시지의 역할 |
result.message.content | string | Y | 대화 메시지 내용 |
result.stopReason | enum | - | 토큰 생성 중단 이유(일반적으로 마지막 이벤트에 전달) |
result.inputLength | int | - | 입력 토큰 수(과금 기준으로 end of turn과 같은 특수 토큰도 포함) |
result.outputLength | int | - | 응답 토큰 수 |
aiFilter | array | - | AI Filter 결과 |
aiFilter.groupName | string | Y | AI Filter 카테고리 그룹 이름 |
aiFilter.name | string | Y | AI Filter 카테고리 세부 이름 |
aiFilter.score | string | Y | AI Filter 점수 |
AI Filter는 최대 500자까지 분석할 수 있습니다. 단, 분석 대상 텍스트에 비정상적인 형식, 이모티콘, 특수 문자 등이 많은 경우, 정상적으로 분석되지 않을 수 있습니다.
구문
구문 예시는 다음과 같습니다.
{
"status": {
"code": "20000",
"message": "OK"
},
"result": {
"message": {
"role": "assistant",
"content": "문구: 오늘 하루 있었던 일들을 기록하며, 내일을 준비하세요. 다이어리는 당신의 삶을 더욱 풍요롭게 만들어 줄 것입니다.\n"
},
"stopReason": "LENGTH",
"inputLength": 100,
"outputLength": 10,
"aiFilter": [
{
"groupName": "curse",
"name": "insult",
"score": "1"
},
{
"groupName": "curse",
"name": "discrimination",
"score": "0"
},
{
"groupName": "unsafeContents",
"name": "sexualHarassment",
"score": "2"
}
]
}
}
응답 스트림
생성되는 토큰을 하나씩 출력하도록 토큰 스트리밍을 사용할 수 있습니다. 토큰 스트리밍 형식을 설명합니다.
헤더
헤더에 대한 설명은 다음과 같습니다.
헤더 | 필수 여부 | 설명 |
---|---|---|
Accept | - | text/event-stream |
바디
바디에 대한 설명은 다음과 같습니다.
StreamingChatCompletionsResultEvent
StreamingChatCompletionsResultEvent에 대한 설명은 다음과 같습니다.
필드 | 타입 | 필수 여부 | 설명 |
---|---|---|---|
message | array | - | 대화 메시지 |
message.role | enum | - | 대화 메시지의 역할 |
message.content | string | - | 대화 메시지 내용 |
stopReason | enum | - | 토큰 생성 중단 이유(일반적으로 마지막 이벤트에 전달) |
inputLength | int | - | 입력 토큰 수(과금 기준으로 end of turn과 같은 특수 토큰도 포함) |
outputLength | int | - | 응답 토큰 수 |
aiFilter | array | - | AI Filter 결과 |
aiFilter.groupName | string | Y | AI Filter 카테고리 그룹 이름 |
aiFilter.name | string | Y | AI Filter 카테고리 세부 이름 |
aiFilter.score | string | Y | AI Filter 점수 |
StreamingChatCompletionsTokenEvent
StreamingChatCompletionsResultEvent에 대한 설명은 다음과 같습니다.
필드 | 타입 | 필수 여부 | 설명 |
---|---|---|---|
id | string | - | 요청을 식별하는 이벤트 아이디 |
message | array | - | 대화 메시지 |
message.role | enum | - | 대화 메시지의 역할 |
message.content | string | - | 대화 메시지 내용 |
inputLength | int | - | 입력 토큰 수(과금 기준으로 end of turn과 같은 특수 토큰도 포함) |
stopReason | enum | - | 토큰 생성 중단 이유(일반적으로 마지막 이벤트에 전달) |
ErrorEvent
ErrorEvent에 대한 설명은 다음과 같습니다.
필드 | 타입 | 필수 여부 | 설명 |
---|---|---|---|
status | status | - | 응답 상태 |
SignalEvent
SignalEvent에 대한 설명은 다음과 같습니다.
필드 | 타입 | 필수 여부 | 설명 |
---|---|---|---|
data | string | - | 전달할 시그널 데이터 정보 |
구문
구문 예시는 다음과 같습니다.
id: aabdfe-dfgwr-edf-hpqwd-f2asd-g
event: token
data: {"message": {"role": "assistant", "content": “안”}}
id: aabdfe-dfgwr-edf-hpqwd-f1asd-g
event: result
data: {"message": {"role": "assistant", "content": “녕 }}