대화 생성

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": "네이버 기술이 궁금해."
    },
    {
      "role": "assistant",
      "content": "네이버는 도시의 모습을 디지털로 똑같이 만들 수 있는 특별한 기술을 갖고 있어서, 드론을 이용해 찍은 사진을 컴퓨터 속에서 마치 진짜처럼 입체적으로 보여줄 수 있어요!"
    },
    {
      "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 처리 단계를 순차적으로 나타냅니다.

문서 검색 결과

data.references

답변 생성 시 사용된 인용 정보입니다.

data

응답 예시

응답 예시는 다음과 같습니다.

{
    "code": 200,
    "message": null,
    "data": {
        "results": [
            {
                "blockId": "START",
                "value": "사람들이 이 기술을 뭐라고 불러?"
            },
            {
                "blockId": "QUERY_REWRITE",
                "value": "네이버의 기술에 대해 사람들이 사용하는 명칭은 무엇인가요?",
                "metadata": {
                    "finishReason": "length",
                    "chatModel": "HyperClovaX",
                    "modelName": "HCX-007",
                    "inputTokens": 1355,
                    "outputTokens": 256,
                    "totalTokens": 1611
                }
            },
            {
                "blockId": "RETRIEVAL",
                "value": [
                    {
                        "docId": "c69cd98c0674e1a8a814",
                        "fileName": "leap-25.docx",
                        "score": 0.04168701171875,
                        "rank": 1,
                        "text": "네이버는 방대한 도시 전체를 디지털 트윈 데이터로 제작할 수 있는 독자적인 기술을 가지고 있는데요. 네이버는 항공 사진과 사진 측량 기술을 활용해 메가시티 규모의 디지털 트윈 데이터를 빠르고 정확하게 제작할 수 있으며, AI 기술을 통해 실제와 동일한 3차원 공간으로 복원했습니다. 이미 한국에서는 네이버페이를 통해 실제 단지를 방문하지 않더라도 부동산 매물 정보 확인을 할 수 있는 VR 서비스를 제공하고 있습니다.",
                        "start_offset": 4025,
                        "end_offset": 4258,
                        "chunk_no": 1,
                        "page_no": 0
                    }
                ]
            },
            {
                "blockId": "CONDITIONAL",
                "value": "branch1"
            },
            {
                "blockId": "GENERATOR",
                "value": "네이버가 가진 이 기술은 '디지털 트윈(Digital Twin)'이라고 불립니다. 디지털 트윈이란 현실 세계의 물리적인 개체를 가상 세계에 똑같이 만들어 실시간으로 모니터링하고 제어하는 기술을 말합니다. 쉽게 말해, 실제 공간을 컴퓨터 안에 쌍둥이처럼 만든 것입니다.\n\n예를 들어, 우리가 살고 있는 동네나 학교 건물을 디지털 트윈으로 만들면, 컴퓨터 화면에서 실제로 그 장소에 가보지 않고도 건물 안팎을 둘러볼 수 있고, 거리를 걷거나 주변 시설을 확인할 수도 있습니다. 또한, 날씨 변화나 교통 상황 등을 시뮬레이션하여 미래의 상황을 예측하거나 문제를 해결하는 데에도 활용할 수 있답니다.\n\n네이버는 이러한 디지털 트윈 기술을 활용해서 다양한 분야에서 새로운 서비스들을 개발하고 있습니다. 예를 들면, 온라인 쇼핑을 하면서 옷을 직접 입어본 것처럼 볼 수 있게 해주는 가상 피팅룸이나, 집 내부를 3D로 탐험하며 인테리어를 꾸며보는 기능 등이 이에 해당됩니다.\n\n이렇게 디지털 트윈 기술은 우리의 일상생활을 더욱 편리하게 해주고 상상력을 자극하는 멋진 도구랍니다. 앞으로도 계속해서 발전하면서 더 많은 곳에서 유용하게 쓰일 것으로 기대되고 있습니다.",
                "metadata": {
                    "finishReason": "length",
                    "chatModel": "HyperClovaX",
                    "modelName": "HCX-007",
                    "inputTokens": 1355,
                    "outputTokens": 256,
                    "totalTokens": 1611,
                    "thinkingContent": "사용자가 디지털 트윈 기술의 개념과 네이버의 적용 사례를 묻고 있군. 기술 자체의 정의부터 시작해서 실제 활용 예시까지 단계적으로 설명해야겠다."
                }
            }
        ],
        "references": [
            {
                "name": "RETRIEVAL",
                "data": [
                    {
                        "docId": "c69cd98c0674e1a8a814",
                        "fileName": "leap-25.docx",
                        "text": "네이버는 방대한 도시 전체를 디지털 트윈 데이터로 제작할 수 있는 독자적인 기술을 가지고 있는데요. 네이버는 항공 사진과 사진 측량 기술을 활용해 메가시티 규모의 디지털 트윈 데이터를 빠르고 정확하게 제작할 수 있으며, AI 기술을 통해 실제와 동일한 3차원 공간으로 복원했습니다. 이미 한국에서는 네이버페이를 통해 실제 단지를 방문하지 않더라도 부동산 매물 정보 확인을 할 수 있는 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 다섯 가지입니다.

• step: 답변 생성 전 블록별 처리 결과 출력 (verbose = true인 경우)
• ping: 답변 생성 전 대기 중에 Read Timeout을 방지하기 위해 데이터 출력 (답변 생성 전까지 1초마다)
• token: 생성 중인 답변의 토큰을 실시간으로 출력
• result: 최종 답변 출력
• error: 답변 생성 중 에러 발생 시 출력

응답 헤더

응답 헤더에 대한 설명은 다음과 같습니다.

응답 바디

응답 바디는 이벤트 타입에 따라 상이합니다.

step 이벤트

step 이벤트에 대한 설명은 다음과 같습니다.

문서 검색 결과

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": "네이버의 기술에 대해 사람들이 사용하는 명칭은 무엇인가요?"
}

event: step
data: {
    "blockName": "RETRIEVAL",
    "blockResult": [
        {
            "docId": "{docId}",
            "fileName": "leap-25.docx",
            "score": 0.04168701171875,
            "rank": 1,
            "text": "네이버는 방대한 도시 전체를 디지털 트윈 데이터로 제작할 수 있는 독자적인 기술을 가지고 있는데요. 네이버는 항공 사진과 사진 측량 기술을 활용해 메가시티 규모의 디지털 트윈 데이터를 빠르고 정확하게 제작할 수 있으며, AI 기술을 통해 실제와 동일한 3차원 공간으로 복원했습니다. 이미 한국에서는 네이버페이를 통해 실제 단지를 방문하지 않더라도 부동산 매물 정보 확인을 할 수 있는 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": ""
    },
    "status": "IN_PROGRESS",
    "references": [],
    "rateLimit": null,
    "metadata": {}
}

...

event: token
data: {
    "message": {
        "role": "assistant",
        "content": "",
        "thinkingContent": "사용자가"
    },
    "status": "IN_PROGRESS",
    "references": [],
    "rateLimit": null,
    "metadata": {}
}

...

event: token
data: {
    "message": {
        "role": "assistant",
        "content": " 디지털"
    },
    "status": "IN_PROGRESS",
    "references": [],
    "rateLimit": null,
    "metadata": {}
}

...

event: result
data: {
    "message": {
        "role": "assistant",
        "content": "네이버가 가진 이 기술은 '디지털 트윈(Digital Twin)'이라고 불립니다.[†1] 디지털 트윈이란 현실 세계의 물리적인 대상을 가상 세계에 똑같이 만들어내는 것을 의미하며, 이를 통해 다양한 시뮬레이션 및 분석을 수행하여 의사결정에 도움을 줄 수 있습니다.\n\n예를 들어, 우리가 종이 위에 집을 그린다고 생각해 볼까요? 실제로 지을 집과 똑같은 그림을 그리는 거예요. 그리고 나서, 그 그림 위에서 여러 가지 계획을 세우고 실험도 해볼 수 있죠. 만약 비가 올 때 물이 어떻게 흐르는지 알고 싶다면, 그림에서 비를 내려보면서 결과를 관찰하는 것처럼 말이죠.\n\n이렇게 만들어진 가상의 세계는 실제 건물이나 도시를 짓기 전에 미리 여러 상황을 시험해 볼 수 있게 해주어 시간과 비용을 절약하게 도와줍니다. 또한, 실제 건물을 관리하는 데에도 큰 도움이 됩니다. 예를 들면, 건물 안에 있는 기계들이 제대로 작동하는지, 에너지를 효율적으로 사용하고 있는지 등을 모니터링해서 문제가 생기기 전에 미리 조치를 취할 수 있답니다.\n\n네이버는 이러한 디지털 트윈 기술을 활용하여 한국의 여러 지역을 가상 세계에 재현하고, 이를 기반으로 한 다양한 서비스들을 개발하고 있습니다.[†1] 그래서 우리는 직접 그곳에 가지 않고도 컴퓨터나 스마트폰으로 해당 지역의 정보를 확인하고 체험할 수 있게 되는 것이랍니다. 정말 신기하죠?",
        "thinkingContent": "사용자가 디지털 트윈 기술의 개념과 네이버의 적용 사례를 묻고 있군. 기술 자체의 정의부터 시작해서 실제 활용 예시까지 단계적으로 설명해야겠다."
    },
    "status": "COMPLETE",
    "references": [
        {
            "name": "RETRIEVAL",
            "data": [
                {
                    "docId": "12345",
                    "fileName": "leap-25.docx",
                    "text": "네이버는 방대한 도시 전체를 디지털 트윈 데이터로 제작할 수 있는 독자적인 기술을 가지고 있는데요. 네이버는 항공 사진과 사진 측량 기술을 활용해 메가시티 규모의 디지털 트윈 데이터를 빠르고 정확하게 제작할 수 있으며, AI 기술을 통해 실제와 동일한 3차원 공간으로 복원했습니다. 이미 한국에서는 네이버페이를 통해 실제 단지를 방문하지 않더라도 부동산 매물 정보 확인을 할 수 있는 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": {
        "finishReason": "stop",
        "chatModel": "HyperClovaX",
        "modelName": "HCX-005",
        "inputTokens": 267,
        "outputTokens": 262,
        "totalTokens": 529
    }
}