Chat Completions

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

대화형 문장을 생성하는 HCX-003 모델과 경량화된 HCX-DASH-001 모델을 이용할 수 있는 Chat Completions에 대해 설명합니다.

요청

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

메서드	URI
POST	/v1/chat-completions/{modelName} 모델을 사용하여 문장 생성 /v1/tasks/{taskId}/chat-completions /v2/tasks/{taskId}/chat-completions 튜닝 학습한 작업을 사용하여 문장 생성

요청 헤더

CLOVA Studio API에서 공통으로 사용하는 헤더에 대한 정보는 CLOVA Studio 요청 헤더를 참조해 주십시오.

요청 경로 파라미터

요청 경로 파라미터에 대한 설명은 다음과 같습니다.

필드	타입	필수 여부	설명
`modelName`	String	Conditional	모델 이름 모델을 사용하여 문장 생성을 하려는 경우 <예시> `HCX-003`
`taskId`	String	Conditional	학습 아이디 튜닝 학습한 작업을 사용하여 문장 생성을 하려는 경우 학습 생성 API 참조

요청 바디

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

필드	타입	필수 여부	설명
`messages`	Array	Required	대화 메시지: messages
`temperature`	Double	Optional	생성 토큰에 대한 다양성 정도(설정값이 높을수록 다양한 문장 생성) 0.00 ＜ `temperature` ≤ 1.00 (기본값: 0.50) 소수점 둘째 자리까지 표기
`topK`	Integer	Optional	생성 토큰 후보군에서 확률이 높은 K개를 후보로 지정하여 샘플링 0 ≤ `topK` ≤ 128 (기본값: 0)
`topP`	Double	Optional	생성 토큰 후보군을 누적 확률을 기반으로 샘플링 0.00 ＜ `topP` ≤ 1.00 (기본값: 0.80) 소수점 둘째 자리까지 표기
`repeatPenalty`	Double	Optional	같은 토큰을 생성하는 것에 대한 패널티 정도(설정값이 높을수록 같은 결괏값을 반복 생성할 확률 감소) 0.0 ＜ `repeatPenalty` ≤ 10.0 (기본값: 5.0)
`stopBefore`	Array	Optional	토큰 생성 중단 문자 [](기본값)
`maxTokens`	Integer	Optional	최대 생성 토큰 수 0 ＜ `maxTokens` ≤ 4096 (기본값: 100)
`includeAiFilters`	Boolean	Optional	AI 필터(생성된 결괏값에 대해 욕설, 비하/차별/혐오, 성희롱/음란 등 카테고리별로 해당하는 정도) 결과 표시 여부 `false` (기본값) \| `true` `false`: 표시 안 함 `true`: 표시
`seed`	Integer	Optional	모델 반복 실행 시 결괏값의 일관성 수준 조정 0: 일관성 수준 랜덤 적용 (기본값) 1 ≤ `seed` ≤ 4294967295: 일관되게 생성하고자 하는 결괏값의 `seed` 값 또는 사용자가 지정하고자 하는 `seed` 값

참고

일부 필드 입력 시 다음 내용을 확인해 주십시오.

HCX-003
- 입력 토큰과 출력 토큰의 합은 8,192 토큰을 초과할 수 없습니다.
- 입력 토큰은 최대 7,600 토큰까지 가능합니다.
- 모델에 요청할 출력 토큰(maxTokens)은 최대 4,096 토큰까지 가능합니다.
HCX-DASH-001
- 입력 토큰과 출력 토큰의 합은 4,096 토큰을 초과할 수 없습니다.
- 입력 토큰은 최대 3,500 토큰까지 가능합니다.
- 모델에 요청할 출력 토큰(maxTokens)은 최대 4,096 토큰까지 가능합니다.

`messages`

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

필드	타입	필수 여부	설명
`role`	Enum	Required	대화 메시지 역할 `system` \| `user` \| `assistant` `system`: 역할을 규정하는 지시문 `user`: 사용자의 발화 또는 질문 `assistant`: 사용자의 발화 또는 질문에 대한 답변
`content`	String	Required	대화 메시지 내용

요청 예시

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

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`

응답 바디

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

필드	타입	필수 여부	설명
`status`	Object	-	응답 상태 참조
`result`	Object	-	응답 결과
`result.message`	Object	-	대화 메시지
`result.message.role`	Enum	-	대화 메시지 역할 `system` \| `user` \| `assistant` `system`: 역할을 규정하는 지시문 `user`: 사용자의 발화 또는 질문 `assistant`: 모델의 답변
`result.message.content`	String	-	대화 메시지 내용
`result.stopReason`	Enum	-	결괏값 생성 중단 이유 `length` \| `end_token` \| `stop_before` `length`: 길이 제한 `end_token`: 토큰 수 제한 `stop_before`: 모델이 자체적으로 출력을 종료 답변 생성 중 `stopBefore`에 지정한 문자 출현
`result.inputLength`	Integer	-	입력 토큰 수(과금 기준으로 end of turn과 같은 특수 토큰도 포함)
`result.outputLength`	Integer	-	응답 토큰 수
`result.seed`	int	-	입력 seed 값(0 입력 또는 미입력 시 랜덤 값 반환)
`result.aiFilter`	Array	-	AI 필터 결과: aiFilter

`aiFilter`

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

필드	타입	필수 여부	설명
`groupName`	String	-	AI 필터 카테고리 `curse` \| `unsafeContents` `curse`: 비하, 차별, 혐오 및 욕설 `unsafeContents`: 성희롱, 음란
`name`	String	-	AI 필터 세부 카테고리 `discrimination` \| `insult` \| `sexualHarassment` `discrimination`: 비하, 차별, 혐오 `insult`: 욕설 `sexualHarassment`: 성희롱, 음란
`score`	String	-	AI 필터 점수 `-1` \| `0` \| `1` \| `2` `-1`: AI 필터 오류 발생 `0`: 대화 메시지에 민감/위험 표현 포함 가능성 높음 `1`: 대화 메시지에 민감/위험 표현 포함 가능성 있음 `2`: 대화 메시지에 민감/위험 표현 포함 가능성 낮음
`result`	String	-	AI 필터 정상 작동 여부 `OK` \| `ERROR` `OK`: 정상 작동 `ERROR`: 오류 발생

참고

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`	Object	-	대화 메시지
`message.role`	Enum	-	대화 메시지 역할 `system` \| `user` \| `assistant` `system`: 역할을 규정하는 지시문 `user`: 사용자의 발화 또는 질문 `assistant`: 모델의 답변
`message.content`	String	-	대화 메시지 내용
`stopReason`	Enum	-	결괏값 생성 중단 이유 `length` \| `end_token` \| `stop_before` `length`: 길이 제한 `end_token`: 토큰 수 제한 `stop_before`: 답변 생성 중 `stopBefore`에 지정한 문자 출현
`inputLength`	Integer	-	입력 토큰 수(과금 기준으로 end of turn과 같은 특수 토큰도 포함)
`outputLength`	Integer	-	응답 토큰 수(과금 기준으로 end of turn과 같은 특수 토큰도 포함)
`aiFilter`	Array	-	AI 필터 결과: aiFilter

StreamingChatCompletionsTokenEvent

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

필드	타입	필수 여부	설명
`id`	String	-	요청을 식별하는 이벤트 아이디
`message`	Object	-	대화 메시지
`message.role`	Enum	-	대화 메시지 역할 `system` \| `user` \| `assistant` `system`: 역할을 규정하는 지시문 `user`: 사용자의 발화 또는 질문 `assistant`: 모델의 답변
`message.content`	String	-	대화 메시지 내용
`inputLength`	Integer	-	입력 토큰 수(과금 기준으로 end of turn과 같은 특수 토큰도 포함)
`outputLength`	Integer	-	응답 토큰 수(과금 기준으로 end of turn과 같은 특수 토큰도 포함)
`stopReason`	Enum	-	결괏값 생성 중단 이유 `length` \| `end_token` \| `stop_before` `length`: 길이 제한 `end_token`: 토큰 수 제한 `stop_before`: 모델이 정상적으로 생성 완료 답변 생성 중 `stopBefore`에 지정한 문자 출현

ErrorEvent

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

필드	타입	필수 여부	설명
`status`	Object	-	응답 상태 참조

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": “녕”}}

실패

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