Korean

Chat Completions

인쇄
공유
PDF

Chat Completions

인쇄
공유
PDF

기사 요약

이 요약이 도움이 되었나요?

의견을 보내 주셔서 감사합니다.

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

HyperCLOVA X 모델을 사용하여 대화형 문장을 생성합니다.

요청

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

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

요청 헤더

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

헤더	필수 여부	설명
`X-NCP-CLOVASTUDIO-API-KEY`	Required	테스트 앱이나 서비스 앱 생성 시 발급 받은 API KEY
`X-NCP-APIGW-API-KEY`	Required	테스트 앱이나 서비스 앱 생성 시 발급 받은 API Gateway KEY
`X-NCP-CLOVASTUDIO-REQUEST-ID`	Optional	요청에 대한 아이디
`Content-Type`	Required	요청 데이터의 형식 `application/json`
`Accept`	Conditional	응답 데이터의 형식 `text/event-stream`

참고

응답 결과는 기본적으로 JSON 형태로 반환되지만, Accept를 text/event-stream으로 지정 시 응답 결과를 스트림 형태로 반환합니다.
응답 스트림 이용 시 API URL은 https://clovastudio.stream.ntruss.com/으로 사용해 주십시오.

요청 경로 파라미터

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

필드	타입	필수 여부	설명
`modelName`	String	Conditional	모델 이름 모델을 사용하여 문장 생성을 하려는 경우 <예시> `HCX-003`
`taskId`	String	Conditional	학습 아이디 튜닝 학습한 작업을 사용하여 문장 생성을 하려는 경우 학습 생성 API의 응답 바디에서 확인 가능

요청 바디

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

필드	타입	필수 여부	설명
`messages`	Array	Required	대화 메시지
`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` ≤ 2048 (기본값: 100)
`includeAiFilters`	Boolean	Optional	AI 필터(생성된 결괏값에 대해 욕설, 비하/차별/혐오, 성희롱/음란 등 카테고리별로 해당하는 정도) 결과 표시 여부 `false` (기본값) \| `true` `false`: 표시 안 함 `true`: 표시
`seed`	Integer	Optional	모델 반복 실행 시 결괏값의 일관성 수준 조정 0: 일관성 수준 랜덤 적용 (기본값) 1 ≤ `seed` ≤ 4294967295: 일관되게 생성하고자 하는 결괏값의 `seed` 값 또는 사용자가 지정하고자 하는 `seed` 값

참고

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

messages: 입력한 토큰 수와 maxTokens에서 입력한 토큰 수의 합은 4096 토큰을 초과할 수 없습니다. messages에서 입력한 토큰 수는 Chat Completions 토큰 계산 API를 호출하여 확인할 수 있습니다.
seed: 사용 시 모델을 반복 실행하더라도 일관성 있는 결괏값을 얻을 확률을 높일 수 있습니다. 하지만 결괏값의 완전성은 보장하지 않으며, 다른 조건이 변경되면 결과가 미세하게 달라질 수 있습니다.

`messages`

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

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

요청 예시

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

curl --location --request POST 'https://clovastudio.stream.ntruss.com/testapp/v1/chat-completions/HCX-003' \
--header 'X-NCP-CLOVASTUDIO-API-KEY: {CLOVA Studio API Key}' \
--header 'X-NCP-APIGW-API-KEY: {API Gateway API Key}' \
--header 'X-NCP-CLOVASTUDIO-REQUEST-ID: {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" : "test"
  }, {
    "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에 대한 설명은 다음과 같습니다.

필드	타입	필수 여부	설명
`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	-	응답 토큰 수
`aiFilter`	Array	-	AI 필터 결과

StreamingChatCompletionsTokenEvent

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

필드	타입	필수 여부	설명
`id`	String	-	요청을 식별하는 이벤트 아이디
`message`	Object	-	대화 메시지
`message.role`	Enum	-	대화 메시지 역할 `system` \| `user` \| `assistant` `system`: 역할을 규정하는 지시문 `user`: 사용자의 발화 또는 질문 `assistant`: 모델의 답변
`message.content`	String	-	대화 메시지 내용
`inputLength`	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": “녕”}}

실패

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

이 문서가 도움이 되었습니까?

What's Next

Completions

요청
응답
응답 스트림

태그

CLOVA Studio