Classic/VPC環境で利用できます。
スキルは、ユーザーの要件に正確かつ適切にレスポンスするために使用するツールです。モデルはユーザーの質問とスキルに作成された APIを分析し、最も適切な答えを与えることができるスキルを選択した後、正確な情報を呼び出してユーザーに提供できます。
スキルトレーナーで作成したスキルは、以下のようなタスクを行えます。
- リアルタイム情報検索: 動物病院の照会、求人広告の照会、リアルタイムの人気サービス、リアルタイムの車両情報
- 知的基盤情報検索: おすすめ旅行スポット、おすすめ商品、旅行情報
スキル作成
スキルを作成する方法は、次の通りです。
- NAVERクラウドプラットフォームコンソールで、
> 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 の [重複チェック] ボタンをクリックします。
- 必須情報をすべて入力した後、 [作成する] ボタンをクリックします。
- 現在までのタスク内容を保存するには、 [一時保存] ボタンをクリックします。
- すべての領域に入力した場合でも、 [一時保存] ボタンをクリックすると、タスクステータスが「タスク中」に保存されます。
- スキル作成完了画面が表示されたら、 [確認] ボタンをクリックします。
参考
1つのスキルセットに、最大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を提供する対象ホスト情報として、Pathsの 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のいずれの1つの値だけを持つ必要がある場合、descriptionに具体的に作成します。
例) maleまたは femaleのいずれか - 江南で検索しても江南区で urlに入る必要がある場合、descriptionに具体的に作成します。
例) 江南区、瑞草区 - 当該パラメータが限定された場所を検索する値である場合、単純な検索キーワードではなく、「レストランやカフェなどの特定の場所を検索するときに使用される」という意味をモデルが理解できるように作成します。
例)
json
{
"parameters": [
{
"name": "place_category",
"in":"query",
"description": "場所の大分類。restaurant、cafe、attraction、accommodationの中から1つ。",
"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文字以内で入力してください。韓国語、記号、スペースは使用できません。
- 2つ以上の単語を組み合わせる場合、各単語の先頭の文字は大文字で入力してください。例えば、「animal」と「hospital」という2つの単語を組み合わせて API名を作る場合、「AnimalHospital」と作成します。
- スキル名に「API」という単語は使用しないでください。
-
- APIの目的と用途を作成します。すべての APIのロールを明確に作成する必要があります。ユーザーの質問に基づいて、モデルが複数の APIの中から必要な APIを選択する基準となります。
- 例えば、動物病院検索、愛犬カフェ検索、愛犬用品検索の APIが存在する場合、ユーザーの質問が「動物病院の位置を教えて」の場合、モデルは各 APIの description for humanを読み取って動物病院検索 APIを選択します。
- 作成例は次の通りです。
蔚山広域市にある動物病院を探すときに使います。病院名で照会し、動物病院の住所と連絡先情報を提供します。 -
- APIの主な使用方法を5000文字以内で作成します。モデルがユーザーの質問に答える時に使用する 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は、販売店名を検索キーワードとして入力すると動作します。送信するクエリには冠詞、前置詞、決定子などの停止キーワードが含まれてはいけません。リンクは常に返し、ユーザーに表示する必要があります。
スキル編集
スキル情報を編集する方法は、次の通りです。
- NAVERクラウドプラットフォームコンソールで、 > Services > AI Services > CLOVA Studio メニューを順にクリックします。
- My Product メニューで [CLOVA Studioに移動する] ボタンをクリックします。
- CLOVA Studioで スキルトレーナー メニューをクリックします。
- スキルセットをクリックします。
- スキル タブをクリックした後、編集するスキル名をクリックします。
- スキル情報を変更した後、 [保存する] ボタンをクリックします。
- 変更した内容があるか、必須項目がすべて入力されると、 [保存する] ボタンが有効になります。
- スキル名と Name for modelを変更した場合、 [重複チェック] ボタンをクリックします。
- API Specを変更した場合、 [検証する] ボタンをクリックします。
- 編集する内容がない場合、 [キャンセル] ボタンをクリックします。
スキル削除
スキルを削除する方法は、次の通りです。
- NAVERクラウドプラットフォームコンソールで、 > Services > AI Services > CLOVA Studio メニューを順にクリックします。
- My Product メニューで [CLOVA Studioに移動する] ボタンをクリックします。
- CLOVA Studioで スキルトレーナー メニューをクリックします。
- スキルセットをクリックします。
- [スキル] タブをクリックします。
- 削除するスキルの ⋮ > 削除 メニューをクリックします。
- 削除のポップアップが表示されたら、 [削除] ボタンをクリックします。