Classic/VPC環境で利用できます。
会話型文章を生成する HCX-003モデルと軽量化された HCX-DASH-001モデルを利用できる Chat Completionsを説明します。
リクエスト
リクエスト形式を説明します。リクエスト形式は次の通りです。
| メソッド | URI |
|---|---|
| POST |
|
リクエストヘッダ
CLOVA Studio APIで共通して使用されるヘッダの詳細は、CLOVA Studioのリクエストヘッダをご参照ください。
リクエストパスパラメータ
リクエストパスパラメータの説明は次の通りです。
| フィールド | タイプ | 必須の有無 | 説明 |
|---|---|---|---|
modelName |
String | Conditional | モデル名
|
taskId |
String | Conditional | 学習 ID
|
リクエストボディ
レスポンスボディの説明は次の通りです。
| フィールド | タイプ | 必須の有無 | 説明 |
|---|---|---|---|
messages |
Array | Required | 会話メッセージ: messages |
temperature |
Double | Optional | 生成トークンに対する多様性の程度(設定値が高いほど多様な文を生成)
|
topK |
Integer | Optional | 生成トークン候補群から確率の高いトークン K個を候補に指定してサンプリング
|
topP |
Double | Optional | 生成トークン候補群を累積確率に基づいてサンプリング
|
repeatPenalty |
Double | Optional | 同じトークンを生成することに対するペナルティの程度(設定値が高いほど同じ結果値を繰り返し生成する確率は下がる)
|
stopBefore |
Array | Optional | トークン生成停止文字
|
maxTokens |
Integer | Optional | 最大トークン生成数
|
includeAiFilters |
Boolean | Optional | AIフィルタ(生成された結果値に対する罵倒、蔑み/差別/嫌悪、セクハラ/わいせつなどカテゴリ別に当てはまる程度)結果を表示するかどうか
|
seed |
Integer | Optional | モデルの繰り返し実行時、結果値の一貫性レベルを調整
|
参考
一部フィールドの入力時、下記の内容をご確認ください。
- HCX-003
- 入力トークンと出力トークンの合計は8,192トークンを超えてはいけません。
- 入力トークンの最大値は7,600トークンまでです。
- モデルにリクエスト可能な出力トークン(maxTokens)は最大4,096トークンまでです。
- HCX-DASH-001
- 入力トークンと出力トークンの合計は4,096トークンを超えてはいけません。
- 入力トークンの最大値は3,500トークンまでです。
- モデルにリクエスト可能な出力トークン(maxTokens)は最大4,096トークンまでです。
messages
messagesの説明は次の通りです。
| フィールド | タイプ | 必須の有無 | 説明 |
|---|---|---|---|
role |
Enum | Required | 会話メッセージのロール
|
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 | - | レスポンスデータの形式
|
レスポンスボディ
レスポンスボディの説明は次の通りです。
| フィールド | タイプ | 必須の有無 | 説明 |
|---|---|---|---|
status |
Object | - | レスポンスステータスを参照 |
result |
Object | - | レスポンス結果 |
result.message |
Object | - | 会話メッセージ |
result.message.role |
Enum | - | 会話メッセージのロール
|
result.message.content |
String | - | 会話メッセージの内容 |
result.stopReason |
Enum | - | 結果生成停止の理由
|
result.inputLength |
Integer | - | 入力トークン数(課金の基準で、end of turnといった特殊なトークンも含む) |
result.outputLength |
Integer | - | レスポンストークン数 |
result.seed |
int | - | 入力 seed値(0を入力したか、未入力の場合はランダムな値を返す) |
result.aiFilter |
Array | - | AIフィルタの結果: aiFilter |
aiFilter
aiFilterの説明は次の通りです。
| フィールド | タイプ | 必須の有無 | 説明 |
|---|---|---|---|
groupName |
String | - | AIフィルタのカテゴリ
|
name |
String | - | AIフィルタの詳細カテゴリ
|
score |
String | - | AIフィルタスコア
|
result |
String | - | AIフィルタは正常に動作しているか
|
参考
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 | - | レスポンスデータの形式
|
レスポンスボディ
レスポンスボディの説明は次の通りです。
StreamingChatCompletionsResultEvent
StreamingChatCompletionsResultEventの説明は次の通りです。
| フィールド | タイプ | 必須の有無 | 説明 |
|---|---|---|---|
message |
Object | - | 会話メッセージ |
message.role |
Enum | - | 会話メッセージのロール
|
message.content |
String | - | 会話メッセージの内容 |
stopReason |
Enum | - | 結果生成停止の理由
|
inputLength |
Integer | - | 入力トークン数(課金の基準で、end of turnといった特殊なトークンも含む) |
outputLength |
Integer | - | レスポンストークン数(課金の基準で、end of turnといった特殊なトークンも含む) |
aiFilter |
Array | - | AIフィルタの結果: aiFilter |
StreamingChatCompletionsTokenEvent
StreamingChatCompletionsTokenEventの説明は次の通りです。
| フィールド | タイプ | 必須の有無 | 説明 |
|---|---|---|---|
id |
String | - | リクエストを識別するイベント ID |
message |
Object | - | 会話メッセージ |
message.role |
Enum | - | 会話メッセージのロール
|
message.content |
String | - | 会話メッセージの内容 |
inputLength |
Integer | - | 入力トークン数(課金の基準で、end of turnといった特殊なトークンも含む) |
outputLength |
Integer | - | レスポンストークン数(課金の基準で、end of turnといった特殊なトークンも含む) |
stopReason |
Enum | - | 結果生成停止の理由
|
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" }
失敗
呼び出しに失敗した場合のレスポンスのサンプルコードは次の通りです。