[NCloud] HyperCLOVA X Function Calling을 이용한 나만의 네이버 쇼핑 채팅 봇 만들기

안녕하세요.

 

이번 시간에는 네이버 클라우드 플랫폼 HyperCLOVA X의 신규 기능인 Function Calling에 대해 알아보겠습니다.

 

0. 업데이트 내용

HCX-005: 최대 128K context length를 지원하며, 이미지를 해석하고 이해할 수 있는 멀티모달 모델입니다.
HCX-DASH-002: 32K context length를 지원하는 경량화된 텍스트 특화 모델입니다.
두 모델 모두 Chat Completions v3 API 및 OpenAI 호환 API를 통해 사용하실 수 있습니다.
*중요) 이미지 입력과 Function calling 요청을 동시에 할 수 없습니다.

25년 4월 17일 네이버 클라우드 플랫폼의 HyperCLOVA가 대규모의 업데이트가 진행되었습니다.

핵심 내용은 신규 모델과 일부 기능(라우터와 Function Calling)이 업데이트되었습니다.

HCX-005 모델이 추가됨에 따라 이제 HCX에서도 멀티 모달을 이용한 서비스 구현이 가능해졌습니다.

 

실습 자료 추가) 25.05.27 네이버 클라우드 7월 웨비나 실습 자료

https://eveningdev.tistory.com/255

[NCloud] HyperCLOVA X Function Calling을 이용한 나만의 네이버 쇼핑 채팅 봇 만들기 - 실습 영상

실습 자료 패스워드: evening

 

1. HyperCLOVA X의 Function Calling이란?

Function Calling은 LLM(대형 언어 모델)이 외부 함수(또는 API)를 정확하게 호출할 수 있도록 설계된 기능입니다. 프롬프트를 통해 사용자의 요청을 받은 LLM이, 그 요청에 맞는 함수 이름과 인자 값을 추출하여, 개발자가 사전에 등록한 외부 함수를 호출하고, 그 결과를 다시 LLM이 사용자에게 자연어로 응답하는 방식입니다.

 

예를 들어, 사용자가 “내일 서울 날씨 알려줘”라고 요청하면, LLM은 getWeather(location="Seoul", date="tomorrow")라는 형태의 함수를 자동으로 구성하고 호출합니다. 결괏값(예: 흐리고 비, 최고기온 24도)이 반환되면, LLM은 이를 “내일 서울은 흐리고 비가 오며, 최고기온은 24도입니다.”처럼 자연스럽게 설명해 줍니다.

 

HCX-005 모델과, HCX-DASH-002 모델에서 Function calling 기능을 제공합니다.
Function calling 기능을 활용해 외부 함수나 API를 호출해 동적으로 정보를 가져오거나 작업을 수행할 수 있습니다.

 

2. Function Calling의 장/단점

1. Function Calling 장점

(1) 정확한 명령 실행

자연어 요청을 함수 호출로 변환함으로써, AI가 임의로 뇌피셜을 생성하는 것을 방지할 수 있습니다. (할루시네이션 방지)

예: “사용자 ID가 123인 고객의 주문 목록을 보여줘” → getOrdersByUserId(userId=123)

 

(2) 구현 간결성

함수 정의만 명확히 하면 복잡한 if-else 없이도 다양한 요청에 대응 가능합니다.

하나의 모델로 다양한 기능을 처리할 수 있어 챗봇/검색봇 개발이 쉬워졌습니다.

 

(3) 비즈니스 로직 분리

LLM은 사용자의 요청을 이해하고 API 호출을 구성하는 데 집중하고, 비즈니스 로직은 백엔드 함수가 담당하게 됩니다. 따라서 유지보수가 쉬워집니다.

 

(4) 멀티 함수 지원

사용자가 복합적인 요청 (예: "내일 날씨랑 일정도 알려줘")을 할 경우, 여러 함수를 순차적으로 호출해 처리 가능.

(10~20개 함수 사용 권장)

 

2. Function Calling의 단점

(1) 함수 설계 및 문서화 필요

함수 이름, 인자 타입, 설명 등을 JSON Schema 형태로 등록해야 함. 초반 설정 부담이 있을 수 있습니다.

 

(2) 모델 의존성

모델이 의도대로 정확한 함수 호출을 하지 못할 수 있음 → 프롬프트 튜닝 및 함수 설명 정교화 필요

 

(3) 보안 및 권한 문제

외부 API와 연동되므로, 민감한 기능을 호출할 경우 인증과 보안에 주의 필요

 

(4) 비동기 처리의 어려움

응답 시간이 긴 함수는 동기 방식 Function Calling에 부적합할 수 있음 (향후 개선 여지)

 

*중요 (참고 사항)
Function calling은 스트림 출력을 지원하지 않으므로 Accept: text/event-stream 요청 시 에러가 발생합니다.

 

3. Function Calling 동작 원리

다음은 Function Calling의 동작 원리입니다.

① 사용자 입력 [ 사용자 → 애플리케이션 ]

② 사용자 입력 & 함수 설명 [ 애플리케이션 → HCX ]

③ 함수 식별자 & 파라미터 [ HCX → 애플리케이션 ]

④ 요청 [ 애플리케이션 → API ] 

⑤ 응답 [ API → 애플리케이션 ]

⑥ API로부터 받은 응답 [ 애플리케이션 → HCX ]

⑦ 생성된 답변 [ HCX → 애플리케이션 ]

⑧ 최종 답변 [ 애플리케이션 → 사용자]

다음과 같이 기본적으로 8 단계를 거쳐서 사용자에게 응답을 반환합니다.

 

애플리케이션에서는 3 단계로 구성할 수 있습니다.

1단계: 모델이 호출할 함수 추론

2단계: 실제 함수 실행 (API 요청 및 응답)

3단계: 최종 응답 생성 (API 응답으로 HCX로 최종 응답 생성)

앞서 설명드린 동작 과정을 바탕으로, "사용자 입력 → 모델이 tool 선택 → 외부 함수 결과 전달 → 최종 응답 생성"이라는 흐름이 코드에서 어떻게 구현되는지 아래 예시를 참고해 주세요.

 

4. Function Calling 사용해 보기 (with. 네이버 쇼핑 API / Streamlit 사용)

(1) 네이버 개발자 센터 - 네이버 쇼핑 API 사용

https://developers.naver.com/main/

NAVER Developers

네이버 쇼핑 API를 사용하기 위해 다음과 같이 NAVER Developers 사이트를 통해 API 사용 신청을 진행합니다.

 

사용하는 API는 검색과 데이터랩 (쇼핑인사이트)를 선택한 후 naver_shopping이라고 하는 애플리케이션을 생성합니다.

 

다음과 같이 네이버 쇼핑 API를 사용하기 위한 애플리케이션 키 값을 확인할 수 있습니다.

 

(2) Postman을 통한 API 응답 확인

 

Headers 값에 네이버 API 키를 추가한 후 query를 합니다. 자세한 API 사용 방법은 위 링크에서 확인할 수 있습니다.

 

다음과 같이 네이버 API를 Postman을 이용하여 테스트해 볼 수 있습니다.

 

(3) Streamlit 파이썬 라이브러리 설치

# 가상 환경 생성
python -m venv venv

# Windows 가상 환경 적용
cd venv/scripts
activate

# Linux 가상 환경 적용
source venv/bin/activate

# 필요한 라이브러리 설치
pip install streamlit python-dotenv

* Streamlit Document

https://docs.streamlit.io/

Streamlit Docs

Streamlit 사용법이 나와 있는 Document입니다.

 

(4) HyperCLOVA X 설정하기

1. 테스트 앱 생성

# 테스트 앱 코드
# -*- coding: utf-8 -*-

import requests


class CompletionExecutor:
    def __init__(self, host, api_key, request_id):
        self._host = host
        self._api_key = api_key
        self._request_id = request_id

    def execute(self, completion_request):
        headers = {
            'Authorization': self._api_key,
            'X-NCP-CLOVASTUDIO-REQUEST-ID': self._request_id,
            'Content-Type': 'application/json; charset=utf-8',
            'Accept': 'text/event-stream'
        }

        with requests.post(self._host + '/testapp/v3/chat-completions/HCX-DASH-002',
                           headers=headers, json=completion_request, stream=True) as r:
            for line in r.iter_lines():
                if line:
                    print(line.decode("utf-8"))


if __name__ == '__main__':
    completion_executor = CompletionExecutor(
        host='https://clovastudio.stream.ntruss.com',
        api_key='Bearer <api-key>',
        request_id='b2faa0fe7ae541f584aadc8706ec021b'
    )

    preset_text = [{"role":"system","content":""}]

    request_data = {
        'messages': preset_text,
        'topP': 0.8,
        'topK': 0,
        'maxTokens': 256,
        'temperature': 0.5,
        'repetitionPenalty': 1.1,
        'stop': [],
        'includeAiFilters': True,
        'seed': 0
    }

    print(preset_text)
    completion_executor.execute(request_data)

 

2. API 키 발급

# 네이버 클라우드 플랫폼 API 키
HCX_API_KEY=""

# 네이버 개발자 센터 Client 키
NAVER_CLIENT_ID=""
NAVER_CLIENT_SECRET=""

다음과 같이 .env 파일에서 사용할 환경 변수를 만들어 줍니다.

 

(5) 테스트 코드 제공

https://github.com/wjsgur8530/naver_shopping

GitHub - wjsgur8530/naver_shopping

Function Calling을 실습해 볼 수 있는 코드를 제공하고 있으니 해당 코드로 실습을 진행해 주시면 됩니다.

 

(6) Function Calling 앱 요청 순서

1. API KEY 환경 및 프롬프트 (user, system, assistant) 설정

MODEL_NAME HCX_API_KEY NAVER_CLIENT_ID NAVER_CLIENT_SECRET

 

2. 모델에 요청 보내기 (항상 Tools 정보 포함)

sendInputAndFunctionDefinition

 

3. API에 요청 보내기

get_search_naver_shopping

 

4. 최종 응답을 위한 모델에 요청 보내기

sendFunctionResult Chat Completion

 

* Function Calling 기본 흐름

“사용자 입력” → “모델이 tool 선택” → 외부 함수 결과 전달” → “최종 응답 생성”

 

(7) 참고 사항

1. 사용자 질문에 Context를 유지하기 위해서는 Session_State를 이용한 Messages 관리 필요

2. AI가 Tools를 선택하지 않았을 때 응답할 수 있게 처리하면 사용성이 높아짐

 

5. Function Calling 성능 최적화하는 방법

1. 자세한 설명과 함께 직관적인 이름 사용하기

함수 및 매개변수의 이름은 쉽게 알아볼 수 있도록 명확하게 지정하는 것이 중요합니다. 약어나 줄임말은 지양하고, 함수가 언제 호출되어야 하는지 설명을 함께 제공하는 것이 좋습니다. 복잡한 함수의 경우, 각 매개변수가 어떤 역할을 수행하는지 설명해 주면 도움이 됩니다. 함수 설명은 최소 3~4 문장 이상으로 구성하여, 함수의 사용 시점과 제한 사항 그리고 매개변수가 함수의 동작에 미치는 영향을 포함합니다.

 

2. 명확한 매개변수 지정하기

직관적인 매개변수의 이름과 함께 설명을 제공합니다. 예를 들어, 날짜 형식을 필요로 하는 매개변수의 경우 YYYY-MM-DD 또는 DD/MM/YY와 같은 형식을 명확히 설명하여 사용자가 올바르게 입력할 수 있도록 합니다.

 

3. 열거형으로 명확한 매개변수 값 제한하기

가능하다면 매개변수에 열거형(enum)을 사용하여 값을 제한하는 것이 좋습니다. 예를 들어, 티셔츠의 사이즈를 선택할 때 S, M, L과 같은 옵션으로 값을 명확하게 제한하면 모델이 더 정확하게 작동할 수 있습니다. 이를 통해 잘못된 값이나 예상치 못한 값이 반환되는 상황을 줄일 수 있습니다.

 

4. 함수의 개수 최적화하기

한 번에 너무 많은 함수를 사용하지 않도록, 10~20개 내외로 유지하는 것이 좋습니다. 그 이상이 되면 모델이 올바른 함수를 선택하는 데 어려움을 겪을 수 있습니다. 필요한 기능이 많다면, 함수들을 논리적으로 그룹화하거나 여러 도구(tool)로 나누어 사용해 보세요.

 

이번 시간에는 HyperCLOVA X의 신규 기능인 Function Calling에 대해 자세하게 알아봤습니다.

담을 내용과 꿀팁이 많아 조금 더 자세하게 포스팅하고 싶었는데 실습 영상을 참고해 주세요.

 

감사합니다.