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 チューニング学習した結果を使用して文を生成

リクエストヘッダ

リクエストヘッダの説明は次の通りです。

ヘッダ	必須の有無	説明
`Authorization`	Required	認証用 APIキー<例> `Bearer nv-************`
`X-NCP-CLOVASTUDIO-REQUEST-ID`	Optional	リクエスト ID
`Content-Type`	Required	リクエストデータの形式 `application/json`
`Accept`	Conditional	レスポンスデータの形式 `text/event-stream`

参考

レスポンス結果は基本的に JSON形式で返されますが、Acceptをtext/event-streamに指定するとレスポンス結果をストリーム形式で返します。

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

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

フィールド	タイプ	必須の有無	説明
`modelName`	String	Conditional	モデル名モデルを使用して文を生成する場合 <例> `HCX-003`
`taskId`	String	Conditional	学習 ID チューニング学習の結果を使用して文を生成する場合学習作成 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` ≤ 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.ntruss.com/v1/chat-completions/HCX-003' \
--header 'Authorization: Bearer {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"
      }
    ]
  }
}

失敗

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

レスポンスストリーム

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

レスポンスヘッダ

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

ヘッダ	必須の有無	説明
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フィルタの結果

StreamingChatCompletionsTokenEvent

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

フィールド	タイプ	必須の有無	説明
`id`	String	-	リクエストを識別するイベント ID
`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-f3asd-g
event: token
data: {"message": {"role": "assistant", "content": “こんに”}}

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": “こんにちは”}, "inputLength":20, "outputLength":5, "stopReason":"stop_before" }

失敗

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