Google Prediction API --Hello Prediction!--

元ネタ：http://code.google.com/apis/predict/docs/hello_world.html

このページは、PredictionAPIを15分程度で、とりあえず使ってみるサンプルを紹介します。
とりあえずこのサンプルを試したあとに、他のドキュメントを読むとよいでしょう。

Prerequisites　前提条件

• Getting StartedページのPrerequisitesを満たしていることを確認してください。
• このサンプルを実行するために、Google Storageへのファイルのアップロード方法をマスターしておいてください。

The Problem　解決課題

あなたの会社では、電子メールで複数の言語での問い合わせを受け付けていると考えてください。
そしてあなたは、該当する言語の担当者に、電子メールを振り分けなければなりません。
つまりここでの問題は、与えられたテキストが英語なのかスペイン語なのかフランス語なのか判別する、ということになります。

これをするためにあなたは、予測エンジンに学習させるための学習データを作成する必要があります。
一つの学習データは、いくつかのテキストで構成されており、そのテキストの言語を表す、「英語」「スペイン語」「フランス語」のいずれかのラベルが振られているものとします。

学習の後に、任意の言葉や文章を与えると、予測エンジンはそれを上記の言語のうち一番近いものに分類します。

The Solution　解法

Hello Predictionを行う処理の流れは以下のようになります。

１．認証トークンの取得

PredictionAPIへのリクエストは、すべて認証されている必要があります。 APIはOAuth認証をサポートします。このサンプルでは、OAuthに対応したoacurlコマンドラインツールを使います。最初にトークンをリクエストし、その後のリクエストには、すべてトークンを含める必要があります。

２．学習データのアップロード

Google Storageに、英語、スペイン語、フランス語を含んだ学習データをアップロードします。 Google Storageにアップロードしたデータのbucket名やオブジェクト名は、学習モデルの一意識別子として使われます。 Prediction APIのリクエストは、この一意識別子により、学習モデルを指定する必要があります。

３．学習

Prediction APIに、学習データを読み込んで学習するように指示します。 この処理は非同期に行われるため、定期的にサーバーに問い合わせを行って、学習の状態を調べる必要があります。 学習に基づく予測問い合わせを行う前に、学習は完了していなければなりません。

４．問い合わせの実行

学習の完了後、単語や文章を含んだクエリをサーバーに送信し、サーバーから、そのテキストに対応した言語を受け取ります。 このステップは何回でも実行できます。

このサンプルでは、oacurlコマンドラインツールと、リクエスト送信用のヘルパースクリプトを使用します。
oacurlのヘルパースクリプトは、ライブラリのページにあります。（スクリプトの使い方や、注意点を解説しています。）

oacurlはここからダウンロード

１．認証トークンの取得
oacurlを使用した認証を行う際、インターネットにアクセスでき、ブラウザが使用可能である必要があります。
ダウンロードしたoacurlのjarファイルを置いたディレクトリに移動し、以下のコマンドを実行してください。
このコマンドはブラウザを立ち上げ、Googleアカウントのログインページを表示します。
ログインの後、oacurlがあなたのGoogleアカウントでPrediction APIにアクセスすることを許可するかどうかを聞いてきます。
Prediction APIをアクティブにしたGoogleアカウントでログインすることを忘れないでください。

$ java -cp oacurl-1.2.0.jar com.google.oacurl.Login --scope https://www.googleapis.com/auth/prediction

※このコマンドにより取得したトークンには長めのライフタイムがあり、セッションの最初に一度実行すればOKです。
もし、セッションの途中で認証エラーが発生した場合は、もう一度このコマンドを実行し、再度トークンを取得してください。

２．学習データのアップロード

この学習ファイルをダウンロードしてください。
これは、英語とスペイン語とフランス語の学習データを含んでいます。
学習ファイルのフォーマットは、カンマ区切りのテキストファイルで、２つのカラムと、多数のレコードからなります。
2つ目のカラムは、一つの言語に対するサンプルテキストです。
1つ目のカラムは、サンプルテキストの言語を表すラベル名です。
学習ファイルを開いて、中身を見てみてください。

学習ファイルをGoogle Storage Bucketにコピーしてください。
このサンプルでは、「examplebucket」というbucketを使っていますが、あなた自身のbucketに読み替えてください。
（bucket名は他ユーザーとの間でもユニークでなければならない。）
オブジェクト名については、好きな名前にすることができます。オリジナルの学習ファイルと同じにする必要はありません。

$ gsutil cp ./language_id.txt gs://examplebucket/prediction_models/languages
$ gsutil ls gs://examplebucket
gs://examplebucket/prediction_models/languages

３．学習
次のステップはシステムに学習させることです。
そのためには、先ほどアップロードした学習ファイルのbucket/objectを指定したPOSTリクエストをサーバーに送信します。
リクエストの送信後、学習が完了するまでポーリングします。

このサンプルでは、oauth-train.shと、oauth-check-training.shという、ヘルパースクリプトを使います。
これらのスクリプトファイルをローカルにコピーして、以下のように実行してください。

この学習は、1分以内に終了するはずです。もしそれ以上かかるようなら、障害が発生している可能性が高いです。
学習データをGoogle Storageにアップロードしたか、また、スクリプト実行の際にGoogle Storageのbucket/objectを正しく指定したかを確認してください。
なお、スクリプトを実行する際、gs:// は不要です。

$ ./oauth-train.sh examplebucket/prediction_models/languages
{
 "kind": "prediction#training",
 "id": "examplebucket/prediction_models/languages",
 "selfLink": "https://www.googleapis.com/prediction/v1.2/training/examplebucket/prediction_models/languages"
}

$ ./oauth-check-training.sh examplebucket/prediction_models/languages
{
 "kind": "prediction#training",
 "id": "examplebucket/prediction_models/languages",
 "selfLink": "https://www.googleapis.com/prediction/v1.2/training/examplebucket/prediction_models/languages",
 "modelInfo": {
  "modelType": "classification",
  "classificationAccuracy": 0.95
 },
 "trainingStatus": "DONE"
}

４．問い合わせの実行
学習が完了すれば、サーバーに問い合わせを送信し、予測させることができるようになります。
oauth-predict.shスクリプトファイルをダウンロードし、以下のコマンドを実行して、"muy bueno"が、フランス語、スペイン語、英語のうち、どれに一番近いと判断されるか試してください。

$ ./oauth-predict.sh examplebucket/prediction_models/languages "\"muy bueno\""
{
 "kind": "prediction#output",
 "id": "examplebucket/prediction_models/languages",
 "selfLink": "https://www.googleapis.com/prediction/v1.2/training/examplebucket/prediction_models/languages/predict",
 "outputLabel": "Spanish",
 "outputMulti": [
  {
   "label": "French",
   "score": 0.334130
  },
  {
   "label": "Spanish",
   "score": 0.418339
  },
  {
   "label": "English",
   "score": 0.247531
  }
 ]
}

スコアが最大のものが、一番近いと判断されたもので、それは"outputLabel"で示されているスペイン語となります。

Google Prediction API --Getting Started--

元ネタ：http://code.google.com/apis/predict/docs/getting-started.html

このページでは、Google Prediction API について、それが何なのか、どのように使うのか、さらに詳しいドキュメントのありかについて説明します。

Introduction　導入

このドキュメントは、わずか数分でAPIを試せる、Hello World アプリケーションを含んでいます。
また、APIを使用した、完全なwebサイトの例も2件示します。
1つはスパム検出を行うwebサイトであり、もう１つは、ユーザーの動画の閲覧履歴に基づいて、お勧め動画を提案するwebサイトです。

What Can the Prediction API Do?　Prediction APIでなにができるの？

Prediction APIは、パターンマッチングと、機械学習の機能を実現します。
与えられた学習データのセットから、以下のような機能を実現するアプリケーションを作ることができます。

• ユーザーの過去の閲覧履歴から、そのユーザーの嗜好に合った動画や製品を予測します。
• メールを、スパムかどうか判断します。
• 製品レビューが、マイナス評価であるか、プラス評価であるかを分析します。
• ユーザーの今までの製品の利用履歴から、特定の日にどのぐらいの時間製品を利用するかを予測します。

Prerequisites　必要なもの

• Googleアカウントが必要です。
• APIs Console projectで、Google Prediction APIと、Google Storage for Developers APIをアクティブにする必要があります。

Questions, Feedback, and Notifications　質問、フィードバック、通知

Prediction API コミュニティに参加する方法は以下の通りです。

• 質問やディスカッションは、prediction-api-discuss フォーラム
• 新バージョンリリースの通知や、新しい機能、サービスの通知は、prediction-api-announce フォーラム
• 新しい機能の提案や、フィードバックやバグ情報は、Suggestions, Feedback, and Bugs ページ

Recommended Reading Order　ドキュメントはこの順に読むとよいです

1. Hello World アプリケーションで、APIを試してください
2. デベロッパガイドや、リファレンスを読んで、APIの使い方を学んでください。
3. 料金と利用規約のページで、無料でできることと、料金を確認してください。
4. 現実世界におけるソリューションの一通りのコーディング例として、example アプリケーションを見てください。
5. APIを様々な言語から使用するための、helper ライブラリをみてください。

Google Prediction API --Libraries and Sample Code--

元ネタ：http://code.google.com/apis/predict/docs/libraries.html#oacurltraining

このページでは、いくつかの言語からPrediction APIを使うためのヘルパーライブラリを紹介します。
また、よくあるシナリオでAPIを使用するアプリケーションのサンプルを提示します。

Generic Google API Client Libraries

ここでは、Google Prediction APIにアクセスするための一般的なREST形式のAPIを紹介します。
以下の表で、1列目に現在の開発段階を示しています。アルファ版のものもあることに注意してください。
各言語のサンプルも提示していますが、中にはまだサンプルがないものもあります。
必要に応じて他の言語のサンプルを参考にしてください。

Client library	Public repository	All client library samples
Google APIs Client Library for .NET (alpha)	google-api-dotnet-client/	.NET samples
Google API Libraries for Google Web Toolkit (alpha)	gwt-google-apis/	GWT samples
Google APIs Client Library for Java (beta)	google-api-java-client/	Java samples
Google APIs Client Library for PHP (alpha)	google-api-php-client/	PHP samples
Google APIs Client Library for Python (beta)	google-api-python-client/	Python samples
Google APIs Client Library for Ruby (alpha)	google-api-ruby-client/	Ruby samples

Specialized Google Prediction API Client Libraries

ここでは、Google Prediction API用に作られたAPIについて紹介します。

Language	Library Name	Link to the Repository
.NET	.NET Prediction API library	http://gpapi.codeplex.com/
BASH script	oacurl	See the scripts below
Java	Prediction API Java library	http://code.google.com/p/google-api-java-client/wiki/APILibraries#Prediction_API
JavaScript (Experimental)	Google Prediction API Javascript Library	Library source is available at https://ajax.googleapis.com/ajax/libs/googleapis/prediction-0.0.1/prediction.js. See information below.
PHP	PHP Prediction API library	http://code.google.com/p/predictionapiphpwrapper/source/browse/trunk/GooglePredictionWrapper.php
R	Google Prediction Client Library for R	http://code.google.com/p/google-prediction-api-r-client/
Ruby	Open-source Prediction API client	http://code.google.com/p/ruby-google-prediction-api/
Ruby	RubyForge Prediction API client	http://rubyforge.org/projects/google-predict/

JavaScript Library (Experimental)　--省略--

BASH Using oacurl

注意：oacurlは、現在、OAuth1.0のみサポートしています。

oacurlは、OAuth認証に対応したHTTPリクエストをサポートする、オープンソースのコマンドラインツールです。

製品として販売するようなコードでoacurlを使用することは勧められませんが、
テストやデバックを手っ取り早く実行するときは便利です。

このセクションでは、Predicton APIのREST呼び出しにoacurlを使用したスクリプトを紹介します。

ここから最新バージョンのoacurlを入手してください。

認証トークンの取得
Prediction APIの最初のステップは、OAuth認証トークンの取得です。
以下のスクリプトは認証トークンを要求するリクエストを生成します。
このスクリプトはブラウザを立ち上げ、Googleの認証ページを開きます。
ブラウザに表示されたページで、GoogleアカウントのIDとパスワードを入力します。
するとブラウザは、oacurlにあなたのPrediction APIアカウントにアクセスするための認証トークンを返します。
oacurlがあなたのIDとパスワードを見たり受け取ったりすることはありません。

上記の認証プロセスを実行する際に、oacurlにブラウザを起動させるかそれとも自分でブラウザを立ち上げるか選択することができます。
もし自分で立ち上げることを選んだ場合、Googleアカウントのログインページを開くためのURLを受け取ります。
自分で立ち上げる場合は、 --nobrowser フラグをつけてコマンドを実行してください。

以下のコマンドは、oacurlを使ってOAuth認証を行うコマンドです。
oacurlのJARファイルは、ダウンロードしたローカルファイルを指すように変更してください。

$ java -cp oacurl-1.2.0.jar com.google.oacurl.Login --scope https://www.googleapis.com/auth/prediction

認証トークンの有効期限は長いので、認証は一度行えばOKです。
認証後は、oacurlはトークンを見つけると自動的にそれをリクエストに含めますので、
認証について特に気にする必要はありません。


学習
oauth-train.sh

#!/bin/bash
# Train a prediction model.
# Usage: oauth-train.sh MODEL_NAME

ID=$1
KEY=`cat googlekey`

post_data="{\"id\":\"$ID\"}"

# Train the model.
java -cp ./oacurl-1.2.0.jar com.google.oacurl.Fetch -X POST \
-t JSON \
"https://www.googleapis.com/prediction/v1.3/training?key=$KEY" <<< $post_data
echo

このスクリプトは、Google Storageにアップロードした学習データを使っての学習を行います。

注意：このスクリプトを実行する際には、Google Storageのアクセスキーを"googlekey"という名前のファイルに保存して、スクリプトからアクセス可能な場所に置いておく必要があります。 「アクセスキー」は、Google APIs Consoleから取得できます。

このスクリプトは、以下のように使用します。

$ oauth-train.sh mybucket/myobject

学習状態の取得
oauth-check-training.sh

#!/bin/bash
# Check training status of a prediction model.
# Usage: oauth-training.sh MODEL_NAME

DATA=$1
KEY=`cat googlekey`

# Encode the model name.
MODEL=`echo $DATA | perl -pe 's:/:%2F:g'`

# Check training status.
java -cp ./oacurl-1.2.0.jar com.google.oacurl.Fetch -X GET \
  "https://www.googleapis.com/prediction/v1.3/training/$MODEL?key=$KEY"
echo

このスクリプトは、モデルの学習状態をチェックします。
このスクリプトも、Google Storageのアクセスキーを"googlekey"という名前のファイルに保存して、アクセス可能な場所に置いておく必要があります。

問い合わせの実行
oauth-predict.sh

#!/bin/bash

# Run a prediction against a model.
# Usage: oauth-predict.sh MODEL_NAME DATA

DATA=$1
INPUT="$2"
KEY=`cat googlekey`
MODEL=`echo $DATA | perl -pe 's:/:%2F:g'`
data="{\"input\" : { \"csvInstance\" : [ $INPUT ]}}"

java -cp ./oacurl-1.2.0.jar com.google.oacurl.Fetch -X POST \
-t JSON \
"https://www.googleapis.com/prediction/v1.3/training/$MODEL/predict?key=$KEY" <<< $data
echo

このスクリプトは判断のリクエストを送信します。 このスクリプトは、複数のテキストや数値の列を処理します。 このスクリプトも、Google Storageのアクセスキーを"googlekey"という名前のファイルに保存して、アクセス可能な場所に置いておく必要があります。

$ oauth-predict.sh mybucket/myobject "col1, col2 ..."

データリストは、全体をダブルクォーテーション（"）で囲む必要があります。 そして、カラムごとにカンマで区切ります。 カラムが文字列データの場合、さらにシングルクォーテンション('）で囲む必要があります。 カラムが数値データの場合は、クォーテーションは不要です。 以下にいくつか例を示します。

oauth-predict.sh example/bucket "'some string data', 'singleval', 123 "
oauth-predict.sh example/bucket "1234, 'Man\'s best friend' "
oauth-predict.sh example/bucket "1234, 3345" # Numerical data does not need additional quotes.