[Ncloud] HyperCLOVA X 스킬트레이너 사용 가이드 활용 예제 실습하기

안녕하세요.

 

이번 시간에는 HyperCLOVA X를 이용해서 실제 서비스를 만들어보기 전에 공식 가이드에 있는 스킬트레이너 활용 예제를 간단하게 실습해 보겠습니다.

 

이 예제에서는 네이버의 지역 검색 API를 활용하여 다양한 업체를 추천하는 요청에 응답할 수 있는 대화형 AI 서비스를 생성하는 방법을 설명합니다.

 

스킬트레이너 활용 예제 실습 순서

사전 준비 (NAVER 개발자 도구 API)
Step 1. 스킬셋 생성
Step 2. 스킬 생성
Step 3. 데이터 수집
Step 4. 데이터 학습
Step 5. 테스트 앱 발급

 

1. 스킬트레이너 활용 예제 실습

사전 준비

이 예제에서 사용할 API는 네이버 개발자 센터에서 제공하는 검색 API를 활용합니다. 스킬 트레이너에서 검색 API를 호출하려면 네이버 개발자 센터에서 애플리케이션을 등록한 후 API 호출에 필요한 인증 정보를 획득해야 합니다. 이 단계에서 획득한 인증 정보는 데이터 수집 시 호출 옵션에 적용합니다.

 

네이버 API를 사용하기 위해 인증 정보를 획득하는 방법은 다음과 같습니다.

 

1. 네이버 개발자 센터에서 애플리케이션을 등록

https://developers.naver.com/

NAVER Developers

상단 Application - [애플리케이션 등록]을 선택합니다.

 

이번 실습에서 사용하는 API는 네이버 검색 API입니다. 다음과 같이 입력한 후 [등록하기]를 눌러서 API 사용 등록을 완료해 주세요.

 

2. API 호출 시 클라이언트 아이디와 클라이언트 시크릿 정보를 확인

해당 정보는 API 호출에 필요한 정보이기 때문에 확인합니다.

네이버 API 사용 시 네이버 개발자 센터의 이용 약관을 준수해야 합니다. 약관 준수 의무를 위반하여 발생한 모든 법적 책임은 사용자에게 있습니다.
네이버 API를 사용하는 방법에 대한 자세한 설명은 네이버 개발자 센터 API 공통 가이드를 참고해 주십시오.

 

Step 1. 스킬셋 생성

CLOVA Studio - My Product - [상품 이용 신청]을 눌러 서비스 이용을 신청합니다. 신청 및 약관에 동의해 주시면 됩니다.

 

상단에 스킬 트레이너를 누른 후 [스킬셋 생성]을 선택합니다.

 

스킬셋	지역 검색
스킬셋 설명	사용자가 입력한 검색어에 맞춰 적절한 지역 검색 결과를 제공합니다. 네이버 지역 서비스에 등록된 다양한 업체나 기관을 조회할 수 있고 검색 결과를 원하는 정렬 방식(블로그의 리뷰 개수순, 정확도순 등을 요청할 수 있습니다.
서비스 분야	플레이스
답변 형식	선택 안 함

다음과 같이 입력한 후 중복 확인 후 [생성]을 눌러 줍니다.

 

Step 2. 스킬 생성

스킬 이름

: 지역 검색

 

API Spec

{
  "info": {
    "title": "네이버 지역 검색",
    "version": "1.0.0",
    "description": "네이버 지역 서비스에 등록된 업체 및 기관을 검색하기 위한 스킬"
  },
  "paths": {
    "/v1/search/local.json": {
      "get": {
        "summary": "국내 지역 정보 검색 결과를 나열합니다.",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "items": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "link": {
                            "type": "string"
                          },
                          "mapx": {
                            "type": "string"
                          },
                          "mapy": {
                            "type": "string"
                          },
                          "title": {
                            "type": "string"
                          },
                          "address": {
                            "type": "string"
                          },
                          "category": {
                            "type": "string"
                          },
                          "telephone": {
                            "type": "string"
                          },
                          "description": {
                            "type": "string"
                          },
                          "roadAddress": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "start": {
                      "type": "integer"
                    },
                    "total": {
                      "type": "integer"
                    },
                    "display": {
                      "type": "integer"
                    },
                    "lastBuildDate": {
                      "type": "string"
                    }
                  }
                }
              }
            },
            "description": "- **title**: 업체명\\n- **address**: 지번 주소(e.g. 서울특별시 중구 을지로3가 229-1)\\n- **roadAddress**: 도로명 주소(e.g. 서울특별시 중구 을지로15길 6-5)\\n- **category**: 카테고리(e.g. 식당, 카페, 병원, 미용실, 기업, 공공 기관)\\n- **description**: 업체에 대한 설명(e.g. 연탄불 한우갈비 전문점, 강남역 근처 분위기 좋은 카페)\\n- **link**: 홈페이지 링크"
          }
        },
        "parameters": [
          {
            "in": "query",
            "name": "query",
            "schema": {
              "type": "string"
            },
            "required": true,
            "description": "**query**: 사용자가 찾고자 하는 상점의 설명 (e.g. 정자동 근처 맛집, 강남역 근처 분위기 좋은 카페)\\n"
          },
          {
            "in": "query",
            "name": "display",
            "schema": {
              "type": "integer",
              "default": "2"
            },
            "required": true,
            "description": "요청한 쿼리에 대한 검색 결과 수 입니다. 유일한 상점이나 업체일 경우에는 결과를 1개만 보여주세요."
          },
          {
            "in": "query",
            "name": "sort",
            "schema": {
              "type": "string"
            },
            "required": false,
            "description": "검색 결과 정렬 방법\\n- **random**: 정확도순으로 내림차순 정렬(기본값)\\n- **comment**:카페, 블로그의 리뷰 개수순으로 내림차순 정렬이 필요할 때 값을 사용하세요.(e.g. 리뷰 많은 순으로 정렬해주세요. 유명한 곳을 알려주세요. 인기 많은 곳을 알려주세요.)\\n"
          }
        ],
        "description": "지역의 업체나 기관을 검색합니다.",
        "operationId": "getLocalInfo"
      }
    }
  },
  "openapi": "3.0.2",
  "servers": [
    {
      "url": "https://openapi.naver.com"
    }
  ]
}

 

Manifest

Name for model	LocalSearch
Description for human	네이버 지역 서비스에 등록된 업체 및 기관을 검색한 결과를 반환합니다.
Description for model	네이버 지역 서비스에 등록된 업체 및 기관을 검색하기 위해서는 LocalSearch 스킬을 사용하세요. /v1/search/local.json은 업체나 기관의 이름, 주소(ex. 도로명 주소, 지번 주소)를 검색어로 입력할 때 동작합니다. 원하는 정렬 방식(ex.블로그의 리뷰 개수순, 정확도순 등)을 포함하여 검색 결과를 요청할 수 있습니다.

 

다음과 같이 스킬을 설정해 줍니다.

 

스킬 화면에서 다음과 같이 스킬 이름, API Spec, Manifest에 대한 유효성 검사를 마치면 [생성하기] 버튼이 활성화됩니다. API Spec을 입력한 후 [검증하기]가 비활성화 되어있다면 빈 공간을 클릭해보거나 JSON 문법을 고치면 활성화 됩니다.

API Spec 작성 방법과 Manifest 작성 방법에 대한 자세한 설명은 스킬(https://guide.ncloud-docs.com/docs/clovastudio-skill)을 참조해 주십시오.

 

답변 포맷도 따로 지정하지 않고 간단한 테스트이기 때문에 Description이 짧지만 설명을 자세하게 적어줄수록 모델이 더 정확하고 정교한 답변을 제공합니다.

 

Step 3. 데이터 학습

데이터 수집 단계에서는 사용자의 질문을 분석한 후 적절한 스킬을 호출합니다. 쿼리 분석 결과에서 분리된 쿼리의 수만큼 스킬이 호출되는데, 만약 사용자의 질문이 두 개의 쿼리로 분리되었다면 스킬도 각각 두 번 호출하게 됩니다. 이 예제에서는 '네이버 1784 주소와 근처 카페 추천해 주세요'로 데이터를 수집하므로 스킬이 두 번 호출됩니다.

 

User Query

User Query에 " 네이버 1784 주소와 근처 카페 추천해 주세요"를 입력해 봅니다.

다음과 같이 HyperCLOVA X 스킬트레이너가 API를 호출하여 어떻게 사고하고 답변을 도출해 내는지 과정을 볼 수 있고 직접 각 단계별로 내용을 교정해 줄 수도 있습니다. 원래는 Step 3까지 나와야 하는데 Step 2에서 문제가 발생한 이유는 NAVER 개발자 도구에서 API 키를 추가해주지 않아서 그렇습니다.

 

호출 옵션

{
  "baseOperation": {
    "header": {
      "X-Naver-Client-Id": "{naver-client-id}",
      "X-Naver-Client-Secret": "{secret}"
    }
  }
}

다음과 같이 호출 옵션에 NAVER 개발자 API 키를 입력한 후 적용합니다. 단, 호출 옵션은 휘발성 옵션이기 때문에 키 값이 지속되길 원한다면 [스킬]에서 파라미터 값으로 넣어주는 방법이 있습니다. 별첨에서 따로 설명드리겠습니다.

 

다시 User Query에 질의했을 때 다음과 같이 답변을 받을 수 있습니다.

 

현재 사용자 질의가 "네이버 1784 주소" 그리고 "근처 카페" 두 가지에 대한 질문을 했기 때문에 스킬 트레이너는 다음과 같이 두 질문에 대한 답변을 생성합니다.

 

답변 포맷

스킬트레이너의 좋은 점은 내가 원하는 형태로 답변 포맷을 간단히 설정해 줄 수 있다는 점입니다.

[답변 형식]을 누른 후 수정으로 되어 있는 하이퍼링크를 누르면 스킬셋으로 페이지가 넘어갑니다.

 

스킬셋 정보 페이지에서 [편집]을 누르면 답변 형식을 수정할 수 있습니다.

 

JSON 형식

{사용자 요청 내용}을 알려드리겠습니다.
1. {장소1 이름}
- 주소: {장소 1의 주소}
2. {장소2 이름}
- 주소: {장소 2의 주소}

더 필요하신 지역 정보가 있다면 말씀해주십시오.

다음과 같이 답변 포맷을 JSON 형식으로 바꿔준 후 다음과 같이 답변 포맷에 대한 설명을 덧붙입니다.

 

정상적으로 답변 포맷이 수정된 것을 확인할 수 있습니다. 답변 포맷을 수정하기 위해 페이지를 벗어나면 호출 옵션에 지정된 네이버 개발자 API 키가 휘발성으로 없어지기 때문에 새 탭에서 답변 포맷 수정을 진행하시는 것을 권장드립니다.

 

다음과 같이 수집이 완료된 건들에 대해서 [작업 완료]를 누르면 데이터 수집이 완료되어 데이터 학습 탭에서 사용할 수 있습니다.

 

Step 4. 데이터 학습

다음과 같이 데이터 학습에서 방금 수집한 내용으로 학습을 진행할 수 있습니다. 이 기능은 HyperCLOVA X의 튜닝 기능과 같습니다.

 

네이버 클라우드 공식 문서에서는 튜닝 성능을 올리기 위해 최소 20개의 데이터 수집이 완료된 상태에서 학습하는 것을 권장하고 있습니다.

 

수집이 완료되면 학습을 진행하는데 다소 시간이 걸리기 때문에 [학습]을 눌러 놓으시면 되겠습니다.

 

Step 5. 테스트 앱 생성

[버전 관리] 탭에서는 스킬에 대한 버전 관리가 가능하며 메모 입력을 통해 해당 버전이 무엇인지 직관적으로 알 수 있게 설계되어 있습니다. 우측에 [테스트 앱]을 누르면 코드에서 사용할 수 있는 curl이나 Python 코드를 자동으로 생성해 주기 때문에 굉장히 편리합니다.

 

다음과 같이 [지역 검색]으로 테스트 앱을 생성하면 만든 스킬트레이너를 호출할 수 있는 코드와 정보를 자동으로 생성해 줍니다.

테스트 앱을 생성하여 사용에 문제가 없는지 확인한 후 서비스 앱을 신청할 수 있습니다.
서비스 앱을 신청하려면 서비스 앱 신청 양식을 작성해 주십시오.
서비스 앱 신청에 관한 자세한 내용은 서비스 앱 신청을 참조해 주십시오.
앱 신청 현황을 확인하려면 앱 신청 현황 확인을 참조해 주십시오.

해당 테스트 앱에는 호출 옵션에 작성한 baseOperation 정보가 추가되어 있지 않기 때문에 코드에서 추가하거나 아래 방법으로 스킬 수정이 필요합니다.

 

별첨. API 키를 스킬 파라미터에 정의하기

{
  "name": "X-Naver-Client-Id",
  "in": "header",
  "description": "발급받은 client id 값을 입력합니다.",
  "required": true,
  "schema": {
    "type": "string"
  }
},
{
  "name": "X-Naver-Client-Secret",
  "in": "header",
  "description": "발급받은 client secret key 값을 입력합니다.",
  "required": true,
  "schema": {
    "type": "string"
  }
}

다음과 같이 파라미터에 해당 Key 정보를 포함해서 스킬을 저장하고 직접 하드코딩 혹은 네이버 클라우드 플랫폼 Secret Manager를 통해 키를 안전하게 관리할 수 있습니다.

 

이번 시간에는 HyperCLOVA X를 이용해서 실제 서비스를 만들어보기 전에 공식 가이드에 있는 스킬트레이너 활용 예제를 간단하게 실습해 봤습니다.

 

다음 시간에는 스킬트레이너를 활용해서 서비스를 만들어보는 실습을 진행하겠습니다.

 

감사합니다.