Chat Completions
- 인쇄
- PDF
Chat Completions
- 인쇄
- PDF
기사 요약
이 요약이 도움이 되었나요?
의견을 보내 주셔서 감사합니다.
Classic/VPC 환경에서 이용 가능합니다.
HyperCLOVA X 모델을 활용하여 대화형 문장을 생성합니다.
요청
요청 형식을 설명합니다. 요청 형식은 다음과 같습니다.
| 메서드 | URI |
|---|---|
| POST |
|
요청 헤더
헤더에 대한 설명은 다음과 같습니다.
| 헤더 | 필수 여부 | 설명 |
|---|---|---|
| Authorization | Required | 인증을 위한 API 키 (예: Bearer nv-***********) |
| Content-Type | Required | application/json |
| Accept | Conditional | text/event-stream |
| X-NCP-CLOVASTUDIO-REQUEST-ID | Optional | 각 요청에 대한 요청 아이디 |
참고
응답 결과는 기본적으로 JSON 형태로 반환되지만, Accept를 text/event-stream으로 지정 시 응답 결과를 스트림 형태로 반환합니다.
요청 경로 파라미터
파라미터에 대한 설명은 다음과 같습니다.
| 필드 | 타입 | 필수 여부 | 설명 |
|---|---|---|---|
| modelName | string | Y | 사용할 모델 이름 <예시> HCX-003 |
튜닝 학습을 한 작업을 이용할 경우, 파라미터에 대한 설명은 다음과 같습니다.
| 필드 | 타입 | 필수 여부 | 설명 |
|---|---|---|---|
| taskId | string | Y | 학습 아이디 |
참고
호출 시 필요한 taskID는 학습 생성 API의 응답 바디에서 확인할 수 있습니다.
요청 바디
바디에 대한 설명은 다음과 같습니다.
| 필드 | 타입 | 필수 여부 | 설명 |
|---|---|---|---|
| messages | object (ChatMessage) | Y | 대화 메시지 |
| ChatMessages.role | enum | Y | 대화 메시지의 역할 |
| ChatMessages.content | string | Y | 대화 메시지 내용 |
| temperature | double | N | 생성 토큰에 대한 다양성 정도(설정값이 높을수록 다양한 문장 생성) |
| topK | int | N | 생성 토큰 후보군에서 확률이 높은 k개를 후보로 지정하여 샘플링 |
| topP | double | N | 생성 토큰 후보군을 누적 확률을 기반으로 샘플링 |
| repeatPenalty | double | N | 같은 토큰을 생성하는 것에 대한 패널티 정도(설정값이 높을수록 같은 결괏값을 반복 생성할 확률 감소) |
| stopBefore | string | N | 토큰 생성 중단 문자 |
| maxTokens | int | N | 최대 생성 토큰 수 |
| includeAiFilters | boolean | N | 생성된 결괏값에 대해 욕설, 비하/차별/혐오, 성희롱 /음란 등 카테고리별로 해당하는 정도 |
| seed | int | N | 모델 반복 실행 시 결괏값의 일관성 수준 조정 |
참고
일부 필드 입력 시 다음 내용을 확인해 주십시오.
요청 구문
구문 예시는 다음과 같습니다.
curl --location --request POST 'https://clovastudio.stream.gov-ntruss.com/testapp/v1/chat-completions/HCX-003' \
--header 'Authorization: Bearer <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" : 256,
"temperature" : 0.5,
"messages" : [ {
"role" : "system",
"content" : "시스템 프롬프트"
}, {
"role" : "user",
"content" : "사용자 입력"
}, {
"role" : "assistant",
"content" : "어시스턴트 "
} ],
"stopBefore" : [ ],
"repeatPenalty" : 5.0,
"topP" : 0.8
}'
응답
응답 형식을 설명합니다.
응답 헤더
헤더에 대한 설명은 다음과 같습니다.
| 헤더 | 필수 여부 | 설명 |
|---|---|---|
| Content-Type | - | application/json |
응답 바디
바디에 대한 설명은 다음과 같습니다.
| 필드 | 타입 | 필수 여부 | 설명 |
|---|---|---|---|
| result | - | - | 응답 결과 |
| result.message | array | - | 대화 메시지 |
| result.message.role | enum | - | 대화 메시지의 역할 |
| result.message.content | string | - | 대화 메시지 내용 |
| result.stopReason | enum | - | 토큰 생성 중단 이유(일반적으로 마지막 이벤트에 전달) |
| result.inputLength | int | - | 입력 토큰 수(과금 기준으로 end of turn과 같은 특수 토큰도 포함) |
| result.outputLength | int | - | 응답 토큰 수 |
| result.seed | int | - | 입력 seed 값 (0 입력 또는 미입력 시 랜덤 값 반환) |
| aiFilter | array | - | AI Filter 결과 |
| aiFilter.groupName | string | - | AI Filter 카테고리 그룹 이름 |
| aiFilter.name | string | - | AI Filter 카테고리 세부 이름 |
| aiFilter.score | string | - | AI Filter 점수 |
| aiFilter.score | string | - | 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 | - | AI Filter 카테고리 그룹 이름 |
| aiFilter.name | string | - | AI Filter 카테고리 세부 이름 |
| aiFilter.score | string | - | AI Filter 점수 |
| aiFilter.result | string | - | 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": “녕”}}
실패
호출이 실패한 경우의 구문 예시는 다음과 같습니다.
이 문서가 도움이 되었습니까?