スキル管理
- 印刷する
- PDF
スキル管理
- 印刷する
- PDF
Article Summary
Share feedback
Thanks for sharing your feedback!
最新のコンテンツが反映されていません。早急にアップデート内容をご提供できるよう努めております。最新のコンテンツ内容は韓国語ページをご参照ください。
Classic/VPC環境で利用できます。
スキルは、ユーザーの要件に正確かつ適切にレスポンスするために使用するツールです。モデルはユーザーの質問とスキルに作成された APIを分析し、最も適切な答えを与えることができるスキルを選択した後、正確な情報を呼び出してユーザーに提供できます。例えば、動物病院の照会リクエストに対応できる「動物病院照会 API」、旅行先のおすすめリクエストに対応できる「おすすめ旅行先 API」を1つのスキルで構成できます
スキル作成
スキルを作成する方法は、次の通りです。
- 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仕様を再度変更してください。
- Manifest領域に情報を入力します。
- Manifestの作成方法は、Manifest作成をご参照ください。
- 必須情報をすべて入力した後、 [保存] ボタンをクリックします。
- 現在までのタスク内容を保存するには、 [一時保存] ボタンをクリックします。
- すべての領域に入力した場合でも、 [一時保存] ボタンをクリックすると、タスク状態が「タスク中」に保存されます。
- スキル作成完了画面が表示されたら、 [確認] ボタンをクリックします。
参考
初めてスキルを作成する場合、バージョン v1が作成されます。当該バージョンを基本モデルとして呼び出したい場合、 スキルトレーナー > タスク > バージョン管理 メニューでテストアプリを作成した後、サービスアプリを申し込んで連携します。詳細は、スキルセットバージョン管理をご参照ください。
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に具体的に作成します。
例) 江南区、瑞草区 - 当該パラメータが限定された場所を検索する値である場合、単純な検索キーワードではなく、「レストランやカフェなどの特定の場所を検索するときに使用される」という意味をモデルが理解できるように作成します。
例){ "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タイプの場合のみ適用できます。正常に適用するには、レスポンスに使用されるすべてのパラメータを正確に作成する必要があります。
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"
}
}
}
}
}
}
}
参考
以下のような場合に活用することをお勧めします。
- APIレスポンスが長いため、トークン数の超過エラーが発生する場合
- x-exclude-cotが適用されたパラメータの場合、シナリオ収集プロセス中にスキルデータ領域ステップ2(API呼び出しステップ)の監視から除外されます。そのため、実際に使用しないパラメータに x-exclude-cotを適用することで、APIレスポンスを減らせます。
- 学習費用を節約したい場合
- 不要なパラメータに x-exclude-cotを適用すると、シナリオ収集プロセスでトークン数を節約せきます。その結果、学習に使用するトークン数を節約できます。
API Spec設計時の注意事項
API Spec設計時の注意事項について説明します。
{
"detail": "{'status': 200, 'message: 'Required parameter theme, min_grade is missing.'}"
}
参考
ただし、HCX-002エンジンを使用する場合は、必須パラメータが欠落すると、以下のように400エラーを返すように設計してください。
{
"detail": "{'status': 400, 'error': 'Bad Request', 'message': 'Required parameter theme, min_grade is missing.'}"
}
呼び出しパラメータの最小化
例えば、飛行機予約 APIを呼び出す時、APIで得られる結果が「出発地」、「到着地」、「航空会社」、「出発日」、「到着日」、「金額」が記載された多数のデータだとします。もし APIの呼び出しパラメータを「到着地」だけ登録した場合、「金浦空港から出発して済州空港に到着する7月21日に出発する30万ウォン以下の飛行機を教えて」とリクエストしても、実際に呼び出し可能なパラメータは「済州」なので、APIは「済州」が到着地であるすべての場合の数値をすべて返します。このような場合、目的の結果を得ることは困難です。
APIで取得できる結果が「出発地」、「到着地」、「航空会社」、「出発日」、「到着日」、「金額」の場合、呼び出し可能なパラメータに「出発地」、「到着地」、「航空会社」、「出発日」、「到着日」、「金額以上検索」、「金額以下検索」のように、呼び出し可能なパラメータを細かく配置することをお勧めします。各パラメータは必須値である場合もあれば、必須値でない場合もあります。「金浦空港から出発して済州空港に到着する7月21日に出発する30万ウォン以下の飛行機を教えて」とリクエストした場合、APIは実際にその条件を満たす結果のみを返すので、希望する答えを正確かつ迅速に得ることができます。パラメータの重複呼び出し
1回の呼び出しで同じパラメータを複数呼び出すように設計する場合、APIがスムーズに動作しないため、十分なデータを作成する必要があります。
同じパラメータを複数使用する場合の例は、次の通りです。
http://goodfood.or.kr/openApi/restful/food?drink=coke&drink=milk&menu=hamburger
API Specの作成例
API Specの作成例は、次の通りです。
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を使用する例
{
"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の入力領域である schema version、Name for model、Description for human、Description for modelの各フィールドを説明します。
API名を作成します。他の APIと名前が重複しないようにし、APIの性質を含めて簡潔に作成する必要があります。
英数字を使用し、先頭の文字列は大文字にして20文字以内で入力してください。韓国語、記号、スペースは使用できません。
2つ以上の単語を組み合わせる場合、各単語の先頭の文字は大文字で入力してください。例えば、「animal」と「hospital」という2つの単語を組み合わせて API名を作る場合、「AnimalHospital」と作成します。
スキル名に「API」という単語は使用しないでください。
Description for human
APIの目的と用途を作成します。すべての APIのロールを明確に作成する必要があります。ユーザーの質問に基づいて、モデルが複数の APIの中から必要な APIを選択する基準となります。例えば、動物病院検索、愛犬カフェ検索、愛犬用品検索の APIが存在する場合、ユーザーの質問が「動物病院の位置を教えて」の場合、モデルは各 APIの description for humanを読み取って動物病院検索 APIを選択します。
作成例は次の通りです。
蔚山広域市にある動物病院を探すときに使います。病院名で照会し、動物病院の住所と連絡先情報を提供します。
Description for model
APIの主な使用方法を作成します。モデルがユーザーの質問に答える時に使用する 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で スキルトレーナー メニューをクリックします。
- [スキルセット] タブで情報を変更するスキルセットの [リスト] ボタンをクリックします。
- スキルリストの右側にある [編集] ボタンをクリックします。
- 編集画面が表示されたら、スキル情報を変更した後、 [保存] ボタンをクリックします。
- 変更した内容があるか、必須項目がすべて入力されると、 [保存] ボタンが有効になります。
- 編集する内容がない場合、 [キャンセル] ボタンをクリックします。
スキル削除
スキルを削除する方法は、次の通りです。
- NAVERクラウドプラットフォームコンソールで Services > AI Services > CLOVA Studio メニューを順にクリックします。
- My Product メニューをクリックした後、[CLOVA Studioに移動する] ボタンをクリックします。
- CLOVA Studioで スキルトレーナー メニューをクリックします。
- [スキルセット] タブでスキルセットの [リスト] ボタンをクリックします。
- スキルリストが表示されたら、削除するスキルの右端にある もっと見る
> [削除] ボタンをクリックします。 - 削除のポップアップが表示されたら、 [削除] ボタンをクリックします。
> [削除] ボタンをクリックします。参考
本人が作成したスキルのみ削除できます。
この記事は役に立ちましたか?