Chat Completions
- 印刷する
- PDF
Chat Completions
- 印刷する
- PDF
記事の要約
この要約は役に立ちましたか?
ご意見ありがとうございます
Classic/VPC環境で利用できます。
HyperCLOVA Xモデルを利用して会話型文章を生成します。
リクエスト
リクエスト形式を説明します。リクエスト形式は次の通りです。
| メソッド | URI |
|---|---|
| POST | /v1/chat-completions/{modelName} |
参考
チューニング学習を行った作業を利用する際は/v1/tasks/{taskId}/chat-completions形式で呼び出します。呼び出しに必要なtaskIDは学習作成 APIのレスポンスボディで確認できます。
リクエストヘッダ
ヘッダの説明は次の通りです。
| ヘッダ | 必須の有無 | 説明 |
|---|---|---|
| X-NCP-CLOVASTUDIO-API-KEY | Y | テストアプリやサービスアプリの作成時に発行された API KEY |
| X-NCP-APIGW-API-KEY | Y | テストアプリやサービスアプリの作成時に発行された API Gateway KEY |
| X-NCP-CLOVASTUDIO-REQUEST-ID | N | 各リクエストのリクエスト ID |
| Content-Type | Y | application/json |
| Accept | N | text/event-stream |
参考
- レスポンス結果は基本的に JSON形式で返されますが、
Acceptをtext/event-streamに指定するとレスポンス結果をストリーム形式で返します。 - レスポンスストリームの利用時、API URLは
https://clovastudio.stream.ntruss.com/を使用してください。
リクエストパスパラメータ
パラメータの説明は次の通りです。
| フィールド | タイプ | 必須の有無 | 説明 |
|---|---|---|---|
| modelName | string | Y | 使用するモデル名<例> HCX-003 |
チューニング学習を行った作業を利用する場合、パラメータの説明は次の通りです。
| フィールド | タイプ | 必須の有無 | 説明 |
|---|---|---|---|
| taskId | string | Y | 学習 ID |
参考
呼び出しに必要なtaskIDは学習作成 APIのレスポンスボディで確認できます。
リクエストボディ
ボディの説明は次の通りです。
| フィールド | タイプ | 必須の有無 | 説明 |
|---|---|---|---|
| messages | object (ChatMessage) | Y | 会話メッセージ |
| ChatMessages.role | enum | Y | 会話メッセージのロール |
| ChatMessages.content | string | Y | 会話メッセージの内容 |
| temperature | double | N | 生成トークンに対する多様性の程度(設定値が高いほど多様な文章を生成) |
| topK | int | N | 生成トークン候補群から確率の高いトークン k個を候補に指定してサンプリング |
| topP | double | N | 生成トークン候補群を累積確率に基づいてサンプリング |
| repeatPenalty | double | N | 同じトークンを生成することに対するペナルティの程度(設定値が高いほど同じ結果値を繰り返し生成する確率は下がる) |
| stopBefore | string | N | トークン生成停止文字 |
| maxTokens | int | N | 最大トークン生成数 |
| includeAiFilters | boolean | N | 生成された結果値に対する罵倒、蔑み/差別/嫌悪、セクハラ/わいせつなどカテゴリ別に当てはまる程度 |
| seed | int | N | モデルを繰り返し実行する場合、結果値の一貫性のレベルを調整 |
参考
一部フィールドの入力時、下記の内容をご確認ください。
リクエスト構文
構文のサンプルコードは次の通りです。
curl --location --request POST 'https://clovastudio.stream.ntruss.com/testapp/v1/chat-completions/HCX-002' \
--header 'X-NCP-CLOVASTUDIO-API-KEY: <X-NCP-CLOVASTUDIO-API-KEY>' \
--header 'X-NCP-APIGW-API-KEY: <X-NCP-APIGW-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" : "test"
}, {
"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 | - | 会話メッセージのロール |
| result.message.content | string | - | 会話メッセージの内容 |
| result.stopReason | enum | - | トークン生成停止の理由(通常、最後のイベントに伝達) |
| result.inputLength | int | - | 入力トークン数(課金の基準で、end of turnといった特殊なトークンも含む) |
| result.outputLength | int | - | レスポンストークン数 |
| result.seed | int | - | 入力 seed値 (0を入力したか、未入力の場合はランダムな値を返す) |
| aiFilter | array | - | AI Filter結果 |
| aiFilter.groupName | string | - | AI Filterカテゴリグループ名 |
| aiFilter.name | string | - | AI Filterの詳細なカテゴリの名前 |
| aiFilter.score | string | - | AI Filterスコア |
| aiFilter.score | string | - | AI Filterは正常に動作しているか |
参考
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 | array | - | 会話メッセージ |
| message.role | enum | - | 会話メッセージのロール |
| message.content | string | - | 会話メッセージの内容 |
| stopReason | enum | - | トークン生成停止の理由(通常、最後のイベントに伝達) |
| 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スコア |
| aiFilter.result | string | - | AI Filterは正常に動作しているか |
StreamingChatCompletionsTokenEvent
StreamingChatCompletionsResultEventの説明は次の通りです。
| フィールド | タイプ | 必須の有無 | 説明 |
|---|---|---|---|
| id | string | - | リクエストを識別するイベント ID |
| message | array | - | 会話メッセージ |
| message.role | enum | - | 会話メッセージのロール |
| message.content | string | - | 会話メッセージの内容 |
| inputLength | int | - | 入力トークン数(課金の基準で、end of turnといった特殊なトークンも含む) |
| stopReason | enum | - | トークン生成停止の理由(通常、最後のイベントに伝達) |
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": “ちは”}}
失敗
呼び出しに失敗した場合の構文例は次の通りです。
この記事は役に立ちましたか?