스킬

Classic/VPC 환경에서 이용 가능합니다.

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

스킬 트레이너에서 생성한 스킬은 다음과 같은 작업을 수행할 수 있습니다.

실시간 정보 검색: 동물 병원 조회, 채용 공고 조회, 실시간 인기 상품, 실시간 차량 정보
지식 기반 정보 검색: 여행지 추천, 상품 추천, 여행 정보

스킬 생성

스킬을 생성하는 방법은 다음과 같습니다.

네이버 클라우드 플랫폼 콘솔에서 Services > AI Services > CLOVA Studio 메뉴를 차례대로 클릭해 주십시오.
My Product 메뉴에서 [CLOVA Studio 바로가기] 버튼을 클릭해 주십시오.
CLOVA Studio에서 스킬 트레이너 메뉴를 클릭해 주십시오.
스킬셋을 클릭해 주십시오.
화면 오른쪽 상단의 [스킬 생성] 버튼을 클릭해 주십시오.
스킬 정보 화면이 나타나면 스킬 이름을 입력한 후 [중복 확인] 버튼을 클릭해 주십시오.
- 스킬 이름은 영문자, 한글, 숫자, 공백을 허용하며 20자 이내로 입력해 주십시오.
- 해당 스킬셋 내에서 스킬 이름이 중복되지 않도록 입력해 주십시오.
답변 형식에 스킬을 통해 생성될 답변 형식을 입력해 주십시오.
API Spec 영역에 API 스펙을 JSON 타입의 OAS 3.0 버전으로 작성해 주십시오.
- API Spec을 작성하는 방법은 API Spec 작성을 참조해 주십시오.
API 스펙 작성이 완료되면 [검증하기] 버튼을 클릭해 주십시오.
- 검증 성공 시 'API Spec 검증이 완료되었습니다' 문구가 표시되고 [검증하기] 버튼이 비활성화됩니다.
- 검증 실패 시 오류 메시지가 나타납니다. API 스펙을 다시 수정해 주십시오.
Manifest 영역에 정보를 입력해 주십시오.
- Manifest를 작성하는 방법은 Manifest 작성을 참조해 주십시오.
Name for model의 [중복 확인] 버튼을 클릭해 주십시오.
필수 정보를 모두 입력한 후, [생성하기] 버튼을 클릭해 주십시오.
- 현재까지 작업한 내용을 저장하려면 [임시 저장] 버튼을 클릭해 주십시오.
- 모든 영역이 입력되었더라도 [임시 저장] 버튼을 클릭하는 경우, 작업 상태가 '작업 중'으로 저장됩니다.
스킬 생성 완료 창이 나타나면 [확인] 버튼을 클릭해 주십시오.

참고

하나의 스킬셋에 최대 10개의 스킬을 추가할 수 있습니다.

API Spec 작성

API Spec 항목에는 모델이 이해할 수 있는 API 스펙을 작성합니다. 스킬 트레이너에서는 JSON 형식만 지원합니다. 자세한 명세는 OpenAPI Specification v3.0.0을 참조해 주십시오.

Version

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

작성 예시는 다음과 같습니다.

{
    "openapi": "3.0.0"
}

Info

제공되는 API에 관한 정보입니다. 필수 입력 값입니다.

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

작성 예시는 다음과 같습니다.

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

Servers

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

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

작성 예시는 다음과 같습니다.

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

Paths

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

필드	설명	필수 여부
Summary I 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

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

필드	설명	필수 여부
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

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

작업 응답에 대한 설명입니다. 필수 입력 값입니다.

필드	설명	필수 여부
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 I Reference Object]	재사용 가능한 Schema Object의 객체
responses	Map[string, Response Object I Reference Object]	재사용 가능한 Response Object의 객체
parameters	Map[string, Parameter Object I Reference Object]	재사용 가능한 Parameter Object의 객체
examples	Map[string, Example Object I 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"

API Spec 확장 기능

API Spec에서 x-exclude-cot 객체를 사용하면 API 응답에서 해당 파라미터를 제외할 수 있습니다. Response Object에서 사용되고, Content-Type이 application/json 타입인 경우에만 적용 가능합니다. 응답에 사용되는 모든 매개 변수를 정확하게 작성해야 정상적으로 적용됩니다.

x-exclude-cot 객체는 다음과 같은 경우에 활용할 수 있습니다.

API 응답이 길어서 토큰 수 초과 에러가 발생하는 경우
x-exclude-cot가 적용된 파라미터의 경우 데이터 수집 과정 중 'API 호출 결과'에서 제외됩니다. 따라서 실제 사용되지 않는 파라미터에 x-exclude-cot를 적용하면 데이터 수집 시 API 응답을 줄일 수 있습니다.
학습 비용을 절약하고자 하는 경우
불필요한 파라미터에 x-exclude-cot를 적용하면, 데이터 수집 과정에서 토큰 수를 절약할 수 있습니다. 결과적으로 학습에 사용되는 토큰 수를 절약할 수 있습니다.

API 응답에서 address라는 매개 변수를 제외하도록 설계한 예시는 다음과 같습니다.

"responses": {
    "200": {
        "description": "test response",
        "content": {
            "application/json": {
                "schema": {
                    "properties": {
                        "name": {
                            "type": "string"
                        },
                        "address": {
                            "type": "object",
                            "properties": {
                                "city" : {
                                    "type": "string"
                                },
                                "state": {
                                    "type": "string"
                                }
                            },
                            "x-exclude-cot": true
                        },
                        "contact": {
                            "type": "string"
                        }
                    }
                }
            }
        }
    }
}

참고

데이터 수집이 아닌, 테스트 앱이나 서비스 앱을 발급하여 호출하는 경우에는 x-exclude-cot가 적용된 필드도 API 응답에 모두 노출됩니다. 이 경우 API 응답에 대한 토큰 수 초과 에러는 발생되지 않습니다.

API Spec 작성 예시

API Spec 작성 예시를 설명합니다.

Requests_get을 사용하는 예시

Requests_get을 사용하는 예시는 다음과 같습니다.

{
    "openapi": "3.0.0",
    "info": {
        "version": "v0",
        "title": "국내 항공기 운행 스케줄 검색"
    },
    "servers": [
        {
            "url": "http://test.airport.co.kr/service/rest/TestFlightScheduleList"
        }
    ],
    "tags": [
        {
            "name": "open-ai-product-endpoint",
            "description": "Open AI Product Endpoint. Query for products."
        }
    ],
    "paths": {
        "/getDflightScheduleList": {
            "get": {
                "tags": [
                    "open-ai-product-endpoint"
                ],
                "summary": "국내 항공기 운행 스케줄을 검색합니다.",
                "operationId": "productsUsingGET",
        "parameters" : [  {
          "name" : "serviceKey",
          "in" : "query",
          "description" : "serviceKey는 반드시 2FMD를 쓰세요",
          "required" : true,
          "schema" : {
            "type" : "string",
            "default" : "1"
          }},
          {
          "name" : "schDate",
          "in" : "query",
          "description" : "검색 일자. 반드시 8자리의 숫자로 입력하세요. 예를 들어 2022년 4월 1일이면 20220401",
          "required" : false,
          "schema" : {
            "type" : "string"
          }
        }, {
          "name" : "schDeptCityCode",
          "in" : "query",
          "description" : "도착 도시 코드. 예를 들어 서울을 나타내는 GMP를, 도착도시코드는 제주도를 나타내는 CJU, 부산은 PSU",
          "required" : false,
          "schema" : {
            "type" : "string",
            "default" : "10"
          }
        }, {
          "name" : "schArrvCityCode",
          "in" : "query",
          "description" : "출발 도시 코드. 예를 들어 서울을 나타내는 GMP를, 도착도시코드는 제주도를 나타내는 CJU, 부산은 PSU",
          "required" : false,
          "schema" : {
            "type" : "string",
            "default" : "10"
          }
        }
                ],
                "responses": {
                    "200": {
                        "description": "Products found",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Rss"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "one or more services are unavailable"
                    }
                },
                "deprecated": false
            }
        }
    },
    "components": {
        "schemas": {
            "Rss": {
                "type": "object",
                "properties": {
                    "airlineKorean": {
                        "type": "string",
                        "description": "항공사(국문)"
                    },
                    "arrivalcity": {
                      "type": "string",
                      "description": "도착 공항"
                    },
                    "domesticArrivalTime": {
                      "type": "integer",
                      "description": "도착 시간"
                    },
                    "domesticEddate": {
                      "type": "string",
                      "format": "date-time",
                      "description": ""
                    },
                    "domesticFri": {
                      "type": "string",
                      "description": "금요일"
                    },
                    "domesticMon": {
                      "type": "string",
                      "description": "월요일"
                    },
                    "domesticNum": {
                      "type": "string",
                      "description": "항공편명"
                    },
                    "domesticSat": {
                      "type": "string",
                      "description": "토요일"
                    },
                    "domesticStartTime": {
                      "type": "integer",
                      "description": "출발 시간"
                    },
                    "domesticStdate": {
                      "type": "string",
                      "format": "date-time",
                      "description": ""
                    },
                    "domesticSun": {
                      "type": "string",
                      "description": "일요일"
                    },
                    "domesticThu": {
                      "type": "string",
                      "description": "목요일"
                    },
                    "domesticTue": {
                      "type": "string",
                      "description": "화요일"
                    },
                    "domesticWed": {
                      "type": "string",
                      "description": "수요일"
                    },
                    "startcity": {
                      "type": "string",
                      "description": "출발 공항"
                    },
                    "numOfRows": {
                      "type": "integer",
                      "description": "열 숫자"
                    },
                    "pageNo": {
                      "type": "integer",
                      "description": "페이지 번호"
                    },
                    "totalCount": {
                      "type": "integer",
                      "description": "데이터 총계"
                    }
                }
            }
        }
    }
}

Requests_post를 사용하는 예시

Requests_post를 사용하는 예시는 다음과 같습니다.

{
  "openapi": "3.0.0",
  "info": {
    "title": "Free API Documentation",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://test.bakery.com"
    }
  ],
  "paths": {
    "/bakery_products": {
      "post": {
        "summary": "베이커리 제품 정보를 등록하는 API입니다.",
        "description": "베이커리 제품 정보를 등록하는 API입니다.",
        "operationId": "filterBakeryProducts",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "제품 영문명"
                  },
                  "max_price": {
                    "type": "integer",
                    "description": "최대 가격 (원)"
                  },
                  "ingredients": {
                    "type": "string",
                    "description": "재료의 영문명"
                  },
                  "expiration_date": {
                    "type": "string",
                    "description": "유통 기한. 예시) 20220701"
                  },
                  "allergens": {
                    "type": "string",
                    "description": "알레르기 성분의 영문명"
                  }
                },
                "required": [
                  "max_price"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "성공적인 응답",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "integer",
                        "description": "제품 ID"
                      },
                      "name": {
                        "type": "string",
                        "description": "제품 이름"
                      },
                      "price": {
                        "type": "integer",
                        "description": "가격 (원)"
                      },
                      "ingredients": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        },
                        "description": "재료 목록"
                      },
                      "expiration_date": {
                        "type": "string",
                        "format": "date",
                        "description": "유통 기한"
                      },
                      "calories": {
                        "type": "integer",
                        "description": "칼로리"
                      },
                      "allergens": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        },
                        "description": "알레르기 성분 목록"
                      },
                      "additional_options": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        },
                        "description": "추가 옵션 목록"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

Manifest 작성

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

Name for model
- 모델 이름을 작성합니다. 다른 API와 이름이 중복되지 않아야 하며 API의 성격을 내포하여 간결하게 작성해야 합니다.
- 영문자, 숫자를 허용하며 대문자로 시작하는 문자열을 20자 이내로 입력해 주십시오. 한글, 특수 문자, 공백을 허용하지 않습니다.
- 두 개 이상의 단어를 조합할 경우, 각 단어의 첫 글자은 대문자로 작성해 주십시오. 예를 들어, 'animal'과 'hospital'이라는 두 개의 단어를 조합하여 API 이름을 만들 경우 'AnimalHospital'라고 작성합니다.
- 스킬 이름에 'API'라는 단어는 사용하지 마십시오.
Description for human
- API의 목적과 용도를 작성합니다. 모든 API의 역할이 명확하게 작성되어야 합니다. 사용자의 질문을 바탕으로 모델이 여러 API 중에서 필요한 API를 선택하는 기준이 됩니다.
- 예를 들어 동물병원 검색, 애견카페 검색, 애견용품 검색 API가 존재할 때 사용자의 질문이 '동물병원 위치 알려줘'일 경우, 모델은 각 API의 description_for_human을 읽고 동물병원 검색 API를 선택합니다.
- 작성 예시는 다음과 같습니다.
```
울산광역시에 있는 동물 병원을 찾을 때 사용합니다. 병원 이름으로 조회하여 동물 병원의 주소와 연락처 정보를 제공합니다.
```
  Plain text

Description for model

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

작성 예시는 다음과 같습니다.

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

울산광역시 동물 병원 현황 조회 API입니다. 이 API를 호출하면 응답으로 동물 병원 이름, 위치, 전화번호, 운영 시간 정보가 제공됩니다. 울산시에 있는 동물 병원을 검색할 때는 /getPetHospitalList를 사용하세요. /getPetHospitalList는 판매점 이름을 검색어로 입력할 때 동작합니다. 전송할 쿼리에는 관사, 전치사, 결정자와 같은 중지어가 포함되어서는 안 됩니다. 링크는 항상 반환되며 사용자에게 표시되어야 합니다.

스킬 편집

스킬 정보를 편집하는 방법은 다음과 같습니다.

네이버 클라우드 플랫폼 콘솔에서 Services > AI Services > CLOVA Studio 메뉴를 차례대로 클릭해 주십시오.
My Product 메뉴에서 [CLOVA Studio 바로가기] 버튼을 클릭해 주십시오.
CLOVA Studio에서 스킬 트레이너 메뉴를 클릭해 주십시오.
스킬셋을 클릭해 주십시오.
화면 왼쪽의 스킬 메뉴를 클릭한 후 편집할 스킬명을 클릭해 주십시오.
스킬 정보를 수정한 후, [저장하기] 버튼을 클릭해 주십시오.
- 수정한 내용이 있거나 필수 항목이 모두 작성되어야 [저장하기] 버튼이 활성화됩니다.
- 스킬 이름과 Name for model을 수정한 경우, [중복 확인] 버튼을 클릭해 주십시오.
- API Spec을 수정한 경우, [검증하기] 버튼을 클릭해 주십시오.
편집할 내용이 없으면 [취소] 버튼을 클릭해 주십시오.

스킬 삭제

스킬을 삭제하는 방법은 다음과 같습니다.

네이버 클라우드 플랫폼 콘솔에서 Services > AI Services > CLOVA Studio 메뉴를 차례대로 클릭해 주십시오.
My Product 메뉴에서 [CLOVA Studio 바로가기] 버튼을 클릭해 주십시오.
CLOVA Studio에서 스킬 트레이너 메뉴를 클릭해 주십시오.
스킬셋을 클릭해 주십시오.
화면 왼쪽의 스킬 메뉴를 클릭해 주십시오.
삭제할 스킬명에 마우스 포인터를 올려 놓은 후 아이콘을 클릭해 주십시오.
삭제 팝업 창이 나타나면 [삭제] 버튼을 클릭해 주십시오.