要は(TL;DR)
- Watson AssistantのAPIにはV1とV2があり、非互換部分があります＆機能も違います
- V2 APIはAssistantとSkillをベースにしたアーキテクチャー変更に対応したものであり、長期的にはV2を使っていくのがよいです
- V2 APIではAssistantとの会話を司るSessionというオブジェクトを意識する必要があります
- V2 APIではContextは自動的に維持されるのでV1の時のようにユーザーアプリで毎回送り返す必要はありません
- V2 APIのContextでユーザー変数を使う場合は"skills"->"main skill"->"user_defined"（←ここまで決めうち1)の下に{"hogevar": "hogevalue"}の形で書く必要があります
はじめに
こんにちわ！石田です。Assistantマニュアルをよく読まれている方はご存知かと思いますが、Watson AssistantのAPIはV1と新しいV2があります。この違いについて、あれこれ調べたこと2をお伝えします。近々でV1 APIが使えなくなるわけではないので、皆様が新しいV2のAPIに取り組まれるのは先々でもいいのかな？とは思いますが、新規アプリなどの場合はV2 APIを使っておいたほうがよさそうです。要は先々のお役にたてばと思い記事にします。
APIの説明 API V1とV2の違いサマリー
| V1 API | V2 API | |
|---|---|---|
| ランタイム・メソッド (対話用API) |
○ (/message) | ○ (/message) |
| オーサリング・メソッド (環境操作API)3 |
○ | ×(今は、なし) |
| 要求の投げ先 | ワークスペース | アシスタント |
| セッションの利用 | 不可(N/A) | 必須 |
| Contextの維持 | クライアントアプリの責任 | 自動で行われる |
| Contextデータの表現形式 | 任意(key:value) |
"skills"->"main skill" ->"user_defined"の下にkey:valueで書く |
| User-based plansでの user_idセット箇所 |
context.metadata.user_id | context.global.system.user_id |
概要
先日、こちらの記事でもお伝えしたとおり、2018/11/9にWatson Assistantのアーキテクチャー変更があり、従来のWorkspaceがSkillになり、クライアントとの間にAssistantが介在するようになりました。V2のAPIはこのアーキテクチャーに対応するものです。
上記は新旧APIの道筋を表現した絵です。
- 従来のV1 APIではクライアントはワークスペース(今後はスキル)に対して要求を投げ、直接やり取りをしていました。当然ですが、現時点では従来とおりV1のAPIを使い続けてもOKです。
- 新しいV2 APIを使う場合は要求を投げる先は介在するアシスタントであり、スキルではありません。アシスタントとスキル間のやりとりはクライアントからは見えません。クライアントとアシスタントとのやりとりではV1では存在しなかったセッション(Session)というオブジェクトを使います。
セッションとコンテキストについて
「セッション」はWebアプリケーションではなじみのある用語かと思います。Watson Assistant側の実装はわかりませんが、要はV2 APIで「セッション」ができた事でWatson Assistantのサービス側でセッション上にコンテキストの情報を保持できるようになりました。以前のV1 APIではユーザー変数などのコンテキスト・データを扱いたければ、クライアント側のアプリケーション・ロジックでリクエストの都度(毎回)、全データを受信/(必要なら更新)/再送する必要がありましたが、V2ではその必要はありません。毎回送らなくてもWatson Assistantのサービス側でコンテキストの内容を保持しており、参照できます。以下、新旧対比しつつ、もう少し細かくご説明します。
従来の方式(V1 API)
V1 APIではWatson Assistantは完全にステートレスなサービスであり、顧客名などのユーザー変数を扱いたい場合はクライアント・プログラムがデータをContextに設定して要求の都度、送信する必要がありました。
V1 APIではContextの形式はJSONで任意のKEY-VALUEペアを書けばいいだけです。例えば以下の形式で要求と共に渡すと、Dialog側では@(myname)で値が参照できます。
context={
'myname': 'ishida'
}
'output': {'generic': [{'response_type': 'text', 'text': 'hello! Mr.ishida '}], 'text': ['hello! Mr.ishida '],
V2 API
V2 APIではSessionを開始してContextにユーザー変数を設定4してしまえば、あとはSessionをクローズするまで自動的に保持されています。V1の場合のように毎回、全量を送信する必要はありません。
Contextの形式はAPI V2 Rerefenceに定義されていますがV1の時のように好きなkey-valueペアではなく「お約束」があります。具体的にはDialog側で@(myname)で値を参照するには以下のように書かないといけません。
"skills"->"main skill"->"user_defined"までは決めうちのキーワードです。(case-sensitiveです) その下に任意のke-valueペアを書きます。別の書き方をするとDialog側で@(myname)で値は参照できません。5
context={
"skills": {
"main skill": {
"user_defined": {
"myname": "ishida"
}
}
}
}
一番シンプルなサンプル・コード(Python)
以下にv1/v2のサンプルコード(Python SDK)をお示しします。（ご参考までに末尾にnode.jsでのサンプルも記載しておきます) 両方を比べると違いが見えてくると思います。
V1の時
from watson_developer_cloud import AssistantV1
iam_apikey='xxxxxxxx'
workspace_id = 'xxxxxxxx'
assistant = AssistantV1(
iam_apikey=iam_apikey,
version='2018-07-10')
# message
response = assistant.message(
workspace_id=workspace_id,
input={'text':'hello'},
context={
'myname': 'ishida'
}).get_result()
print(response)
{'intents': [{'intent': 'General_Greetings', 'confidence': 1}], 'entities': [], 'input': {'text': 'hello'}, 'output': {'generic': [{'response_type': 'text', 'text': 'hello! Mr.ishida '}], 'text': ['hello! Mr.ishida '], 'nodes_visited': ['node_13_1502484041694'], 'log_messages': []}, 'context': {'myname': 'ishida', 'conversation_id': 'c5d28afc-6d53-479f-a7cd-ffebc2752729', 'system': {'initialized': True, 'dialog_stack': [{'dialog_node': 'root'}], 'dialog_turn_counter': 1, 'dialog_request_counter': 1, '_node_output_map': {'node_13_1502484041694': {'0': [0]}}, 'branch_exited': True, 'branch_exited_reason': 'completed'}}}
V2の時
V2では、まずセッションを入手してから対話を行う(/message)のが今までとの違いです。
import json
from watson_developer_cloud import AssistantV2
assistant_id = 'XXXXXXXX'
iam_apikey='XXXXXXXX',
assistant = AssistantV2(
iam_apikey=iam_apikey,
version='2018-11-08')
# 【1】Sessionを作る
session_id = assistant.create_session(assistant_id).get_result()
print(json.dumps(session_id, indent=2))
# 【2】Assistant IDとSessionを渡す
message = assistant.message(
assistant_id,
session_id["session_id"],
# 【3】ユーザー変数を参照したい場合は'options':{'return_context': True}
input={'text':'hello',
'options':{'return_context': True}
},
# 【4】ユーザー変数は必ず"skills"->"main skill"->"user_defined"（←ここまで決めうち)
# の下に{"hogevar": "hogevalue"}の形で書く. この点がV1との違い
context={
"skills": {
"main skill": {
"user_defined": {
"myname": "ishida"
}
}
}
}).get_result()
print(message)
# 【5】Sessionを削除する
assistant.delete_session(assistant_id, session_id["session_id"]).get_result()
{'output': {'generic': [{'response_type': 'text', 'text': 'hello! Mr.ishida '}], 'intents': [{'intent': 'General_Greetings', 'confidence': 1}], 'entities': []}, 'context': {'global': {'system': {'turn_count': 1}}, 'skills': {'main skill': {'user_defined': {'myname': 'ishida'}}}}}
【V2のコードの解説】(番号はコメントの番号に対応)
まずはcreate_session()にてSessionを入手します
以降、/messageで発話する際はアシスタントのID以外に前項で入手したSessionのIDを引き渡します
クライアント側でContextに設定したユーザー変数群を参照したい場合は'options':{'return_context': True}とTrueにします。デフォルトはFalseで、その場合'skills': {'main skill': {'user_defined': {'myname': 'ishida'}}}}の部分はレスポンスに含まれません。
ユーザー変数は必ず"skills"->"main skill"->"user_defined"（←ここまで決めうち)の下に{"hogevar": "hogevalue"}のkey-valueペアの形で書きます。上記はCase-Sensitiveであり、間違えるとユーザー変数が参照できません。
対話が終わったらdelete_session()でセッションを消します
ご参考) Assistant IDの入手
プログラムにセットするAssistant IDは上記から参照できます
Contextの自動メンテについて
V2 APIではContextにセットしたユーザー変数はWatson Assistantのサービス側にて保持されているのでセッションを消すまで(または会話が無い状態で一定時間6が経過するまで)なくなりません。
以下のコード例では対話の冒頭で'hello'と言う時のみContext=で顧客の名前を渡しています。それ以降は名前をいちいち渡さずとも、顧客の名前が入手できています。（クライアント側でのContextのCRUDも、もちろん可能です)
import json
from watson_developer_cloud import AssistantV2
assistant_id = 'xxxxxxxx'
iam_apikey='xxxxxxxx',
assistant = AssistantV2(
iam_apikey=iam_apikey,
version='2018-11-08')
session_id = assistant.create_session(assistant_id).get_result()
print(json.dumps(session_id, indent=2))
#########################
# Message
#########################
print('{0}'.format('-'*30))
message = assistant.message(
assistant_id,
session_id["session_id"],
input={'text':'hello',
'options':{'return_context': True}
},
context={
"skills": {
"main skill": {
"user_defined": {
"myname": "ishida"
}
}
}
}
).get_result()
print(message)
print('{0}'.format('-'*30))
message = assistant.message(
assistant_id,
session_id["session_id"],
input={'text':'thanks',
'options':{'return_context': True}
}
).get_result()
print(message)
print('{0}'.format('-'*30))
message = assistant.message(
assistant_id,
session_id["session_id"],
input={'text':'bye',
'options':{'return_context': True}
}
).get_result()
print(message)
assistant.delete_session(assistant_id, session_id["session_id"]).get_result()
{
"session_id": "bbf62560-00d2-4861-9ac7-4b066237ad96"
}
------------------------------
{'output': {'generic': [{'response_type': 'text', 'text': 'hello! Mr.ishida '}], 'intents': [{'intent': 'General_Greetings', 'confidence': 1}], 'entities': []}, 'context': {'global': {'system': {'turn_count': 1}}, 'skills': {'main skill': {'user_defined': {'myname': 'ishida'}}}}}
------------------------------
{'output': {'generic': [{'response_type': 'text', 'text': "You're welcome, Mr.ishida . Just let me know if you need anything else"}], 'intents': [{'intent': 'Thanks', 'confidence': 1}], 'entities': []}, 'context': {'global': {'system': {'turn_count': 2}}, 'skills': {'main skill': {'user_defined': {'myname': 'ishida'}}}}}
------------------------------
{'output': {'generic': [{'response_type': 'text', 'text': 'So long, Mr.ishida '}], 'intents': [{'intent': 'Goodbye', 'confidence': 1}], 'entities': []}, 'context': {'global': {'system': {'turn_count': 3}}, 'skills': {'main skill': {'user_defined': {'myname': 'ishida'}}}}}
user-based planについて
記事「Watson Assistantの新しいプラン「Plus」と月次ユーザー数課金(MCU)導入のご紹介」に詳細を書きましたが新しいMCU課金への対応に際して、V1/V2 APIで少し違いがあります。よろしければ上記記事もご参照ください。
以上です
注意 2018/11/26現在、V2 APIのドキュメントにはバグがあります
自分がハマッたので書いておきます。（報告したので、そのうち直るでしょうけれど）そもそもはV2 APIでContextを扱う場合、V1の書き方だとユーザー変数が渡らず、悩んでいました。API V2 Referenceを見ましたが「Skillsというエントリーを使うんだよ」という記述以外に細かいContextの書き方が何も書いてませんでしたので「これでどうやれっーつの！」と。それでStackOverflowで聞いたり、とあれこれ調べたら「Curlのタブを選んだ状態で文書を見ると、もっと詳しい情報が表示される」「Java/Node/Pythonのタブを選んだ状態で文書を見ると、何も表示されない」のだと気がつきました。マジか。。
ご参考) node.jsでの一番シンプルなサンプルコード
'use strict';
/*
Watson Assistant
*/
const express = require('express');
const app = express();
const port = 3000;
var watson = require('watson-developer-cloud');
app.get('/', (req, res) => res.send('Hello World!'));
app.listen(port, () => console.log('Example app listening on port %d', port));
const util = require('util');
var assistant_id = 'XXXXXXXX';
var iam_apikey='XXXXXXXX';
var assistant = new watson.AssistantV2({
iam_apikey: iam_apikey,
version: '2018-11-08'
});
async function createSession() {
var params = {
assistant_id: assistant_id
};
const createSessionPromise = util.promisify(assistant.createSession);
var response = await createSessionPromise.call(assistant, params);
return response["session_id"];
}
async function message(session_id, text) {
var params = {
assistant_id: assistant_id,
session_id: session_id,
input: {
'message_type': 'text',
'text': text
},
context: {
"skills": {
"main skill": {
"user_defined": {
"myname": "ishida"
}
}
}
}
};
const messagePromise = util.promisify(assistant.message);
var response = await messagePromise.call(assistant, params);
console.log('message response:',
JSON.stringify(response, null, 2));
}
var session_id;
async function main() {
var session_id = await createSession();
await message(session_id, "Hello");
}
main()
Example app listening on port 3000
message response: {
"output": {
"generic": [
{
"response_type": "text",
"text": "hello! Mr.ishida "
}
],
"intents": [
{
"intent": "General_Greetings",
"confidence": 1
}
],
"entities": []
}
}
-
「今はきめうち」であってAssistantが複数スキルをサポートしたら変わるかもしれません ↩
-
当記事の元ネタはこのStackOverflowでの質問やこのPython_SDKのIssueです ↩
-
インテントやエンティティを定義する、ダイアログを操作する、などの環境構築系のAPI群 ↩
-
Contextの変数はクライアントのアプリケーションで設定することもできますし、Dialogのフローで設定することもできます。 ↩
-
これは「試した結果では、今のSDKではこう書かないと参照できない」というお話です。翻ってAPI_V2のドキュメント上は「Skillsは個々のスキルの固有のデータを保持する」と書いてあります。将来的にAssistantは複数スキルをサポートする予定と聞いていますので、そうなると今のような「決めうちキーワード」の設計では破綻します。よって先々、改めて変更が入るのかもしれません。または私の知らないなんらかの表記のルールがあるのかもしれませんが、ドキュメントに書いてないのでわからないんですよね。。 ↩
-
Lire/Standardプランは5分、Plusプランは60分 ↩