Classic/VPC 환경에서 이용 가능합니다.
외부 함수나 API를 호출해 동적으로 정보를 가져오거나 작업을 수행할 수 있는 Function calling 기능이 지원되는 v3 Chat Completions에 대해 설명합니다.
요청
요청 형식을 설명합니다. 요청 형식은 다음과 같습니다.
메서드 | URI |
---|---|
POST | /v3/chat-completions/{modelName} |
요청 헤더
요청 헤더에 대한 설명은 다음과 같습니다.
헤더 | 필수 여부 | 설명 |
---|---|---|
Authorization |
Required | 인증을 위한 API 키 <예시> Bearer nv-************ |
X-NCP-CLOVASTUDIO-REQUEST-ID |
Optional | 요청에 대한 아이디 |
Content-Type |
Required | 요청 데이터의 형식
|
Function calling은 스트림 출력을 지원하지 않으므로 Accept: text/event-stream
요청 시 에러가 발생합니다.
요청 경로 파라미터
요청 경로 파라미터에 대한 설명은 다음과 같습니다.
필드 | 타입 | 필수 여부 | 설명 |
---|---|---|---|
modelName |
Enum | Required | 모델 이름
|
HyperCLOVA X Function calling은 HCX-005와 HCX-DASH-002의 Chat Completions v3, 오픈AI 호환 API에서만 사용할 수 있습니다.
요청 바디
요청 바디에 대한 설명은 다음과 같습니다.
필드 | 타입 | 필수 여부 | 설명 |
---|---|---|---|
messages |
Array | Required | 대화 메시지 |
topP |
Double | Optional | 생성 토큰 후보군을 누적 확률을 기반으로 샘플링
|
topK |
Integer | Optional | 생성 토큰 후보군에서 확률이 높은 K개를 후보로 지정하여 샘플링
|
maxTokens |
Integer | Optional | 최대 생성 토큰 수maxTokens ≤ 모델 최대값 |
temperature |
Double | Optional | 생성 토큰에 대한 다양성 정도(설정값이 높을수록 다양한 문장 생성)
|
repetitionPenalty |
Double | Optional | 같은 토큰을 생성하는 것에 대한 패널티 정도(설정값이 높을수록 같은 결괏값을 반복 생성할 확률 감소)
|
stop |
Array | Optional | 토큰 생성 중단 문자
|
seed |
Integer | Optional | 모델 반복 실행 시 결괏값의 일관성 수준 조정
|
tools |
Array | Optional | Function Calling 사용 가능 도구 목록: tools |
toolChoice |
String | Object | Optional | Function Calling 도구 호출 동작 방식
|
toolChoice.type |
String | Optional | Function Calling 모델이 호출할 도구 유형 |
toolChoice.function |
Object | Optional | Function Calling 모델이 호출할 도구
|
toolChoice.function.name |
String | Optional | Function Calling 모델이 호출할 도구 이름 |
messages
messages
에 대한 설명은 다음과 같습니다.
필드 | 타입 | 필수 여부 | 설명 |
---|---|---|---|
role |
Enum | Required | 대화 메시지 역할
|
content |
String | Required | 대화 메시지 내용
|
toolCalls |
Array | - | assistant의 호출 도구 정보 |
toolCallId |
String | - | 도구 아이디
|
tools
tools
에 대한 설명은 다음과 같습니다.
필드 | 타입 | 필수 여부 | 설명 |
---|---|---|---|
type |
String | Required | 도구 유형
|
function |
Object | Required | 호출 function 정보 |
function.name |
String | Required | function 이름 |
function.description |
String | Required | function 설명 |
function.parameters |
Object | Required | function 사용 시 전달되는 매개변수
|
toolCalls
toolCalls
에 대한 설명은 다음과 같습니다.
필드 | 타입 | 필수 여부 | 설명 |
---|---|---|---|
id |
String | - | 도구 식별자 |
type |
String | - | 도구 유형
|
function |
Object | - | 호출 function 정보 |
function.name |
String | - | function 이름 |
function.arguments |
Object | - | function 사용 시 전달되는 매개변수 |
일부 필드 입력 시 다음 내용을 확인해 주십시오.
- HCX-005
- 입력 토큰과 출력 토큰의 합은 128,000 토큰을 초과할 수 없습니다.
- 입력 토큰은 최대 128,000 토큰까지 가능합니다.
- 모델에 요청할 출력 토큰(maxTokens)은 최대 4,096 토큰까지 가능합니다.
- HCX-DASH-002
- 입력 토큰과 출력 토큰의 합은 32,000 토큰을 초과할 수 없습니다.
- 입력 토큰은 최대 32,000 토큰까지 가능합니다.
- 모델에 요청할 출력 토큰(maxTokens)은 최대 4,096 토큰까지 가능합니다.
- 이미지 입력과 Function calling 요청을 동시에 할 수 없습니다.
응답
응답 형식을 설명합니다.
응답 헤더
응답 헤더에 대한 설명은 다음과 같습니다.
헤더 | 필수 여부 | 설명 |
---|---|---|
Content-Type |
- | 응답 데이터의 형식
|
응답 바디
응답 바디에 대한 설명은 다음과 같습니다.
필드 | 타입 | 필수 여부 | 설명 |
---|---|---|---|
status |
Object | - | 응답 상태 |
result |
Object | - | 응답 결과 |
result.created |
Integer | - | 응답 날짜(Unix timestamp miliseconds 형식) |
result.usage |
Object | - | 토큰 사용량 |
result.usage.completionTokens |
Integer | - | 생성 토큰 수 |
result.usage.promptTokens |
Integer | - | 입력(프롬프트) 토큰 수 |
result.usage.totalTokens |
Integer | - | 전체 토큰 수
|
result.message |
Object | - | 대화 메시지 |
result.message.role |
Enum | - | 대화 메시지 역할
|
result.message.content |
String | - | 대화 메시지 내용 |
result.message.toolCalls |
Array | - | [toolCalls]((/docs/clovastudio-chatcompletionsv3-fc#toolCalls) |
result.finishReason |
String | - | 토큰 생성 중단 이유(일반적으로 마지막 이벤트에 전달)
|
result.seed |
Integer | - | 입력 seed 값(0 입력 또는 미입력 시 랜덤 값 반환) |
toolCalls
toolCalls
에 대한 설명은 다음과 같습니다.
필드 | 타입 | 필수 여부 | 설명 |
---|---|---|---|
id |
String | - | 도구 식별자 |
type |
String | - | 도구 유형
|
function |
Object | - | 호출 function 정보 |
function.name |
String | - | function 이름 |
function.arguments |
Object | - | function 사용 시 전달되는 매개변수 |
동작 방식
요청과 응답을 포함한 Function calling의 동작 방식은 다음과 같습니다.
Step 1. 입력 및 함수 정의 전달
질의 내용을 입력하고 함수 정의를 전달합니다. 요청 예시는 다음과 같습니다.
- cURL
curl --location --request POST 'https://clovastudio.stream.gov-ntruss.com/testapp/v3/chat-completions/{modelName}' \ --header 'Authorization: Bearer <api-key>' \ --header 'X-NCP-CLOVASTUDIO-REQUEST-ID: {Request ID}' --header 'Content-Type: application/json' \ --data '{ "messages" : [ { "content" : "오늘 서울 날씨 알려줘", "role" : "user" } ], "tools" : [ { "function" : { "description" : "날씨를 알려줄 수 있는 도구", "name" : "get_weather", "parameters" : { "properties" : { "location" : { "description" : "서울, 대전, 부산 등의 도시 이름", "type" : "string" }, "unit" : { "enum" : [ "celsius", "fahrenheit" ], "type" : "string" }, "date" : { "description" : "2023-08-01 같은 형태의 날짜 문자열. 날씨를 알고 싶은 날짜", "type" : "string" } }, "required" : [ "location" ], "type" : "object" } } }], "toolChoice" : "auto" }'
- Python
import requests API_KEY = "YOUR_API_KEY" REQUEST_ID = "YOUR_REQUEST_ID" url = "https://clovastudio.stream.gov-ntruss.com/testapp/v3/chat-completions/{modelName}" headers = { "Authorization": f"Bearer {API_KEY}", "X-NCP-CLOVASTUDIO-REQUEST-ID": REQUEST_ID, "Content-Type": "application/json" } data = { "messages": [ { "content": "내일 서울 날씨 어때?", "role": "user" } ], "tools": [ { "type": "function", "function": { "description": "날씨를 알려줄 수 있는 도구", "name": "get_weather", "parameters": { "type": "object", "properties": { "location": { "description": "서울, 대전, 부산 등의 도시 이름", "type": "string" }, "unit": { "type": "string", "enum": ["celsius", "fahrenheit"] }, "date": { "description": "2025-03-21 같은 형태의 날짜 문자열. 날씨를 알고 싶은 날짜", "type": "string" } }, "required": ["location"] } } } ], "toolChoice": "auto" } response = requests.post(url, headers=headers, json=data) result = response.json() print(result)
Step 2. 호출할 함수 및 인수 반환
호출할 함수와 인수 정보가 반환됩니다. 응답 예시는 다음과 같습니다.
{
"status": {
"code": "20000",
"message": "OK"
},
"result": {
"message": {
"role": "assistant",
"content": "",
"toolCalls": [
{
"id": "call_s83AKVWrPPI6bCTLl5kFGtyo",
"type": "function",
"function": {
"name": "get_weather",
"arguments": {
"location": "서울",
"unit": "celsius",
"date": "2025-04-10"
}
}
}
]
},
"finishReason": "tool_calls",
"created": 1744218663,
"seed": 1354242582,
"usage": {
"promptTokens": 134,
"completionTokens": 48,
"totalTokens": 315
}
}
}
Step 3. 응답 결과 기반으로 실제 함수 호출
Step 2.의 응답 결과를 기반으로 실제 함수를 호출합니다. 요청 예시는 다음과 같습니다.
- cURL
# <예시> 다음과 같은 API를 호출한다고 가정합니다. # GET https://weather.example.com?location=서울&unit=celsius&date=2025-04-10 curl --request GET 'https://weather.example.com?location=서울&unit=celsius&date=2025-04-10'
- Python
""" <예시> 다음과 같은 함수를 구성했다고 가정합니다. def get_weather(location, unit="celsius", date=None): response = requests.get(f"https://weather.example.com?location={location}&unit={unit}&date={date}") data = response.json() return data """ tool_call = result["result"]["message"]["toolCalls"][0] function_name = tool_call["function"]["name"] arguments = tool_call["function"]["arguments"] if function_name == "get_weather": function_result = get_weather(**arguments)
응답 예시는 다음과 같습니다.
{ "location": "서울", "temperature": "17도", "condition": "맑음" }
Step 4. 함수 실행 결과 전달
함수 실행 결과를 전달합니다. 요청 예시는 다음과 같습니다.
-
cURL
curl --location --request POST 'https://clovastudio.stream.gov-ntruss.com/testapp/v3/chat-completions/{modelName}' \ --header 'Authorization: Bearer <api-key>' \ --header 'X-NCP-CLOVASTUDIO-REQUEST-ID: {Request ID}' --header 'Content-Type: application/json' \ --data '{ "messages": [ { "role": "user", "content": "내일 서울 날씨 어때?" }, { "role": "assistant", "content": "", "toolCalls": [ { "id": "call_s83AKVWrPPI6bCTLl5kFGtyo", "type": "function", "function": { "name": "get_weather", "arguments": { "location": "서울", "unit": "celsius", "date": "2025-04-10" } } } ] }, { "role": "tool", "toolCallId": "call_s83AKVWrPPI6bCTLl5kFGtyo", "content": "{ \"location\": \"서울\", \"temperature\": \"17도\", \"condition\": \"맑음\" }" } ], "seed": 0, "topP": 0.8, "topK": 0, "maxTokens": 1024, "temperature": 0, "repeatPenalty": 1.1, "stopBefore": [] }'
-
Python
url = "https://https://clovastudio.stream.gov-ntruss.com/testapp/v3/chat-completions/{modelName}" headers = { "Authorization": f"Bearer {API_KEY}", "X-NCP-CLOVASTUDIO-REQUEST-ID": REQUEST_ID, "Content-Type": "application/json" } data = { "messages": [ { "role": "user", "content": "내일 서울 날씨 어때?" }, { "role": "assistant", "content": "", "toolCalls": [ { "id": "call_s83AKVWrPPI6bCTLl5kFGtyo", "type": "function", "function": { "name": "get_weather", "arguments": { "location": "서울", "unit": "celsius", "date": "2025-04-10" } } } ] }, { "role": "tool", "toolCallId": "call_s83AKVWrPPI6bCTLl5kFGtyo", "content": str(function_result) } ], "seed": 0, "topP": 0.8, "topK": 0, "maxTokens": 1024, "temperature": 0, "repeatPenalty": 1.1, "stopBefore": [] } response = requests.post(url, headers=headers, json=data) result = response.json() print(result)
Step 5. 최종 텍스트 응답 반환
최종 반환된 응답 결과의 텍스트를 확인합니다.
{
"status": {
"code": "20000",
"message": "OK"
},
"result": {
"message": {
"role": "assistant",
"content": "내일 서울의 날씨는 맑을 예정이며, 기온은 17도로 예상됩니다. 따뜻한 봄날씨가 될 것 같으니 외출하기에 좋은 날이 될 것 같아요!"
},
"finishReason": "stop",
"created": 1744218776,
"seed": 2744409319,
"usage": {
"promptTokens": 88,
"completionTokens": 37,
"totalTokens": 125
}
}
}
실패
호출이 실패한 경우의 응답 예시는 다음과 같습니다.