会話の生成

VPC環境で利用できます。

ユーザークエリに対し、LLMが会話型文章を生成します。

リクエスト

リクエスト形式を説明します。リクエスト形式は次の通りです。

リクエストヘッダ

RAG APIで共通して使用されるヘッダの詳細は、RAGのリクエストヘッダをご参照ください。

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

パラメータの説明は次の通りです。

リクエストボディ

リクエストボディの説明は次の通りです。

messages

会話のコンテキストを提供するメッセージの配列です。

RETRIEVALパラメータ

文書検索ブロック(blocks.RETRIEVAL.type = "RETRIEVAL")の設定パラメータです。

filters

GENERATORパラメータ

回答生成ブロック(blocks.GENERATOR.type = "LLM")の設定パラメータです。

リクエスト例

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

curl --location --request POST 'https://kr-pub-gateway.rag.naverncp.com/api/v1/svc/{serviceId}/conversation' \
--header 'Authorization: Bearer {apiKey}' \
--header 'Content-Type: application/json' \
--header 'Accept: text/event-stream' \
--data '{
  "serviceId": "{serviceId}",
  "messages": [
    {
      "role": "user",
      "content": "NAVERの技術について教えて。"
    },
    {
      "role": "assistant",
      "content": "NAVERは街の様子をデジタルでそっくり再現できる特別な技術を持っていて、ドローンを使って撮った写真をコンピュータの中でまるで本物のように立体的に見せることができます!"
    },
    {
      "role": "user",
      "content": "この技術は何と呼ばれているの?"
    }
  ],
  "blocks": {
    "RETRIEVAL": {
      "type": "RETRIEVAL",
      "parameters": {
        "k": 1,
        "fileName": "leap-25.docx",
        "chunkSize": 256,
        "overlapSize": 128,
        "filters": [
          {
            "term": {
              "extra.bucket.keyword": {
                "value": "clova-ai"
              }
            }
          },
          {
            "term": {
              "file_name": "leap-25.docx"
            }
          },
          {
            "range": {
              "extra.size": {
                "lte": 1000000
              }
            }
          }
        ]
      }
    },
    "GENERATOR": {
      "type": "LLM",
      "parameters": {
        "chatModel": "HyperClovaX",
        "systemPrompt": "小学生の目線に合わせて説明して。",
        "llmParameters": {
          "model": "HCX-005",
          "clovaStudioApiKey": "{clovaStudioApiKey}",
          "temperature": 0.50,
          "topK": 64,
          "topP": 0.50,
          "maxTokens": 1024
        }
      }
    }
  },
  "citation": {
    "enabled": true
  },
  "verbose": true
}

レスポンス

レスポンス形式を説明します。

レスポンスヘッダ

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

レスポンスボディ

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

data.results

配列の各要素は、RAGの処理段階を順に表します。

RETRIEVALパラメータ

data.references

回答作成時に使用された引用情報です。

data

レスポンス例

レスポンスのサンプルコードは次の通りです。

{
    "code": 200,
    "message": null,
    "data": {
        "results": [
            {
                "blockId": "START",
                "value": "この技術は何と呼ばれているの?"
            },
            {
                "blockId": "QUERY_REWRITE",
                "value": "NAVERの技術のことを人々はどのような名称で呼んでいますか?"
            },
            {
                "blockId": "RETRIEVAL",
                "value": [
                    {
                        "docId": "c69cd98c0674e1a8a814",
                        "fileName": "leap-25.docx",
                        "score": 0.04168701171875,
                        "rank": 1,
                        "text": "NAVERは巨大な街全体をデジタルツインデータで製作できる独自の技術を持っています。NAVERは、航空写真と写真測量技術を利用してメガシティ規模のデジタルツインデータを迅速かつ正確に製作することができ、AI技術で実際と同じ3次元空間に復元しました。既に韓国では、NAVER Payを通じて、実際に団地を訪問しなくても不動産物件情報を確認できる VRサービスを提供しています。",
                        "start_offset": 4025,
                        "end_offset": 4258,
                        "chunk_no": 1,
                        "page_no": 0
                    }
                ]
            },
            {
                "blockId": "CONDITIONAL",
                "value": "branch1"
            },
            {
                "blockId": "GENERATOR",
                "value": "NAVERが持つこの技術は、「デジタルツイン(Digital Twin)」と呼ばれています。デジタルツインとは、現実世界の物理的なオブジェクトを仮想世界にそっくり作り、リアルタイムでモニタリング・制御する技術を指します。分かりやすく言うと、実際の空間をコンピュータの中に双子のように作ったものです。\n\n例えば、私たちが住んでいる街や学校の建物をデジタルツインにすると、実際にその場所に行かなくても、コンピュータの画面で建物の内外を見渡すことができ、街を歩いたり、周辺施設を確認することもできます。さらに、天気の変化や交通状況などをシミュレーションして未来の状況を予測したり、問題を解決するのにも活用することができます。\n\nNAVERは、このようなデジタルツイン技術を活用してさまざまな分野で新しいサービスを開発しています。例えば、ネットでショッピングをしながら洋服を実際に試着したかのように見せてくれるバーチャルフィッティングルームや、家の中を3Dで探索しながらインテリアを飾る機能などがこれに当たります。\n\nこのように、デジタルツインテクノロジーは、私たちの日常生活をより便利にし、想像力を刺激する素晴らしいツールです。今後も絶えず進化を続けて、より多くの場面で活用されることが期待されています。"
            }
        ],
        "references": [
            {
                "name": "RETRIEVAL",
                "data": [
                    {
                        "docId": "c69cd98c0674e1a8a814",
                        "fileName": "leap-25.docx",
                        "text": "NAVERは巨大な街全体をデジタルツインデータで製作できる独自の技術を持っています。NAVERは、航空写真と写真測量技術を利用してメガシティ規模のデジタルツインデータを迅速かつ正確に製作することができ、AI技術で実際と同じ3次元空間に復元しました。既に韓国では、NAVER Payを通じて、実際に団地を訪問しなくても不動産物件情報を確認できる VRサービスを提供しています。",
                        "startOffset": 4025,
                        "endOffset": 4258,
                        "chunkNo": 1,
                        "pageNo": 0,
                        "extra": {
                            "bucket": "clova-ai",
                            "size": 966060,
                            "last_modified": "2025-07-02T10:17:19+00:00",
                            "key": "leap-25.docx"
                        }
                    }
                ]
            }
        ],
        "rateLimit": {
            "limitRequests": null,
            "remainingRequests": null,
            "resetRequests": null,
            "limitTokens": "60000",
            "remainingTokens": "58324",
            "resetTokens": "59s"
        }
    }
}

レスポンスストリーム

Server-Sent Events (SSE)方式でリアルタイムストリーミングレスポンスを提供します。各 SSEメッセージは次のような形式で構成されます (イベントは空の行で区切ります)。

event: [event_type]
data: [json_data]

会話生成 APIがサポートするイベントタイプは、step、ping、token、result、errorの5つです。

• step: 回答生成前にブロック別処理結果を出力 (verbose = trueの場合)
• ping: 回答生成前の待機中に Read Timeoutを防止するためにデータを出力 (回答生成まで1秒ごとに)
• token: 生成中回答のトークンをリアルタイムで出力
• result: 最終回答を出力
• error: 回答生成中にエラーが発生した場合に出力

レスポンスヘッダ

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

レスポンスボディ

レスポンスボディはイベントタイプによって異なります。

stepイベント

stepイベントの説明は次の通りです。

RETRIEVALパラメータ

ping、token、resultイベント

ping、token、resultイベントの説明は次の通りです。

references

data

errorイベント

errorイベントの説明は次の通りです。

レスポンスステータスコード

RAG APIで共通して使用されるレスポンスステータスコードの詳細は、RAGのレスポンスステータスコードをご参照ください。

レスポンス例

レスポンスのサンプルコードは次の通りです。

event: step
data: {
    "blockName": "START",
    "blockResult": "この技術は何と呼ばれているの?"
}

event: step
data: {
    "blockName": "QUERY_REWRITE",
    "blockResult": "NAVERの技術のことを人々はどのような名称で呼んでいますか?"
}

event: step
data: {
    "blockName": "RETRIEVAL",
    "blockResult": [
        {
            "docId": "{docId}",
            "fileName": "leap-25.docx",
            "score": 0.04168701171875,
            "rank": 1,
            "text": "NAVERは巨大な街全体をデジタルツインデータで製作できる独自の技術を持っています。NAVERは、航空写真と写真測量技術を利用してメガシティ規模のデジタルツインデータを迅速かつ正確に製作することができ、AI技術で実際と同じ3次元空間に復元しました。既に韓国では、NAVER Payを通じて、実際に団地を訪問しなくても不動産物件情報を確認できる VRサービスを提供しています。",
            "start_offset": 4025,
            "end_offset": 4258,
            "chunk_no": 1,
            "page_no": 0
        }
    ]
}

event: step
data: {
    "blockName": "CONDITIONAL",
    "blockResult": "branch1"
}

event: ping
data: {
    "message": {
        "role": "assistant",
        "content": "",
        "totalContent": ""
    },
    "status": "IN_PROGRESS",
    "references": [],
    "rateLimit": null,
    "metadata": {}
}

...

event: token
data: {
    "message": {
        "role": "assistant",
        "content": " デジタル",
        "totalContent": "NAVERが持つこの技術は、「デジタルツイン(Digital Twin)」と呼ばれています。デジタル"
    },
    "status": "IN_PROGRESS",
    "references": [],
    "rateLimit": null,
    "metadata": {}
}

...

event: result
data: {
    "message": {
        "role": "assistant",
        "content": "NAVERが持つこの技術は、「デジタルツイン(Digital Twin)」と呼ばれています。[†1]デジタルツインとは、現実世界の物理的なオブジェクトを仮想世界にそっくり作ることを意味し、これを通じてさまざまなシミュレーションや分析を行うことで、意思決定に役立てることができます。\n\n例えば、紙の上に家を描くとします。実際に建てる家とまったく同じ絵を描くのです。すると、その絵をもっていろいろな計画を立てたり、実験を行ったりできるわけです。雨が降ったときに水がどのように流れるか知りたいなら、絵の上で雨を降らせて結果を観察するといった具合にです。\n\nこのように作られた仮想世界は、実際の建物や都市を建設する前に、予めさまざまな状況をテストすることができて、時間とコストを節約できます。さらに、実際の建物の管理にも大いに役立ちます。例えば、建物内の機械が正常に動作しているか、エネルギーを効率的に使用しているかなどをモニタリングして、問題が発生する前に対策を講じることができます。\n\nNAVERはこのようなデジタルツイン技術を利用して、韓国のさまざまな地域を仮想世界に再現し、これに基づいてさまざまなサービスを開発しています。[†1]そうやって私たちは、直接現地に行かなくても、パソコンやスマートフォンでその地域の情報を確認したり、体験したりできるのです。本当にすごいと思いませんか?",
        "totalContent": "NAVERが持つこの技術は、「デジタルツイン(Digital Twin)」と呼ばれています。[†1]デジタルツインとは、現実世界の物理的なオブジェクトを仮想世界にそっくり作ることを意味し、これを通じてさまざまなシミュレーションや分析を行うことで、意思決定に役立てることができます。\n\n例えば、紙の上に家を描くとします。実際に建てる家とまったく同じ絵を描くのです。すると、その絵をもっていろいろな計画を立てたり、実験を行ったりできるわけです。雨が降ったときに水がどのように流れるか知りたいなら、絵の上で雨を降らせて結果を観察するといった具合にです。\n\nこのように作られた仮想世界は、実際の建物や都市を建設する前に、予めさまざまな状況をテストすることができて、時間とコストを節約できます。さらに、実際の建物の管理にも大いに役立ちます。例えば、建物内の機械が正常に動作しているか、エネルギーを効率的に使用しているかなどをモニタリングして、問題が発生する前に対策を講じることができます。\n\nNAVERはこのようなデジタルツイン技術を利用して、韓国のさまざまな地域を仮想世界に再現し、これに基づいてさまざまなサービスを開発しています。[†1]そうやって私たちは、直接現地に行かなくても、パソコンやスマートフォンでその地域の情報を確認したり、体験したりできるのです。本当にすごいと思いませんか?"
    },
    "status": "COMPLETE",
    "references": [
        {
            "name": "RETRIEVAL",
            "data": [
                {
                    "docId": "12345",
                    "fileName": "leap-25.docx",
                    "text": "NAVERは巨大な街全体をデジタルツインデータで製作できる独自の技術を持っています。NAVERは、航空写真と写真測量技術を利用してメガシティ規模のデジタルツインデータを迅速かつ正確に製作することができ、AI技術で実際と同じ3次元空間に復元しました。既に韓国では、NAVER Payを通じて、実際に団地を訪問しなくても不動産物件情報を確認できる VRサービスを提供しています。",
                    "startOffset": 4025,
                    "endOffset": 4258,
                    "chunkNo": 1,
                    "pageNo": 0,
                    "extra": {
                        "bucket": "clova-ai",
                        "size": 966060,
                        "last_modified": "2025-07-02T10:17:19+00:00",
                        "key": "leap-25.docx"
                    }
                }
            ]
        }
    ],
    "rateLimit": {
        "limitRequests": null,
        "remainingRequests": null,
        "resetRequests": null,
        "limitTokens": "60000",
        "remainingTokens": "56648",
        "resetTokens": "28s"
    },
    "metadata": {
        "chatModel": "HyperClovaX",
        "modelName": "HCX-005",
        "inputTokens": 267,
        "outputTokens": 262,
        "totalTokens": 529
    }
}