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-KEYRequiredテストアプリやサービスアプリの作成時に発行された API KEY
    X-NCP-APIGW-API-KEYRequiredテストアプリやサービスアプリの作成時に発行された API Gateway KEY
    X-NCP-CLOVASTUDIO-REQUEST-IDOptionalリクエスト ID
    Content-TypeRequiredリクエストデータの形式
    • application/json
    AcceptConditionalレスポンスデータの形式
    • text/event-stream
    参考
    • レスポンス結果は基本的に JSON形式で返されますが、Accepttext/event-streamに指定するとレスポンス結果をストリーム形式で返します。
    • レスポンスストリームの利用時、API URLはhttps://clovastudio.stream.ntruss.com/を使用してください。

    リクエストパスパラメータ

    リクエストパスパラメータの説明は次の通りです。

    フィールドタイプ必須の有無説明
    modelNameStringConditionalモデル名
    • モデルを使用して文を生成する場合
    • <例> HCX-003
    taskIdStringConditional学習 ID
    • チューニング学習の結果を使用して文を生成する場合
    • 学習作成 APIのレスポンスボディで確認可能

    リクエストボディ

    レスポンスボディの説明は次の通りです。

    フィールドタイプ必須の有無説明
    messagesArrayRequired会話メッセージ
    temperatureDoubleOptional生成トークンに対する多様性の程度(設定値が高いほど多様な文を生成)
    • 0.00 < temperature ≤ 1.00 (デフォルト: 0.50)
      • 小数点第二位まで表記
    topKIntegerOptional生成トークン候補群から確率の高いトークン K個を候補に指定してサンプリング
  • 0 ≤ topK ≤ 128 (デフォルト: 0)
  • topPDoubleOptional生成トークン候補群を累積確率に基づいてサンプリング
    • 0.00 < topP ≤ 1.00 (デフォルト: 0.80)
      • 小数点第二位まで表記
    repeatPenaltyDoubleOptional同じトークンを生成することに対するペナルティの程度(設定値が高いほど同じ結果値を繰り返し生成する確率は下がる)
  • 0.0 < repeatPenalty ≤ 10.0 (デフォルト: 5.0)
  • stopBeforeArrayOptionalトークン生成停止文字
  • [](デフォルト)
  • maxTokensIntegerOptional最大トークン生成数
  • 0 < maxTokens ≤ 2048 (デフォルト: 100)
  • includeAiFiltersBooleanOptionalAIフィルタ(生成された結果値に対する罵倒、蔑み/差別/嫌悪、セクハラ/わいせつなどカテゴリ別に当てはまる程度)結果を表示するかどうか
    • false(デフォルト) | true
      • false: 表示しない
      • true: 表示
    seedIntegerOptionalモデルの繰り返し実行時、結果値の一貫性レベルを調整
    • 0: 一貫性レベルをランダム適用 (デフォルト)
    • 1 ≤ seed ≤ 4294967295: 一貫して作成しようとする結果値のseedまたはユーザーが指定するseed
    参考

    一部フィールドの入力時、下記の内容をご確認ください。

    • messages: 入力したトークン数とmaxTokensで入力したトークン数の合計は4096トークンを超えることはできません。messagesで入力したトークン数は、Chat Completionsトークン計算 APIを呼び出すと確認できます。
    • seed: 使用時にモデルを繰り返し実行しても、一貫した結果値を得る確率を高められます。ただし、結果値の完全性は保証されません。他の条件が変わると結果が微妙に変わる可能性があります。

    messages

    messagesの説明は次の通りです。

    フィールドタイプ必須の有無説明
    roleEnumRequired会話メッセージのロール
    • system | user | assistant
      • system: ロールを規定する指示文
      • user: ユーザーの発話または質問
      • assistant: ユーザーの発話/質問に対する返答
    contentStringRequired会話メッセージの内容

    リクエスト例

    リクエストのサンプルコードは次の通りです。

    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

    レスポンスボディ

    レスポンスボディの説明は次の通りです。

    フィールドタイプ必須の有無説明
    statusObject-レスポンスステータス
    resultObject-レスポンス結果
    result.messageObject-会話メッセージ
    result.message.roleEnum-会話メッセージのロール
    • system | user | assistant
      • system: ロールを規定する指示文
      • user: ユーザーの発話または質問
      • assistant: モデルの返答
    result.message.contentString-会話メッセージの内容
    result.stopReasonEnum-結果生成停止の理由
    • length | end_token | stop_before
      • length: 長さ制限
      • end_token: トークン数制限
      • stop_before: 返答生成中stopBeforeに指定した文字が登場
    result.inputLengthInteger-入力トークン数(課金の基準で、end of turnといった特殊なトークンも含む)
    result.outputLengthInteger-レスポンストークン数
    result.seedint-入力 seed値(0を入力したか、未入力の場合はランダムな値を返す)
    result.aiFilterArray-AIフィルタの結果

    aiFilter

    aiFilterの説明は次の通りです。

    フィールドタイプ必須の有無説明
    groupNameString-AIフィルタのカテゴリ
    • curse | unsafeContents
      • curse: 蔑み、差別、嫌悪および罵倒
      • unsafeContents: セクハラ、わいせつ
    nameString-AIフィルタの詳細カテゴリ
    • discrimination | insult | sexualHarassment
      • discrimination: 蔑み、差別、嫌悪
      • insult: 罵倒
      • sexualHarassment: セクハラ、わいせつ
    scoreString-AIフィルタスコア
    • -1 | 0 | 1 | 2
      • -1: AIフィルタにエラー発生
      • 0: 会話メッセージに要注意/危険な表現を含む可能性が高い
      • 1: 会話メッセージに要注意/危険な表現を含む可能性がある
      • 2: 会話メッセージに要注意/危険な表現を含む可能性が低い
    resultString-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"
          }
        ]
      }
    }
    

    失敗

    呼び出しに失敗した場合のレスポンスのサンプルコードは次の通りです。

    レスポンスストリーム

    生成されるトークンを1つずつ出力するようにトークンストリーミングを使用できます。トークンストリーミング形式を説明します。

    レスポンスヘッダ

    レスポンスヘッダの説明は次の通りです。

    ヘッダ必須の有無説明
    Accept-レスポンスデータの形式
    • text/event-stream

    レスポンスボディ

    レスポンスボディの説明は次の通りです。

    StreamingChatCompletionsResultEvent

    StreamingChatCompletionsResultEventの説明は次の通りです。

    フィールドタイプ必須の有無説明
    messageObject-会話メッセージ
    message.roleEnum-会話メッセージのロール
    • system | user | assistant
      • system: ロールを規定する指示文
      • user: ユーザーの発話または質問
      • assistant: モデルの返答
    message.contentString-会話メッセージの内容
    stopReasonEnum-結果生成停止の理由
    • length | end_token | stop_before
      • length: 長さ制限
      • end_token: トークン数制限
      • stop_before: 返答生成中stopBeforeに指定した文字が登場
    inputLengthInteger-入力トークン数(課金の基準で、end of turnといった特殊なトークンも含む)
    outputLengthInteger-レスポンストークン数
    aiFilterArray-AIフィルタの結果

    StreamingChatCompletionsTokenEvent

    StreamingChatCompletionsResultEventの説明は次の通りです。

    フィールドタイプ必須の有無説明
    idString-リクエストを識別するイベント ID
    messageObject-会話メッセージ
    message.roleEnum-会話メッセージのロール
    • system | user | assistant
      • system: ロールを規定する指示文
      • user: ユーザーの発話または質問
      • assistant: モデルの返答
    message.contentString-会話メッセージの内容
    inputLengthInteger-入力トークン数(課金の基準で、end of turnといった特殊なトークンも含む)
    stopReasonEnum-結果生成停止の理由
    • length | end_token | stop_before
      • length: 長さ制限
      • end_token: トークン数制限
      • stop_before: 返答生成中stopBeforeに指定した文字が登場

    ErrorEvent

    ErrorEventの説明は次の通りです。

    フィールドタイプ必須の有無説明
    statusObject-レスポンスステータス

    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.