--- title: "RAG Reasoning" slug: "clovastudio-ragreasoning" updated: 2026-04-23T08:55:44Z published: 2026-04-23T09:02:20Z --- > ## Documentation Index > Fetch the complete documentation index at: https://api.ncloud-docs.com/llms.txt > Use this file to discover all available pages before exploring further. # RAG Reasoning Classic/VPC 환경에서 이용 가능합니다. 신뢰도를 높이는 인용 출처, 인용 출처 인덱싱 표기 등의 답변 유형에 맞춰 학습한 RAG Reasoning 모델을 활용하여 근거 기반의 RAG 답변 생성합니다. RAG Reasoning은 Function calling 형식으로 엔진을 호출합니다. 단일 혹은 여러 개의 RAG 함수를 지정할 수 있으며, LLM이 상황에 맞게 자율적으로 최적의 함수를 선택하여 검색 증강 생성 작업을 수행할 수 있습니다. [리랭커](/docs/clovastudio-reranker)와 체이닝하여 사용하는 경우, 좀 더 안정적인 결괏값을 얻을 수 있습니다. ## 요청 요청 형식을 설명합니다. 요청 형식은 다음과 같습니다. | 메서드 | URI | | --- | --- | | POST | /v1/api-tools/rag-reasoning | ### 요청 헤더 CLOVA Studio API에서 공통으로 사용하는 헤더에 대한 정보는 [CLOVA Studio 요청 헤더](/docs/ai-naver-clovastudio-summary#%EC%9A%94%EC%B2%AD%ED%97%A4%EB%8D%94)를 참조해 주십시오. ### 요청 바디 요청 바디에 대한 설명은 다음과 같습니다. | 필드 | 타입 | 필수 여부 | 설명 | | --- | --- | --- | --- | | `messages` | Array | Required | 대화 메시지: [messages](/docs/clovastudio-ragreasoning#messages) | | `topP` | Double | Optional | 생성 토큰 후보군을 누적 확률을 기반으로 샘플링 - 0.00 ＜ `topP` ≤ 1.00 (기본값: 0.8) | | `topK` | Integer | Optional | 생성 토큰 후보군에서 확률이 높은 K개를 후보로 지정하여 샘플링 - 0 ≤ `topK` ≤ 128 (기본값: 0) | | `maxTokens` | Integer | Optional | 최대 생성 토큰 수 - 1024 ≤ `maxTokens` ＜ 4096 (기본값: 1024) | | `temperature` | Double | Optional | 생성 토큰에 대한 다양성 정도(설정값이 높을수록 다양한 문장 생성) - 0.00 ＜ `temperature` ≤ 1.00 (기본값: 0.50) | | `repetitionPenalty` | Double | Optional | 같은 토큰을 생성하는 것에 대한 패널티 정도(설정값이 높을수록 같은 결괏값을 반복 생성할 확률 감소) - 0.0 ＜ `repetitionPenalty` ≤ 2.0 (기본값: 1.1) | | `stop` | Array | Optional | 토큰 생성 중단 문자 - [](기본값) | | `seed` | Integer | Optional | 모델 반복 실행 시 결괏값의 일관성 수준 조정 - 0: 일관성 수준 랜덤 적용 (기본값) - 1 ≤ `seed` ≤ 4294967295: 일관되게 생성하고자 하는 결괏값의 `seed` 값 또는 사용자가 지정하고자 하는 `seed` 값 | | `includeAiFilters` | Boolean | Optional | AI 필터(생성된 결괏값에 대해 욕설, 비하/차별/혐오, 성희롱/음란 등 카테고리별로 해당하는 정도) 결과 표시 여부 - `true` (기본값) \| `false` - `true`: 표시 - `false`: 표시 안 함 | | `tools` | Array | Required | `Function calling` 사용 가능 도구 목록: [tools](/docs/clovastudio-ragreasoning#tools) | | `toolChoice` | String \| Object | Optional | `Function calling` 도구 호출 동작 방식 - `auto` : 모델이 도구 자동 호출(String) - `none` : 모델이 도구 호출 없이 일반 답변 생성(String) - 모델이 특정도구 강제 호출(Object) | | `toolChoice.type` | String | Optional | `Function calling` 모델이 호출할 도구 유형 | | `toolChoice.function` | Object | Optional | `Function calling` 모델이 호출할 도구 - `function`(유효 값) | | `toolChoice.function.name` | String | Optional | `Function calling` 모델이 호출할 도구 이름 | 참고 RAG Reasoning 의 최대 입력 토큰 수는 128,000이며, 최대 출력 토큰 수는 4,096입니다. #### `messages` `messages`에 대한 설명은 다음과 같습니다. | 필드 | 타입 | 필수 여부 | 설명 | | --- | --- | --- | --- | | `role` | Enum | Required | 대화 메시지 역할 - `system` \| `user` \| `assistant` \| `tool` - `system`: 역할을 규정하는 지시문 - `user`: 사용자의 발화 또는 질문 - `assistant`: 사용자의 발화 또는 질문에 대한 답변 - `tool`: assistant(모델)가 호출한 함수의 실행 결과 | | `content` | String | Required | 대화 메시지 내용 - 텍스트 입력(String) | | `toolCalls` | Array | Conditional | assistant의 호출 도구 정보 - `role`이 `tool`인 경우, assistant의 [toolCalls](/docs/clovastudio-ragreasoning#toolCalls) 요청과 같이 입력 | | `toolCallId` | String | Conditional | 도구 아이디 - `role`이 `tool`인 경우, 필수 입력 - assistant의 [toolCalls](/docs/clovastudio-ragreasoning#toolCalls) 요청과 연결하는 용도 | 참고 `role`이 `tool`인 경우, `messages`의 `content`에는 검색 데이터베이스 또는 검색 API에서 검색한 문서 목록(`search_result`)를 추가해야 합니다. 검색 결과(`search_result`)에 `id: {문서 고유 아이디}`, `doc: {검색한 문서 원본}`을 포함하여 RAG 답변의 인용 표기에 활용될 수 있도록 구성해 주십시오. 예시는 다음과 같습니다. ``` { "role": "tool", "content": "[ { \"search_result\": [{\"id\": \"doc-1493058999\", \"doc\": \"네이버 계정으로 로그인은 개인 회원만 가능하며 사업자 회원은 불가능합니다.\" }, ... ]" } ``` #### `tools` `tools`에 대한 설명은 다음과 같습니다. | 필드 | 타입 | 필수 여부 | 설명 | | --- | --- | --- | --- | | `type` | String | Required | 도구 유형 - `function`(유효 값) | | `function` | Object | Required | 호출 `function` 정보 | | `function.name` | String | Required | `function` 이름 | | `function.description` | String | Required | `function` 설명 | | `function.parameters` | Object | Required | `function` 사용 시 전달되는 매개변수 - `properties`, `required` - 입력: [동작 방식](/release-20260423/docs/clovastudio-chatcompletionsv3-fc#%EB%8F%99%EC%9E%91-%EB%B0%A9%EC%8B%9D) 참조 - 형식: [JSON Schema reference](https://json-schema.org/understanding-json-schema/reference) 참조 | #### `toolCalls` `toolCalls`에 대한 설명은 다음과 같습니다. | 필드 | 타입 | 필수 여부 | 설명 | | --- | --- | --- | --- | | `id` | String | - | 도구 식별자 | | `type` | String | - | 도구 유형 - `function`(유효 값) | | `function` | Object | - | 호출 `function` 정보 | | `function.name` | String | - | `function` 이름 | | `function.arguments` | Object | - | `function` 사용 시 전달되는 매개변수 | ### 요청 예시 요청 예시는 다음과 같습니다. - Step 1. `role: user`에 질의 내용을 입력하고 답변 생성에 가장 적합한 함수를 호출 ([응답 확인](/docs/clovastudio-ragreasoning#%EC%9D%91%EB%8B%B5%EC%98%88%EC%8B%9C1)) ``` curl --location --request POST 'https://clovastudio.stream.ntruss.com/v1/api-tools/rag-reasoning' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data-raw '{ "messages": [ { "content": "A100 GPU 빌리는 방법", "role": "user" } ], "tools": [ { "function": { "description": "NCloud 관련 검색을 할 때 사용하는 도구입니다.\n나누어 질문해야 하는 경우 쿼리를 쪼개 나누어서 도구를 사용합니다.\n정보를 찾을 수 없었던 경우, 최종 답을 하지 않고 suggested_queries를 참고하여 도구를 다시 사용할 수 있습니다.", "name": "ncloud_cs_retrieval", "parameters": { "properties": { "query": { "description": "사용자의 검색어를 정제해서 넣으세요.", "type": "string" } }, "required": [ "query" ], "type": "object" } }, "type": "function" } ], "toolChoice": "auto", "maxTokens": 1024 }' ``` - Step 2. 최종 답변을 생성하기 위한 `role: tool`을 포함한 요청 ([응답 확인](/docs/clovastudio-ragreasoning#%EC%9D%91%EB%8B%B5%EC%98%88%EC%8B%9C2)) ``` curl --location --request POST 'https://clovastudio.stream.ntruss.com/v1/api-tools/rag-reasoning' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data-raw '{ "messages": [ { "content": "A100 GPU 빌리는 방법", "role": "user" }, { "role": "assistant", "content": "", "toolCalls": [ { "id": "call_enTEYb0kWBjOwtkngbl7FGTm", "type": "function", "function": { "name": "ncloud_cs_retrieval", "arguments": { "query": "A100 GPU 빌리는 방법" } } } ] }, { "content": "{\"search_result\": [{\"id\": \"doc-179\", \"doc\": \"GPU A100은 KR-1에서만 생성 가능합니다. A100 생성 시에는 KR-1의 Subnet을 선택하여 주시기 바랍니다. GPU 서버는 기업 회원에 한하여 최대 5대까지 생성할 수 있습니다.\"}, {\"id\": \"doc-248\", \"doc\": \"네이버 클라우드 플랫폼 콘솔의 Services > Compute > Server 메뉴에서 GPU A100 서버를 생성할 수 있습니다. 자세한 생성 방법은 서버 생성 가이드를 참고해 주십시오.\"}, {\"id\": \"doc-156\", \"doc\": \"더 많은 GPU 서버가 필요하거나 GPU 서버 생성이 필요한 개인 회원의 경우 FAQ를 참고하여 고객 지원으로 문의해 주십시오.\"}]}", "role": "tool", "toolCallId": "call_enTEYb0kWBjOwtkngbl7FGTm" } ], "tools": [ { "function": { "description": "NCloud 관련 검색을 할 때 사용하는 도구입니다.\n나누어 질문해야 하는 경우 쿼리를 쪼개 나누어서 도구를 사용합니다.\n정보를 찾을 수 없었던 경우, 최종 답을 하지 않고 suggested_queries를 참고하여 도구를 다시 사용할 수 있습니다.", "name": "ncloud_cs_retrieval", "parameters": { "properties": { "query": { "description": "사용자의 검색어를 정제해서 넣으세요.", "type": "string" } }, "required": [ "query" ], "type": "object" } }, "type": "function" } ] }' ``` ## 응답 응답 형식을 설명합니다. ### 응답 헤더 응답 헤더에 대한 설명은 다음과 같습니다. | 헤더 | 필수 여부 | 설명 | | --- | --- | --- | | `Content-Type` | - | 응답 데이터의 형식 - `application/json` | ### 응답 바디 응답 바디에 대한 설명은 다음과 같습니다. | 필드 | 타입 | 필수 여부 | 설명 | | --- | --- | --- | --- | | `status` | Object | - | [응답 상태](/docs/ai-naver-clovastudio-summary#%EC%9D%91%EB%8B%B5) 참조 | | `result` | Object | - | 응답 결과 | | `result.message` | ChatMessage | - | 대화 메시지 목록 | | `result.message.role` | Enum | - | 대화 메시지 역할 - `system` \| `user` \| `assistant` - `system`: 역할을 규정하는 지시문 - `user`: 사용자의 발화 또는 질문 - `assistant`: 모델의 답변 | | `result.message.content` | String | - | 대화 메시지 내용 | | `result.message.thinkingContent` | String | - | 모델의 의사 결정 흐름 | | `result.message.toolCalls` | Array | - | [toolCalls](/docs/clovastudio-ragreasoning#toolCalls_response) | | `result.usage` | Object | - | 토큰 사용량 | | `result.usage.completionTokens` | Integer | - | 생성 토큰 수 | | `result.usage.promptTokens` | Integer | - | 입력(프롬프트) 토큰 수 | | `result.usage.totalTokens` | Integer | - | 전체 토큰 수 - 생성 토큰 수+입력 토큰 수 | #### `toolCalls` `toolCalls`에 대한 설명은 다음과 같습니다. | 필드 | 타입 | 필수 여부 | 설명 | | --- | --- | --- | --- | | `id` | String | - | 도구 식별자 | | `type` | String | - | 도구 유형 - `function`(유효값) | | `function` | Object | - | 호출 `function` 정보 | | `function.name` | String | - | `function` 이름 | | `function.arguments` | Object | - | `function` 사용 시 전달되는 매개변수 | ### 응답 예시 응답 예시는 다음과 같습니다. - Step 1.에 대한 응답 예시 ([요청 확인](/docs/clovastudio-ragreasoning#%EC%9A%94%EC%B2%AD%EC%98%88%EC%8B%9C1)) ``` { "status": { "code": "20000", "message": "OK" }, "result": { "message": { "role": "assistant", "content": "", "thinkingContent": "사용자가 \"A100 GPU 빌리는 방법\"에 대해 문의했습니다. 이 질문에 대한 답변을 찾기 위해 'ncloud_cs_retrieval' 도구를 사용하여 관련 정보를 검색할 필요가 있습니다.", "toolCalls": [ { "id": "call_enTEYb0kWBjOwtkngbl7FGTm", "type": "function", "function": { "name": "ncloud_cs_retrieval", "arguments": { "query": "A100 GPU 빌리는 방법" } } } ] }, "usage": { "promptTokens": 135, "completionTokens": 84, "totalTokens": 219 } } } ``` - Step 2.에 대한 응답 예시 (LLM의 최종 답변 반환) ([요청 확인](/docs/clovastudio-ragreasoning#%EC%9A%94%EC%B2%AD%EC%98%88%EC%8B%9C2)) ``` { "status": { "code": "20000", "message": "OK" }, "result": { "message": { "role": "assistant", "content": "A100 GPU를 빌리는 방법은 네이버 클라우드 플랫폼 콘솔의 Services > Compute > Server 메뉴에서 GPU A100 서버를 생성할 수 있습니다. 그러나 GPU A100은 KR-1에서만 생성 가능하며, A100 생성 시에는 KR-1의 Subnet을 선택해야 합니다. 또한, GPU 서버는 기업 회원에 한하여 최대 5대까지 생성할 수 있습니다. 만약 더 많은 GPU 서버가 필요하거나 GPU 서버 생성이 필요한 개인 회원의 경우, FAQ를 참고하여 고객 지원으로 문의해 주십시오." }, "usage": { "promptTokens": 332, "completionTokens": 146, "totalTokens": 478 } } } ``` #### 실패 호출이 실패한 경우의 응답 예시는 다음과 같습니다. - [클라이언트 공통 오류 문제(4xx)](/release-20260423/docs/clovastudio-troubleshoot-c4xx) - [서버 공통 오류 문제(5xx)](/release-20260423/docs/clovastudio-troubleshoot-c5xx)