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 | 매개 변수의 위치.
|
Y |
| description | 해당 파라미터에 대한 구체적인 설명 | N |
| required | 매개 변수의 필수 여부 결정
|
N |
| schema: type | 매개변수 데이터 유형 설정
|
N |
| schema:format | 데이터 타입별 포맷 설정
|
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 각 필드에 대해 설명합니다.
-
- 모델 이름을 작성합니다. 다른 API와 이름이 중복되지 않아야 하며 API의 성격을 내포하여 간결하게 작성해야 합니다.
- 영문자, 숫자를 허용하며 대문자로 시작하는 문자열을 20자 이내로 입력해 주십시오. 한글, 특수 문자, 공백을 허용하지 않습니다.
- 두 개 이상의 단어를 조합할 경우, 각 단어의 첫 글자은 대문자로 작성해 주십시오. 예를 들어, 'animal'과 'hospital'이라는 두 개의 단어를 조합하여 API 이름을 만들 경우 'AnimalHospital'라고 작성합니다.
- 스킬 이름에 'API'라는 단어는 사용하지 마십시오.
-
- API의 목적과 용도를 작성합니다. 모든 API의 역할이 명확하게 작성되어야 합니다. 사용자의 질문을 바탕으로 모델이 여러 API 중에서 필요한 API를 선택하는 기준이 됩니다.
- 예를 들어 동물병원 검색, 애견카페 검색, 애견용품 검색 API가 존재할 때 사용자의 질문이 '동물병원 위치 알려줘'일 경우, 모델은 각 API의 description_for_human을 읽고 동물병원 검색 API를 선택합니다.
- 작성 예시는 다음과 같습니다.
울산광역시에 있는 동물 병원을 찾을 때 사용합니다. 병원 이름으로 조회하여 동물 병원의 주소와 연락처 정보를 제공합니다.
-
- 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에서 스킬 트레이너 메뉴를 클릭해 주십시오.
- 스킬셋을 클릭해 주십시오.
- 스킬 탭을 클릭해 주십시오.
- 삭제할 스킬의 ⋮ > 삭제 메뉴를 클릭해 주십시오.
- 삭제 팝업 창이 나타나면 [삭제] 버튼을 클릭해 주십시오.