Chat Completions

인쇄
공유
PDF

Chat Completions

인쇄
공유
PDF

기사 요약

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

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

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

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

요청

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

메서드	URI
POST	/v1/chat-completions/{modelName}

참고

튜닝 학습을 한 작업을 이용할 경우, /v1/tasks/{taskId}/chat-completions 형태로 호출해야 합니다. 테스트 앱 생성 후 호출할 수 있는 API를 확인하실 수 있습니다.

요청 헤더

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

헤더	필수 여부	설명
X-NCP-CLOVASTUDIO-API-KEY	Y	테스트 앱이나 서비스 앱 생성 시 발급 받은 API KEY
X-NCP-CLOVASTUDIO-REQUEST-ID	N	각 요청에 대한 요청 아이디
Content-Type	Y	application/json
Accept	N	text/event-stream

참고

응답 결과는 기본적으로 JSON 형태로 반환되지만, Accept를 text/event-stream으로 지정 시 응답 결과를 스트림 형태로 반환합니다.

요청 경로 파라미터

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

필드	타입	필수 여부	설명
modelName	string	Y	사용할 모델 이름 <예시> HCX-003

튜닝 학습을 한 작업을 이용할 경우, 파라미터에 대한 설명은 다음과 같습니다.

필드	타입	필수 여부	설명
taskId	string	Y	학습 아이디

참고

호출 시 필요한 taskID는 학습 생성 API의 응답 바디에서 확인할 수 있습니다.

요청 바디

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

필드	타입	필수 여부	설명
messages	object (ChatMessage)	Y	대화 메시지
ChatMessages.role	enum	Y	대화 메시지의 역할 system: 역할을 규정하는 지시문 user: 사용자의 발화/질문 assistant: 사용자의 발화/질문에 대한 답변
ChatMessages.content	string	Y	대화 메시지 내용
temperature	double	N	생성 토큰에 대한 다양성 정도(설정값이 높을수록 다양한 문장 생성) 0.00 ＜ temperature ≤ 1 (기본값: 0.50)
topK	int	N	생성 토큰 후보군에서 확률이 높은 k개를 후보로 지정하여 샘플링 0 ≤ topK ≤ 128 (기본값: 0)
topP	double	N	생성 토큰 후보군을 누적 확률을 기반으로 샘플링 0 ＜ topP ≤ 1 (기본값: 0.8)
repeatPenalty	double	N	같은 토큰을 생성하는 것에 대한 패널티 정도(설정값이 높을수록 같은 결괏값을 반복 생성할 확률 감소) 0 ＜ repeatPenalty ≤ 10 (기본값: 5.0)
stopBefore	string	N	토큰 생성 중단 문자 [](기본값)
maxTokens	int	N	최대 생성 토큰 수 0~4096 (기본값: 100)
includeAiFilters	boolean	N	생성된 결괏값에 대해 욕설, 비하/차별/혐오, 성희롱 /음란 등 카테고리별로 해당하는 정도 false(기본값) true
seed	int	N	모델 반복 실행 시 결괏값의 일관성 수준 조정 0: 일관성 수준 랜덤 적용 (기본값) 1 ≤ seed ≤ 4294967295: 일관되게 생성하고자 하는 결괏값의 seed 값 또는 사용자가 지정하고자 하는 seed 값

참고

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

messages: 입력한 토큰 수와 `maxTokens`에서 입력한 토큰 수의 합은 4096 토큰을 초과할 수 없습니다. messages에서 입력한 토큰 수는 Chat Completions 토큰 계산 API를 호출하여 확인할 수 있습니다.

topP, temperature: 소수점 둘째 자리까지 표기합니다.

Seed: 사용 시 모델을 반복 실행하더라도 일관성 있는 결괏값을 얻을 확률을 높일 수 있습니다. 하지만 결괏값의 완전성은 보장하지 않으며, 다른 조건이 변경되면 결과가 미세하게 달라질 수 있습니다.

요청 구문

구문 예시는 다음과 같습니다.

curl --location --request POST 'https://clovastudio.stream.gov-ntruss.com/testapp/v1/chat-completions/HCX-003' \
--header 'X-NCP-CLOVASTUDIO-API-KEY: <X-NCP-CLOVASTUDIO-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	-	대화 메시지의 역할 system: 역할을 규정하는 지시문 user: 사용자의 발화/질문 assistant: 사용자의 발화/질문에 대한 답변
result.message.content	string	-	대화 메시지 내용
result.stopReason	enum	-	토큰 생성 중단 이유(일반적으로 마지막 이벤트에 전달) LENGTH: 길이 제한 END_TOKEN: EOD(End Of Token)로 인한 생성 중단 STOP_BEFORE: stopBefore에 지정한 문자로 인한 중단
result.inputLength	int	-	입력 토큰 수(과금 기준으로 end of turn과 같은 특수 토큰도 포함)
result.outputLength	int	-	응답 토큰 수
result.seed	int	-	입력 seed 값 (0 입력 또는 미입력 시 랜덤 값 반환)
aiFilter	array	-	AI Filter 결과
aiFilter.groupName	string	-	AI Filter 카테고리 그룹 이름 curse unsafeContents
aiFilter.name	string	-	AI Filter 카테고리 세부 이름 discrimination: 비하, 차별, 혐오(curse) insult: 욕설(curse) sexualHarassment: 성희롱, 음란(unsafeContents)
aiFilter.score	string	-	AI Filter 점수 0: 대화 메시지에 민감/위험 표현 포함 가능성 높음 1: 대화 메시지에 민감/위험 표현 포함 가능성 있음 2: 대화 메시지에 민감/위험 표현 포함 가능성 낮음 -1: AI Filter 오류 발생
aiFilter.score	string	-	AI Filter 정상 작동 여부 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	array	-	대화 메시지
message.role	enum	-	대화 메시지의 역할 system: 역할을 규정하는 지시문 user: 사용자의 발화/질문 assistant: 사용자의 발화/질문에 대한 답변
message.content	string	-	대화 메시지 내용
stopReason	enum	-	토큰 생성 중단 이유(일반적으로 마지막 이벤트에 전달) LENGTH: 길이 제한 END_TOKEN: EOD(End Of Token)로 인한 생성 중단 STOP_BEFORE: stopBefore에 지정한 문자로 인한 중단
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 점수 0: 대화 메시지에 민감/위험 표현 포함 가능성 높음 1: 대화 메시지에 민감/위험 표현 포함 가능성 있음 2: 대화 메시지에 민감/위험 표현 포함 가능성 낮음 -1: AI Filter 오류 발생
aiFilter.result	string	-	AI Filter 정상 작동 여부 OK: 정상 작동 ERROR: 오류 발생

StreamingChatCompletionsTokenEvent

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

필드	타입	필수 여부	설명
id	string	-	요청을 식별하는 이벤트 아이디
message	array	-	대화 메시지
message.role	enum	-	대화 메시지의 역할 system: 역할을 규정하는 지시문 user: 사용자의 발화/질문 assistant: 사용자의 발화/질문에 대한 답변
message.content	string	-	대화 메시지 내용
inputLength	int	-	입력 토큰 수(과금 기준으로 end of turn과 같은 특수 토큰도 포함)
stopReason	enum	-	토큰 생성 중단 이유(일반적으로 마지막 이벤트에 전달) LENGTH: 길이 제한 END_TOKEN: EOD(End Of Token)로 인한 생성 중단 STOP_BEFORE: stopBefore에 지정한 문자로 인한 중단

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

실패

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

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

What's Next

학습 조회

요청
응답
응답 스트림

태그