Available in Classic and VPC
Skills are tools used to provide accurate and appropriate responses to user requests. Models analyze user questions and the APIs written within skills to select the most appropriate skill, call accurate information, and deliver it to the user.
The skills created in the skill trainer can perform the following tasks.
- Real-time information search: veterinary hospital search, job postings search, real-time popular products, real-time vehicle information
- Knowledge-based information search: travel destination recommendations, product recommendations, travel information
Create skill
To create a skill, follow these steps:
- From the NAVER Cloud Platform console, click
> Services > AI Services > CLOVA Studio in order. - From the my product menu, click the [Go to CLOVA Studio] button.
- In CLOVA Studio, click the Skill trainer menu.
- Click a skill set.
- Click the [Create skill] button on the top right corner of the screen.
- Once you see the skill information screen, enter your skill name, and click the [Check duplicates] button.
- The skill name allows English letters, Korean characters, numbers, and blanks. It cannot exceed 20 characters.
- Make sure your skill name is unique within the skill set.
- In the API spec field, provide the API specifications in JSON format based on the OAS 3.0 version.
- For more information on how to write API spec, see write API spec.
- After writing the API specifications, click the [Validate] button.
- Once the validation is complete, you'll see the "API spec validation is complete" message, and the [Validate] button will be disabled.
- If the validation fails, an error message will be displayed. Edit the API specifications.
- Enter the information in the Manifest area.
- For more information on writing a Manifest, see write manifest.
- Click the [Check duplicates] button of the name for model.
- Enter all the required information, and then click the [Create] button.
- To save the work done so far, click the [Save draft] button.
- Even if all fields have been filled out, if you click the [Save draft] button, the task status will be saved as "In progress."
- When the Skill creation completion window appears, click the [OK] button.
Note
A maximum of 10 skills may be added to a skill set.
Write API spec
In the API spec field, write API specifications the model can understand. Skill trainer only supports JSON format. For more information on specifications, see OpenAPI specification v3.0.0.
Version
This is the OpenAPI version to use. Only version 3.0 is supported. If you use another version, an error may occur. This value is required.
See the following examples:
{
"openapi": "3.0.0"
}
Info
Information regarding the API provided. This value is required.
| Field | Description | Required |
|---|---|---|
| version | API version information | Y |
| title | API name | Y |
See the following examples:
info:
version: API version
title: API title
description: API description
contact: API provider
license: API license information
Servers
This is the information about the target hosts for the API, the baseURL of the paths. This value is required.
| Field | Description | Required |
|---|---|---|
| url | Server URL | Y |
See the following examples:
servers:
- url: https://sample.naver.com/v1
Paths
This is the information about each path of the provided API. This value is required. Under each path, there is an operation object and a parameter object.
| Field | Description | Required |
|---|---|---|
| Summary I Description | Specify the parameters to use and the information you can obtain from the path Example: search regions and cities you want to travel to, based on whether it's a domestic or overseas destination, the Region's name, visiting month, number of visitors, estimated budget |
Y |
Note
- Only the requests get, requests post methods are supported.
- For the post method, "nested datatypes" are not officially supported. When you write your description, separate your parameters.
- Assume that your URL operates based on the argument method when writing. The current model only supports the argument method. (Parameter=parameter value)
Example 1: http://test.com/data?birthdata=20190302&address=Seocho-gu (O)
Example 2: http://test.com/data?20190302/Seocho-gu (X)
See the following examples:
paths:
/test:
get:
Description: get test data (specify under what circumstance the path is used)
operationId: getTest
responses:
'200':
description: test response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Test'
Parameter Object
The following describes the parameters you can apply to your tasks. This value is required.
| Field | Description | Required |
|---|---|---|
| name | Parameters name. Case sensitive | Y |
| in | Location of the parameters.
|
Y |
| description | Specific description of parameters | N |
| required | Determine whether a parameter is required or not
|
N |
| schema: type | Set parameter data type
|
N |
| schema:format | Set formats by data type
|
N |
Note
In description, specify what your parameter means, under what circumstance it's used, and in what format you should create your URL. If the value of your parameter must be limited, specify an example of the value.
- If the value must be either male or female, specify that in the description.
Example: either male or female - If a user searches the keyword "Gangnam" but the url should still show Gangnam District, specify that in the description.
Example: Gangnam District, Seocho District - If your parameter is used to search for a specific place, make sure the model understands that the parameter is not just search keywords but a specific place such as a restaurant or a coffee shop.
Example:
json
{
"parameters": [
{
"name": "place_category",
"in":"query",
"description": "large categories of places. One of restaurant, cafe, attraction, and accommodations.",
"required": false,
"schema": {
"type": "string"
}
}
]
}
See the following examples:
parameters:
- name: birthdate
in: query
description: date of birth. Use yyyy-mm-dd format.
required: true
schema:
type: array
style: simple
items:
type: string
format: date
Operation Object
The following describes API call tasks. This value is required.
| Field | Description | Required |
|---|---|---|
| description | Specific description of task actions | N |
| operationId | Unique string for identifying a task. You can also use operationId from other tools or libraries using Open API for identification | Y |
| responses | List of responses that can be returned after running a task. Responses are in Response Object format | Y |
See the following examples:
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
The following describes task responses. This value is required.
| Field | Description | Required |
|---|---|---|
| description | Brief description of a response | Y |
Note
Response 200 is required, but you can add other responses depending on the HTTP status code.
- If a request is made to an incorrect parameter, error 422 and 400 are returned.
- If there is no defined error code, error 422 is arbitrarily made and returned.
See the following examples:
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
These are a group of components reusable in various parts of OAS.
| Field name | Type | Description |
|---|---|---|
| schemas | Map[string, Schema Object I Reference Object] | Reusable components from schema object |
| responses | Map[string, Response Object I Reference Object] | Reusable components from response object |
| parameters | Map[string, Parameter Object I Reference Object] | Reusable components from parameter object |
| examples | Map[string, Example Object I Reference Object] | Reusable components from example object |
See the following examples:
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 expansion feature
You can use the x-exclude-cot object in the API spec to exclude the parameter from the API response. It is used in response object and is applicable only when content-Type is the application/json type. Only when all parameters used in the response must be entered accurately can they be applied normally.
The x-exclude-cot object can be utilized in the following cases.
- When API responses are lengthy and result in token limit excess errors,
parameters with x-exclude-cot applied will be excluded from the "API response results" during data collection. Therefore, applying x-exclude-cot to parameters that are not actually used can reduce the API responses during data collection. - If you want to save on training costs,
applying x-exclude-cot to unnecessary parameters can save tokens during data collection. As a result, the number of tokens used for training can be reduced.
An example of design to exclude the parameter called address from the API response is as follows:
"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"
}
}
}
}
}
}
}
Note
If you're calling a skill by issuing a test app or a service app, not by collecting data, all fields with x-exclude-cot applied are exposed to the API response. In this case, you don't see any token limit excess errors for the API response.
API spec writing example
The following describes an API spec writing example.
Examples of using Requests_get
The following shows an example using Requests_get.
{
"openapi": "3.0.0",
"info": {
"version": "v0",
"title": "search domestic flight schedule"
},
"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": "searching domestic flight schedule.",
"operationId": "productsUsingGET",
"parameters" : [ {
"name" : "serviceKey",
"in" : "query",
"description": "be sure to use 2FMD for serviceKey",
"required" : true,
"schema" : {
"type" : "string",
"default" : "1"
}},
{
"name" : "schDate",
"in" : "query",
"description": "search date. You must use an 8-digit format. For example, if it's April 1st, 2022, 20220401",
"required" : false,
"schema" : {
"type" : "string"
}
}, {
"name" : "schDeptCityCode",
"in" : "query",
"description": "destination code. For example, use GMP for Seoul. For arrival code, use CJU for Jeju and PSU for Busan",
"required" : false,
"schema" : {
"type" : "string",
"default" : "10"
}
}, {
"name" : "schArrvCityCode",
"in" : "query",
"description": "departure code. For example, use GMP for Seoul. For arrival code, use CJU for Jeju and PSU for Busan",
"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": "airline (Korean)"
},
"arrivalcity": {
"type": "string",
"description": "arriving airport"
},
"domesticArrivalTime": {
"type": "integer",
"description": "arrival time"
},
"domesticEddate": {
"type": "string",
"format": "date-time",
"description": ""
},
"domesticFri": {
"type": "string",
"description": "friday"
},
"domesticMon": {
"type": "string",
"description": "monday"
},
"domesticNum": {
"type": "string",
"description": "flight number"
},
"domesticSat": {
"type": "string",
"description": "saturday"
},
"domesticStartTime": {
"type": "integer",
"description": "departure time"
},
"domesticStdate": {
"type": "string",
"format": "date-time",
"description": ""
},
"domesticSun": {
"type": "string",
"description": "sunday"
},
"domesticThu": {
"type": "string",
"description": "thursday"
},
"domesticTue": {
"type": "string",
"description": "tuesday"
},
"domesticWed": {
"type": "string",
"description": "wednesday"
},
"startcity": {
"type": "string",
"description": "departing airport"
},
"numOfRows": {
"type": "integer",
"description": "number of rows"
},
"pageNo": {
"type": "integer",
"description": "page number"
},
"totalCount": {
"type": "integer",
"description": "total data count"
}
}
}
}
}
}
Example of using Requests_post
The following shows an example using 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 for registering bakery product information.",
"description": "API for registering bakery product information.",
"operationId": "filterBakeryProducts",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "english product name"
},
"max_price": {
"type": "integer",
"description": "max amount (KRW)"
},
"ingredients": {
"type": "string",
"description": "english ingredient name"
},
"expiration_date": {
"type": "string",
"description": "expiration date. Example) 20220701"
},
"allergens": {
"type": "string",
"description": "english name for allergen"
}
},
"required": [
"max_price"
]
}
}
}
},
"responses": {
"200": {
"description": "successful response",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "product ID"
},
"name": {
"type": "string",
"description": "product name"
},
"price": {
"type": "integer",
"description": "amount (KRW)"
},
"ingredients": {
"type": "array",
"items": {
"type": "string"
},
"description": "ingredient list"
},
"expiration_date": {
"type": "string",
"format": "date",
"description": "expiration date"
},
"calories": {
"type": "integer",
"description": "calories"
},
"allergens": {
"type": "array",
"items": {
"type": "string"
},
"description": "allergen list"
},
"additional_options": {
"type": "array",
"items": {
"type": "string"
},
"description": "additional options list"
}
}
}
}
}
}
}
}
}
}
}
}
Write manifest
Manifest is the area where you enter the name and purpose of the API and how to use the API that can be called through the skill. It describes each field in the manifest input area: name for model, description for human, and description for model.
-
- Enter the name of your model. The name must be unique and concise, containing the characteristics of your API.
- The name can contain up to 20 English letters and must begin with a capital letter. Korean characters, special characters, and blanks are not allowed.
- If you want to combine 2 or more words, the first letter of each word must be capitalized. For example, if you want to combine 2 words, "animal" and "hospital," use "animalhospital."
- Do not use the word "API" for your skill name.
-
- Describe the purpose and use of the API. All roles of your API should be clearly specified. Based on the users' questions, this description is the standard by which the model selects an API out of many.
- For example, let's say there are vet, pet cafe, and pet supply shop search APIs. If a user says "Tell me the location of a vet," the model reads each API's description_for_human and selects the vet search API.
- See the following examples:
Use when you search for vets in Ulsan. View by the name of the animal hospital and show its address and contact.
-
-
Describe the major usages of your API in up to 5,000 characters. When the model decides which API to use when answering a user's question, it refers to both the question and "decription_for_model" before selecting the most appropriate API. Also, you need to specify the information that can be returned as an API response. Specify the scope of the information that can be returned by calling each API so that the model can adequately decide which API to use. If there are multiple paths, you need to specify the role of each path. Specify the keywords to be searched for each path so that the model can properly use the API.
-
See the following examples:
This is the API for viewing the information about traditional markets and their parking lots. If you call this API, the name, address, and operation hours of the place are offered as a response. If you want to learn about traditional markets in Seoul/use traditional_market. /traditional_market operates when you search the following keywords: market name, operating days, closed days, address, business opening time, and closing time. If you want to learn about their parking lots, use /parking_lot. /parking_lot operates when you search the following keywords: Region_gu, region_dong, parking lot name, parking lot type, operating hours, and minimum fee. Queries to be sent should not include stop words such as articles, prepositions, or determiners. Links must always be returned and displayed to users.This is the API for viewing the information about vets in Ulsan. If you call this API, the name, location, phone number, and operation hours of the vet are offered as a response. If you want to search for vets in Ulsan, use /getPetHospitalList. /getPetHospitalList operates when you enter a store name as a search keyword. Queries to be sent should not include stop words such as articles, prepositions, or determiners. Links must always be returned and displayed to users.
-
Edit skill
To edit your skill information, follow these steps:
- From the NAVER Cloud Platform console, click Services > AI Services > CLOVA Studio in order.
- From the my product menu, click the [Go to CLOVA Studio] button.
- In CLOVA Studio, click the Skill trainer menu.
- Click a skill set.
- Click the Skill tab and then click the skill name you want to edit.
- Edit the skill information, and then click the [Save] button.
- The [Save] button can only be activated if you edit an item or all required items are filled in.
- After editing the skill name and the Name for model, click the [Check duplicates] button.
- After editing the API spec, click the [Validate] button.
- If there is nothing to edit, click the [Cancel] button.
Delete skill
To delete a skill, follow these steps:
- From the NAVER Cloud Platform console, click Services > AI Services > CLOVA Studio in order.
- From the my product menu, click the [Go to CLOVA Studio] button.
- In CLOVA Studio, click the Skill trainer menu.
- Click a skill set.
- Click the Skill tab.
- Click ⋮> Delete of the skill you want to delete.
- Once the delete window pops up, click [Delete].