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-KEYY테스트 앱이나 서비스 앱 생성 시 발급 받은 API KEY
    X-NCP-CLOVASTUDIO-REQUEST-IDN각 요청에 대한 요청 아이디
    Content-TypeYapplication/json
    AcceptNtext/event-stream
    참고

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

    요청 경로 파라미터

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

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

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

    필드타입필수 여부설명
    taskIdstringY학습 아이디
    참고

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

    요청 바디

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

    필드타입필수 여부설명
    messagesobject (ChatMessage)Y대화 메시지
    ChatMessages.roleenumY대화 메시지의 역할
  • system: 역할을 규정하는 지시문
  • user: 사용자의 발화/질문
  • assistant: 사용자의 발화/질문에 대한 답변
  • ChatMessages.contentstringY대화 메시지 내용
    temperaturedoubleN생성 토큰에 대한 다양성 정도(설정값이 높을수록 다양한 문장 생성)
  • 0.00 < temperature ≤ 1 (기본값: 0.50)
  • topKintN생성 토큰 후보군에서 확률이 높은 k개를 후보로 지정하여 샘플링
  • 0 ≤ topK ≤ 128 (기본값: 0)
  • topPdoubleN생성 토큰 후보군을 누적 확률을 기반으로 샘플링
  • 0 < topP ≤ 1 (기본값: 0.8)
  • repeatPenaltydoubleN같은 토큰을 생성하는 것에 대한 패널티 정도(설정값이 높을수록 같은 결괏값을 반복 생성할 확률 감소)
  • 0 < repeatPenalty ≤ 10 (기본값: 5.0)
  • stopBeforestringN토큰 생성 중단 문자
  • [](기본값)
  • maxTokensintN최대 생성 토큰 수
  • 0~4096 (기본값: 100)
  • includeAiFiltersbooleanN생성된 결괏값에 대해 욕설, 비하/차별/혐오, 성희롱 /음란 등 카테고리별로 해당하는 정도
  • false(기본값)
  • true
  • seedintN모델 반복 실행 시 결괏값의 일관성 수준 조정
  • 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.messagearray-대화 메시지
    result.message.roleenum-대화 메시지의 역할
  • system: 역할을 규정하는 지시문
  • user: 사용자의 발화/질문
  • assistant: 사용자의 발화/질문에 대한 답변
  • result.message.contentstring-대화 메시지 내용
    result.stopReasonenum-토큰 생성 중단 이유(일반적으로 마지막 이벤트에 전달)
  • LENGTH: 길이 제한
  • END_TOKEN: EOD(End Of Token)로 인한 생성 중단
  • STOP_BEFORE: stopBefore에 지정한 문자로 인한 중단
  • result.inputLengthint-입력 토큰 수(과금 기준으로 end of turn과 같은 특수 토큰도 포함)
    result.outputLengthint-응답 토큰 수
    result.seedint-입력 seed 값
    (0 입력 또는 미입력 시 랜덤 값 반환)
    aiFilterarray-AI Filter 결과
    aiFilter.groupNamestring-AI Filter 카테고리 그룹 이름
  • curse
  • unsafeContents
  • aiFilter.namestring-AI Filter 카테고리 세부 이름
  • discrimination: 비하, 차별, 혐오(curse)
  • insult: 욕설(curse)
  • sexualHarassment: 성희롱, 음란(unsafeContents)
  • aiFilter.scorestring-AI Filter 점수
  • 0: 대화 메시지에 민감/위험 표현 포함 가능성 높음
  • 1: 대화 메시지에 민감/위험 표현 포함 가능성 있음
  • 2: 대화 메시지에 민감/위험 표현 포함 가능성 낮음
  • -1: AI Filter 오류 발생
  • aiFilter.scorestring-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에 대한 설명은 다음과 같습니다.

    필드타입필수 여부설명
    messagearray-대화 메시지
    message.roleenum-대화 메시지의 역할
  • system: 역할을 규정하는 지시문
  • user: 사용자의 발화/질문
  • assistant: 사용자의 발화/질문에 대한 답변
  • message.contentstring-대화 메시지 내용
    stopReasonenum-토큰 생성 중단 이유(일반적으로 마지막 이벤트에 전달)
  • LENGTH: 길이 제한
  • END_TOKEN: EOD(End Of Token)로 인한 생성 중단
  • STOP_BEFORE: stopBefore에 지정한 문자로 인한 중단
  • inputLengthint-입력 토큰 수(과금 기준으로 end of turn과 같은 특수 토큰도 포함)
    outputLengthint-응답 토큰 수
    aiFilterarray-AI Filter 결과
    aiFilter.groupNamestring-AI Filter 카테고리 그룹 이름
    aiFilter.namestring-AI Filter 카테고리 세부 이름
    aiFilter.scorestring-AI Filter 점수
  • 0: 대화 메시지에 민감/위험 표현 포함 가능성 높음
  • 1: 대화 메시지에 민감/위험 표현 포함 가능성 있음
  • 2: 대화 메시지에 민감/위험 표현 포함 가능성 낮음
  • -1: AI Filter 오류 발생
  • aiFilter.resultstring-AI Filter 정상 작동 여부
  • OK: 정상 작동
  • ERROR: 오류 발생
  • StreamingChatCompletionsTokenEvent

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

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

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

    필드타입필수 여부설명
    statusstatus-응답 상태

    SignalEvent

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

    필드타입필수 여부설명
    datastring-전달할 시그널 데이터 정보

    응답구문

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

    성공

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

    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
    Changing your password will log you out immediately. Use the new password to log back in.
    First name must have atleast 2 characters. Numbers and special characters are not allowed.
    Last name must have atleast 1 characters. Numbers and special characters are not allowed.
    Enter a valid email
    Enter a valid password
    Your profile has been successfully updated.