この記事は IBM Cloud Advent Calendar 2020 の 16 日目の記事です。

IBM CloudのAIサービスWatsonはRESTのAPIで呼び出し可能です。また各種メジャーな言語でSDKも利用できます。

当記事はPythonからSDKを利用してIBM Watsonのサービスを使う方法を説明します。なお当記事は以下のバージョンを元にテストしています：
v5.0.0

結構バージョンによって使い方が変わっているので、注意しましょう。

v5.0.0では以下のAPI呼び出しができます。

assistant_v1
assistant_v2
compare_comply_v1
discovery_v1
discovery_v2
language_translator_v3
natural_language_classifier_v1
natural_language_understanding_v1
personality_insights_v3 (2020/12/1よりインスタンス作成不可, 2021/12/1サービス停止)
speech_to_text_v1
text_to_speech_v1
tone_analyzer_v3
visual_recognition_v3 (2021/1/7よりインスタンス作成不可, 2021/12/1サービス停止)
visual_recognition_v4 (2021/1/7よりインスタンス作成不可, 2021/12/1サービス停止)

0. 前提条件

IBM Cloudアカウントを持っている
サービスを作成済み(以下の例ではLanguage Translator)
- やり方がよくわからない場合はこちらを参考にしてください
python 3.5以上の実行環境がある

1.前準備

作成したサービスのAPIKEYとURLを確認できるようにしておいてください。
やり方がよくわからない場合はこちらを参考にしてください:
サービスの資格情報取得

2. Watson SDKの使い方の基本

まずは言語に関係なく、一般的な使い方の調べ方をご紹介します。
各種メジャーな言語のSDKの使い方は、実はIBM Cloud上のAPIドキュメントにあります！

API & SDK リファレンス・ライブラリーのカテゴリAI / Machine Learningにあるものが、各サービスのAPI&SDKのドキュメントへのリンクです。

当記事ではLanguage Translatorを例に説明しますので、Language Translatorのサービスを作成しておいてください。

基本1: API & SDK リファレンス・ライブラリーから使用するサービスをクリック

今回はLanguage Translatorを使いますので、API & SDK リファレンス・ライブラリーのカテゴリ　AI / Machine Learning から　Language Translatorをクリックします。

基本2: 右側の「Curl Java Node Python Go」などと書いてあるタブから、自分の使いたい言語をクリック

今回はPythonですので、「Python」をクリックしてください。
ちなみに2020/12/15に確認したところ、Curl, Java, Node, Python, Go, .NET, Ruby, Swift, Unityがタブにありました。

基本3: 左側のメニューから使い方を知りたいSubjectをクリック。

例えば「Introduction」だったらpipでのインストール方法が載っています。コピペして実行すればよいですね。

例えばMethod「Translate」だったら、選んだ言語の定義とサンプルコードが右側に表示されます。サンプルコードはコピペして、実行可能です。
ただし、{apikey}, {url}は自分のサービスのものに置き換える必要があるので注意しましょう。1. 前準備で準備したものに置き換えてください。

3. ではPythonから使おう!

「2. Watson SDKの使い方の基本にのっているドキュメントって英語なんですけど、、、」と引いてしまった方のために、一通り使い方を説明します。
ただ細かいSDKの使用はやっぱりSDKリファレンスをみないとわからないので、感覚を掴んだら、ぜひSDKリファレンスで詳細を調べてみてください。Codeは共通語ですよね❤️

ここではLanguage Translatorを例に説明します

3.1 まずはライブラリのインストール

以下のpipコマンドでインストールできます。

pip install --upgrade ibm-watson

3.2 インスタンスの作成

ほぼここのサンプルコード（example code）のコピーです。

ここのサンプルコードで例えば'{apikey}' と書かれていると、'{xxxxxxxxx}'(xxxxxxxxxは自分のapikey)とコードに書いてしまう方が、ハンズオンをやったりすると結構います。わかりにくいのですが、{ }は不要です。{apikey}ごと置き換えます。下記のコードは変数として最初に定義して{ }の記述は無くしました。

APIKEY='自分のAPIKEYを入れる'
URL='自分のURLを入れる'
VERSION='2018-05-01' #使いたいVersionを入れてください

from ibm_watson import LanguageTranslatorV3
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

authenticator = IAMAuthenticator(APIKEY)
language_translator = LanguageTranslatorV3(
    version=VERSION,
    authenticator=authenticator
)

language_translator.set_service_url(URL)

上記のVERSIONはAPIドキュメントの右側の「Versioning」をクリックすると、ドキュメントで想定しているVersionが記載されていますので、そちら値を使用するのがよいかと思います。

3.3 Methodの呼び出し

Language Translatorは翻訳サービスので、翻訳メソッド「Translate」を呼び出してみましょう。

呼び出し方法のMethod名、パラメータの内容などは基本3: 左側のメニューから使い方を知りたいSubjectをクリック。に書いたように、APIドキュメントの右側から知りたい内容をクリックすればサンプルコードと共に表示されます。

以下のコードを3.2 インスタンスの作成のコードの次に書きましょう。
model_id='en-es'なので、英語(en)からスペイン語(es)への翻訳となります。

translation = language_translator.translate(
    text='Hello, how are you today?',
    model_id='en-es').get_result()

language_translator.translate（）の戻り値にget_result()して何が戻ってくるかはAPIドキュメントの真ん中の列に書かれています。

また戻り値全体の話はAPIドキュメントのData Handling→Response detailsに載っています。get_result()以外に、Header情報やHTTP　Status　Codeを取得することが可能です。

結果を表示してみましょう.インデントをつけて見やすく表示させています:

import json

print(json.dumps(translation, indent=2, ensure_ascii=False))

表示されるもの:

{
  "translations": [
    {
      "translation": "Hola, ¿cómo estás hoy?"
    }
  ],
  "word_count": 7,
  "character_count": 25
}

翻訳結果だけ欲しい場合は以下のように指定します(辞書型になります)：

print (translation[ "translations"][0]["translation"])

表示されるもの:

Hola, ¿cómo estás hoy?

以上です。

4. 最後に

使い方のポイントを抑えれば、APIドキュメントが英語でも簡単にCodeがかけると思いますので、ぜひ他のAPIでも試してみてください！