[Ncloud] HyperCLOVA X 스킬트레이너에 대해 알아보고 사용 가이드 정리

Cloud/Naver Cloud

[Ncloud] HyperCLOVA X 스킬트레이너에 대해 알아보고 사용 가이드 정리

__Evening 2024. 8. 8. 09:48

안녕하세요.

이번시간에는 네이버 클라우드 플랫폼 서비스인 HyperClova X의 스킬트레이너의 개념에 대해 알아보고 사용 가이드를 정리하겠습니다.

1. HyperCLOVA X란?

네이버의 초대규모 AI로 자체 데이터와 결합하여 사용자 니즈에 맞는 응답을 즉각 제공할 수 있습니다. HyperCLOVA X는 한국어 특화 언어 모델로 기업 전용 AI를 만들 수 있도록 돕는 하이퍼스케일 AI 개발 도구입니다.

국내에 대한 정보를 기반으로 한국어를 메인으로 사용하는 서비스는 현시점에서 HyperCLOVA X 만큼 높은 신뢰성과 정확성을 갖춘 모델을 찾기 힘들 것으로 생각됩니다.

2. HyperCLOVA X 스킬 트레이너

스킬 트레이너는 특화된 지식을 모델에 학습시키는 기능입니다. 특정 서비스에 필요한 여러 스킬을 구성하여 이를 모델에 학습시켜 모델의 성능을 높일 수 있습니다. 스킬 트레이너를 활용하면 사용자에게 최신 정보나 신뢰할 수 있는 정보를 제공할 수 있고, 많은 양의 데이터를 매번 학습하기 어려운 한계를 보완하여 효율적으로 모델의 지식을 업데이트할 수 있습니다.

1. 스킬셋

스킬셋은 특정 분야에 필요한 여러 스킬의 묶음입니다. 다음과 같이 여행이라는 큰 틀의 개념을 스킬셋, 세부 항목들을 스킬이라고 합니다. 하나의 스킬셋에 최대 10개의 스킬을 추가할 수 있습니다. 스킬셋에는 답변 형식 말투, 포맷을 지정할 수 있습니다.

2. 스킬

스킬은 사용자의 요구 사항에 정확하고 적절한 응답을 주기 위해 사용하는 도구입니다. 모델은 사용자의 질문과 스킬에 작성된 API를 분석하여 가장 적절한 답을 줄 수 있는 스킬을 선택한 후, 정확한 정보를 호출하여 사용자에게 제공할 수 있습니다.

(1) 스킬 필수 항목

Version

Info

Servers

Paths

Parameter Object

Operation Object

Response Object

API Spec에는 다음과 같은 필수 항목들이 있습니다. 다음 항목들이 정상적으로 입력되어야 API Spec 체크가 가능하니 아래 설명에서 확인해 보시면 됩니다.

(2) API Spec 작성

모델이 이해할 수 있는 API 스펙을 작성합니다. 스킬 트레이너는 현재 JSON 형식만 지원하며 명세는 OpenAPI Specification v3.0.0을 참조하면 됩니다.

Version (Required)

사용할 OpenAPI 버전 정보입니다. 3.0 버전만 지원하며, 다른 버전을 사용할 경우 오류가 발생할 수 있습니다.

작성 예시

{
    "openapi": "3.0.0"
}

Info (Required)

제공되는 API에 관한 정보입니다.

필드	설명	필수 여부
version	API 버전 정보	Y
title	API 이름	Y

작성 예시

info:
  version: API 버전
  title: API 제목
  description: API 설명
  contact: API 제공자
  license: API 라이선스 정보

Servers (Required)

API가 제공되는 대상 호스트 정보로 Path들의 baseURL입니다.

필드	설명	필수 여부
url	서버 URL	Y

작성 예시

servers:
  - url: https://sample.naver.com/v1

Paths (Required)

제공되는 API의 각 Path 정보입니다. 각 Path의 하위에는 Operation Object와 Parameter Object가 존재합니다.

필드	설명	필수 여부
Summary \| Description	사용할 파라미터와 해당 Path를 통해 얻을 수 있는 정보를 구체적으로 작성 <예시> 여행지의 국내외 여부, 지역명, 방문하는 달, 여행자 수, 예상 경비를 통해서 여행 지역 및 도시 검색	Y

- requests get, requests post 메소드만 지원합니다.
- POST 메소드인 경우, 'nested datatype'은 아직 정식 지원하지 않으므로 파라미터를 분리해서 작성해 주십시오.
- URL은 반드시 argument 방식으로 동작하는 것으로 가정하여 작성해 주십시오. 현재의 모델은 argument 방식만 지원합니다. (파라미터=파라미터의 값)
<예시 1> http://test.com/data?birthdata=20190302&address=서초구 (O)
<예시 2 > http://test.com/data?20190302/서초구 (X)

작성 예시

paths:
  /test:
    get:
      description: get test data (해당 path가 어떤 상황에서 쓰이는지 구체적으로 작성)
      operationId: getTest
      responses:
        '200':
          description: test response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Test'

Parameter Object (Required)

작업에 적용할 수 있는 매개 변수 목록입니다.

필드	설명	필수 여부
name	매개 변수의 이름, 대소문자 구별	Y
in	매개 변수의 위치 - 사용 가능한 값: query	Y
description	해당 파라미터에 대한 구체적인 설명	N
required	매개 변수의 필수 여부 결정 - 사용 가능한 값: true, false	N
schema: type	매개 변수 데이터 유형 설정 - 사용 가능한 값: string, integer, number, boolean, array	N
schema: format	데이터 타입별 포맷 설정 - 데이터 타입별 설정 가능한 포맷은 OpenAPI Specification v3.0.0 참조	N

description에는 해당 파라미터가 어떤 의미를 갖고 있는지, 어떤 상황에서 사용되는 것인지, URL 생성 시 어떤 형식으로 들어가야 하는지 등을 구체적으로 작성합니다. 만약 파라미터가 가져야 하는 값이 한정되어 있다면 예시 값을 구체적으로 작성합니다.
male 또는 female 둘 중 하나의 값만 가져야 한다면 description에 구체적으로 작성합니다.
<예시> male 또는 female 중에 하나
강남으로 검색해도 강남구로 url에 들어가야 한다면 description에 구체적으로 작성합니다.
<예시> 강남구, 서초구
해당 파라미터가 한정된 장소를 검색하는 값이라면, 단순 검색어가 아닌 '레스토랑 또는 카페와 같은 특정 장소를 검색할 때 사용된다'라는 의미를 모델이 이해할 수 있도록 작성합니다.
<예시>

{
   "parameters": [
      {
         "name": "place_category",
         "in":"query",
         "description": "장소의 대분류. restaurant, cafe, attraction, accommodation 중에 하나.",
         "required": false,
         "schema": {
            "type": "string"
         }
      }
   ]
}

작성 예시

parameters:
- name: birthdate
  in: query
  description: 생일을 의미합니다. 입력 형식은 yyyy-mm-dd입니다.
  required: true
  schema:
    type: array
    style: simple
    items:
      type: string
      format: date

Operation Object (Required)

API 호출 작업에 대한 정보입니다.

필드	설명	필수 여부
description	작업 동작에 대한 자세한 설명	N
operationId	작업 식별 시 사용되는 고유 문자열. Open API를 이용하는 다른 툴이나 라이브러리에서 operationId를 사용하여 식별하는 것도 가능	Y
responses	작업을 실행하여 반환되는 것이 가능한 응답 목록. 응답은 Response Object 형태로 제공	Y

작성 예시

get:
  description: get test data
  operationId: getTest
  responses:
    '200':
      description: teset response
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/Test'
    default:
      description: unexpected error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

Response Object (Required)

작업 응답에 대한 설명입니다.

필드	설명	필수 여부
description	응답에 대한 간단한 설명	Y

200 응답은 필수 값이며, HTTP 상태 코드에 따라 기타 응답을 추가할 수 있습니다.
잘못된 파라미터에 대한 요청 시 422, 400 오류를 반환합니다.
정의된 오류 코드가 없을 경우, 422 오류를 임의로 만들어서 반환합니다.

작성 예시

responses:
  '200':
	description: test response
	content:
	  application/json:
		schema:
		  items:
			$ref: '#/components/schemas/Test'
  default:
	description: unexpected error
	content:
	  application/json:
		schema:
		  $ref: '#/components/schemas/Error'

Components

OAS의 다양한 부분에서 재사용 가능한 객체입니다.

필드 이름	타입	설명
schemas	Map[string, Schema Object \| Reference Object]	재사용 가능한 Schema Object의 객체
responses	Map[string, Response Object \| Reference Object]	재사용 가능한 Response Object의 객체
parameters	Map[string, Parameter Object \| Reference Object]	재사용 가능한 Parameter Object의 객체
examples	Map[string, Example Object \| Reference Object]	재사용 가능한 Example Object의 객체

작성 예시

components:
  schemas:
    Test:
      allOf:
        - $ref: '#/components/schemas/NewTest'
        - type: object
          required:
            - id
          properties:
            id:
              type: integer
              format: int64
              example: 100
    NewTest:
      type: object
      required:
        - name
      properties:
        name:
          type: string
        tag:
          type: string
          example: "test tag"

Manifest

Manifest는 해당 스킬을 통해 호출할 수 있는 API의 이름, 목적, 사용 방법 등을 입력하는 영역입니다. Manifest의 입력 영역인 Name for model, Description for human, Description for model 각 필드에 대해 설명합니다.

Manifest 작성은 HyperCLOVA X의 답변 품질에 영향을 주기 때문에 정확하고 자세하게 작성하는 것이 중요합니다.

Name for model

모델 이름을 작성합니다. 다른 API와 이름이 중복되지 않아야 하며 API의 성격을 내포하여 간결하게 작성해야 합니다.
영문자, 숫자를 허용하며 대문자로 시작하는 문자열을 20자 이내로 입력해 주십시오. 한글, 특수 문자, 공백을 허용하지 않습니다.
두 개 이상의 단어를 조합할 경우, 각 단어의 첫 글자은 대문자로 작성해 주십시오. 예를 들어, 'animal'과 'hospital'이라는 두 개의 단어를 조합하여 API 이름을 만들 경우 'AnimalHospital'라고 작성합니다.
스킬 이름에 'API'라는 단어는 사용하지 마십시오.

Description for human

API의 목적과 용도를 작성합니다. 모든 API의 역할이 명확하게 작성되어야 합니다. 사용자의 질문을 바탕으로 모델이 여러 API 중에서 필요한 API를 선택하는 기준이 됩니다.
예를 들어 동물병원 검색, 애견카페 검색, 애견용품 검색 API가 존재할 때 사용자의 질문이 '동물병원 위치 알려줘'일 경우, 모델은 각 API의 description_for_human을 읽고 동물병원 검색 API를 선택합니다.

사용자의 질문에 따라 모델이 여러 API 중에서 필요한 API를 선택하는 기준

작성 예시

울산광역시에 있는 동물 병원을 찾을 때 사용합니다. 병원 이름으로 조회하여 동물 병원의 주소와 연락처 정보를 제공합니다.

Description for model

API의 주요 사용 방법을 5,000자 이내로 작성합니다. 모델이 사용자의 질문에 답변할 때 사용할 API를 결정할 때 사용자의 질문과 ‘decription_for_model’을 모두 참고하여 여러 개의 API 중 적절한 API를 선택합니다. 또한 API 응답으로 받을 수 있는 정보에 대해서도 작성해야 합니다. 각 API를 호출했을 때 어떤 정보를 받을 수 있는지에 대해 범위를 상세하게 작성해야 모델이 API를 적절하게 선택하여 사용할 수 있습니다. 만약 Path가 여러 개인 경우에는 Path별 역할에 대해 자세히 작성해야 합니다. Path별로 검색되어야 할 키워드를 작성해야 모델이 해당 API를 적절하게 사용할 수 있습니다.

API의 주요 사용 방법과 설명이 작성되며 모델이 사용자의 질문에 답변할 때 사용 방법과 설명을 참조할 때 사용

작성 예시

전통 시장의 정보와 주차장 시설 정보를 조회하는 API입니다. 이 API를 호출하면 응답으로 장소명, 주소, 운영 시간 정보가 제공됩니다. 서울시 전통 시장의 정보를 알고 싶을 때에는 /traditional_market을 사용하세요. /traditional_market은 시장 이름, 영업일, 휴무일, 주소 키워드, 영업 시작 시간, 영업 종료 시간을 검색어로 입력할 때 동작합니다. 주차장 시설 정보를 얻고 싶을 때는 /parking_lot을 사용하세요. /parking_lot은 지역구분_구, 지역구분_동, 주차장 명, 주차장 종류, 운영시간, 최소 가격을 검색어로 입력할 때 동작합니다. 전송할 쿼리에는 관사, 전치사, 결정자와 같은 중지어가 포함되어서는 안 됩니다. 링크는 항상 반환되며 사용자에게 표시되어야 합니다.
울산광역시 동물 병원 현황 조회 API입니다. 이 API를 호출하면 응답으로 동물 병원 이름, 위치, 전화번호, 운영 시간 정보가 제공됩니다. 울산시에 있는 동물 병원을 검색할 때는 /getPetHospitalList를 사용하세요. /getPetHospitalList는 판매점 이름을 검색어로 입력할 때 동작합니다. 전송할 쿼리에는 관사, 전치사, 결정자와 같은 중지어가 포함되어서는 안 됩니다. 링크는 항상 반환되며 사용자에게 표시되어야 합니다.

스킬트레이너를 이용해서 서비스를 만들어봤을 때 개인적으로 Description이었던 것 같습니다.

3. 데이터 수집

데이터 수집은 사용자의 질문에 적절한 답을 주기 위해 모델이 생각하고 판단하는 과정입니다. 데이터 수집 및 데이터 검토를 통해 모델의 사고 과정을 수정할 수 있습니다.

Engine / Version	사용할 언어 모델 또는 버전 선택
Skill	스킬셋 및 에 포함된 스킬 목록. 작업 상태가 '작업 완료'인 스킬만 활용 가능
Setting > 호출 옵션	유저 쿼리로 API 호출 시 고정할 값 입력. 호출 옵션을 작성하는 방법은 호출 옵션 작성 참조

스킬 호출

스킬을 호출하고 모델의 사고를 검토하는 단계입니다. 쿼리 분석 단계에서 분리된 쿼리 개수만큼 스킬 호출이 수행됩니다.

스킬 호출은 3단계로 구성됩니다.

Step 1: 호출할 스킬에 해당하는 API를 조회하는 단계
- 호출 방안: API를 찾기 위한 모델의 사고 과정
- 호출 스킬: 스킬의 모델 이름
- API 조회 내용: 스킬의 API Spec 및 Description for model 정보
Step 2: API 조회 결과를 확인하는 단계
- API 조회 결과: API를 호출하기 위한 모델의 사고 과정. API 호출에 필요한 요청 변수(파라미터) 추론
- 액션: API 메소드. requests_get과 requests_post만 지원
- 액션 입력: 모델이 추론한 URL 및 파라미터. 액션에 따라 입력 필드가 달라짐
  - requests_get일 때 액션 입력 필드: API URL/파라미터
  - requests_post일 때 액션 입력 필드: API URL/파라미터(Key, Value)
    - [필드 추가] 버튼 클릭 시 빈 필드 추가 생성
    - 아이콘 클릭 시 필드 삭제
- 호출 결과: API 호출 결과
Step 3: 호출 결과를 토대로 내용을 정리하는 단계
- 생각: 호출 내용을 정리하기 위한 모델의 사고 과정
- 결과 정리: 모델의 생성 결과

데이터 수집 단계에서는 스킬을 호출하고 모델이 어떻게 답변을 도출하는지 단계별로 살펴보고 모델의 사고를 내가 직접 교정해 주는 단계라고 보실 수 있습니다.

호출 옵션

호출 옵션을 작성하면 API spec의 operation ID에 대응하여 헤더 및 본문 매개 변수의 특정값을 고정할 수 있습니다.

데이터 수집 화면에서 벗어난 후, 데이터 수집 메뉴로 다시 진입한 경우 호출 옵션이 초기화됩니다.
호출 옵션을 적용하여 데이터를 수집한 후, [초기화] 버튼을 클릭하더라도 호출 옵션은 유지됩니다.
[불러오기] 버튼을 클릭하여 작업하던 내역을 불러올 경우, 해당 작업에 적용된 호출 옵션도 불러옵니다.

상세 호출 옵션

호출 옵션에 작성 가능한 필드에 관한 정보입니다.
호출 옵션은 operations 필드, baseOperation 필드, 유저 쿼리 순으로 적용됩니다.

4. 데이터 학습

데이터 학습은 서비스에 특화된 지식을 모델에 학습시키는 것을 의미합니다. 모델이 더 정확하고 정교한 답변을 생성할 수 있도록 스킬셋을 학습시키고 학습한 내역을 관리하는 방법을 설명합니다.

모델이 더 정확한 답변을 생성할 수 있도록 수집한 데이터를 모델에 학습시킵니다. 스킬셋을 학습시키려면 '완료' 상태인 스킬과 수집한 데이터가 1개 이상 존재해야 합니다. 선택 가능한 스킬셋이 없는 경우에는 스킬의 작업 상태를 확인해 주십시오.

학습 중일 경우에는 해당 스킬셋 내에 신규 스킬을 생성하거나 기존 스킬을 수정할 수 없으며 임시 저장만 가능합니다.

스킬 트레이너의 데이터 학습 단계는 HyperCLOVA X의 튜닝 단계와 유사합니다.

https://guide.ncloud-docs.com/docs/clovastudio-skill

자세한 내용은 네이버 클라우드 스킬트레이너 공식 가이드에서 확인해 볼 수 있습니다.

이번시간에는 네이버 클라우드 플랫폼 서비스인 HyperClova X의 스킬트레이너의 개념에 대해 알아보고 사용 가이드를 알아봤습니다.

사실 Ncloud 사용 가이드에 정말 자세하게 나와 있기 때문에 활용 예제와 활용한 서비스를 다음 포스팅에서 소개하겠습니다.

감사합니다.

저작자표시 비영리 변경금지