How to use

BazilのRubyClientの使い方

1. 準備

   Bazilのサービスに安全に利用するため、RubyClientはSSLを用いて接続を行います。 そのため、環境によってはグローバルサインのルート証明書をご用意していただく必要がございます。 https://jp.globalsign.com/repository/index.html#cer のリンクから「ルート証明書(R1)」をダウンロードしていただき、RubyClientを動かすマシンに保存してください。

   また、RubyClientはAPIキーを用いて認証を行います。 BazilのWebページにログインし、 https://asp-bazil.preferred.jp/api_keys からAPIキーをご確認下さい。 APIキーが存在しない、あるいはAPIキーを削除してしまった場合にはCreate a new keyボタンで生成することができます。

   このAPIキーはBazilの認証に使うため、万が一APIが第三者に知られてしまった場合、すみやかに対象のAPIキーを削除し、作り直してください。 その場合、RubyClientを使っているコードのAPIキーも書き直す必要があります。

2. クライアントの作成

   Bazilのサービスに接続するため、クライアントを作成します。

   require "bazil"
   
   cli = Bazil::Client.new
   
   # 環境によってはSSL証明書の指定が必要になることがあります。
   # 先ほどダウンロードしていただいたSSL証明書をca_fileに絶対パスで記述してください。
   # cli = Bazil::Client.new(ca_file: "/home/bazil/rootcacert.cer")
   

   認証のため、APIキーを指定します。 APIキーは、ファイルに保存する方法と、コード中に記述する方法があります。

   1. ファイルに保存する方法

      WebUIで確認したAPIキーをファイルに保存します。 APIキーを記述するファイルは、RubyClientを動かしているディレクトリ(カレントディレクトリ)、もしくは、ホームディレクトリに、「.bazil」という名前のディレクトリを作り、その中に「api_keys」という名前で保存します。 ファイルの形式は以下の様になります。

      {
        "api_key": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
        "secret_key": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
      }
      

      また、このファイルを別の場所に保存し、Bazil::Client#newのオプションでファイル名を指定することもできます。

      cli = Bazil::Client.new(api_keys: '/path/to/your/api_keys')
      

      これらのAPIキーファイルの優先度は、Bazil::Client#newのオプション、カレントディレクトリ、ホームディレクトリの順になります。

   2. コード中で指定する方法。

      Bazil::Client#set_api_keysの第一引数にAPI key、第二引数にSecret keyを設定します。

      cli.set_api_keys('XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX', 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
      

   これでRubyからBazilを利用する準備が整いました。

3. モデルの取得

   設定をしたクライアントを使ってモデルを取得することができます。

   # Bazil::Client#models はアクセスすることのできるすべてのモデルとコンフィグの組み合わせを返します。
   models = cli.models
   # => [#<Bazil::Model:0x0000000263cef8 @client=#<Bazil::Client:0x000000025d57f8 @http_cli=#<Bazil::REST:0x000000025d4d30 @http=#<Net::HTTP asp]
   
   models.size
   # => 1
   
   model = models[0]
   # => #<Bazil::Model:0x00000002349868 @client=#<Bazil::Client:0x000000025d57f8 @http_cli=#<Bazil::REST:0x000000025d4d30 @http=#<Net::HTTP asp->
   
   # モデルIDとコンフィグIDの取得
   model.model_id
   # => 4
   model.config_id
   # => 7
   
   # モデルIDとコンフィグIDはWebUIのURLからも確認することが出来ます。
   # 操作したい対象のモデルのコンフィグを選択したさいのURLは
   # https://asp-bazil.preferred.jp/models/(モデルID)/configs/(コンフィグID)
   # となっています。
   # WebUIから確認したモデルIDとコンフィグIDを使い、任意のモデルを取得することができます。
   model = cli.model(4,7)
   

4. モデルを使って分類をする

   取得したモデルを使って分類をすることができます。 ここでは非常に単純な名前から性別を判定するモデルを対象に分類を行っています。

   result = model.query({content: "綾 子"})
   # => {"score"=>{"男"=>-0.289951503277, "女"=>0.289951503277}, "classification_result"=>"女"}
   
   # Bazilが判定したラベルがclassification_resultに、それぞれのラベルのスコアがscoreに格納されています。
   result["classification_result"]
   # => "女"
   result["score"]
   # => {"男"=>-0.289951503277, "女"=>0.289951503277}
   

   model.trace の結果も取得できます。どの特徴がどのくらいの重みになっているのかが返ってきます。

   # 
   result = model.trace('feature_weights', {content: "綾 子"})
   

5. モデルに正解データを追加する

   正解データの登録はWebUIからCSVで行うことも出来ますが、RubyClientからも可能になっています。

   model.train(annotation: '男', data: {'content' => '裕 也'})
   # => {"training_data_id"=>5251}