7.1.8. groonga-suggest-httpd

7.1.8.1. 概要

groonga-suggest-httpd は次の機能に対するHTTPインターフェイスを提供するプログラムです。

  • サジェスト を実行した結果を返す

  • 学習用にログを保存する

groonga-suggest-httpdsuggest コマンドのようなサジェスト機能を提供します。いくつかパラメーター名が異なることに注意してください。

7.1.8.2. 構文

groonga-suggest-httpd にはデータベースのパスを指定します。:

groonga-suggest-httpd [options] DATABASE_PATH

7.1.8.3. 使い方

groonga-suggest-httpd を使う場合は1つ以上のデータセットを作る必要があります。データセットはテーブルとカラムの集まりです。これらのテーブル・カラムは groonga-suggest-create-dataset で作成できます。

ユーザーの入力からサジェスト用データを学習するには groonga-suggest-learner を使う必要があります。手動でサジェスト用データを作成する場合は groonga-suggest-learner を使う必要はありません。手動でサジェスト用データを作る方法については サジェスト とその関連ドキュメントを参照してください。

1つ以上のデータセットを作ったらHTTP経由で groonga-suggest-httpd を使えます。

つづくセクションでは次のことについて説明します。

  • データセットのセットアップ方法

  • groonga-suggest-learner と一緒に groonga-suggest-httpd を使う方法

  • サジェスト結果を取得するために groonga-suggest-httpd を使う方法

7.1.8.3.1. セットアップ

groonga-suggest-create-dataset でデータセットを作ります。

以下は query データセットを作る例です。

実行例:

% groonga-suggest-create-dataset ${DB_PATH} query
> plugin_register suggest/suggest
false
> table_create event_type TABLE_HASH_KEY ShortText
true
> table_create bigram TABLE_PAT_KEY ShortText --default_tokenizer TokenBigram --normalizer NormalizerAuto
true
> table_create kana TABLE_PAT_KEY ShortText --normalizer NormalizerAuto
true
> table_create item_query TABLE_PAT_KEY ShortText --default_tokenizer TokenDelimit --normalizer NormalizerAuto
true
> column_create bigram item_query_key COLUMN_INDEX|WITH_POSITION item_query _key
true
> column_create item_query kana COLUMN_VECTOR kana
true
> column_create kana item_query_kana COLUMN_INDEX item_query kana
true
> column_create item_query freq COLUMN_SCALAR Int32
true
> column_create item_query last COLUMN_SCALAR Time
true
> column_create item_query boost COLUMN_SCALAR Int32
true
> column_create item_query freq2 COLUMN_SCALAR Int32
true
> column_create item_query buzz COLUMN_SCALAR Int32
true
> table_create pair_query TABLE_HASH_KEY UInt64
true
> column_create pair_query pre COLUMN_SCALAR item_query
true
> column_create pair_query post COLUMN_SCALAR item_query
true
> column_create pair_query freq0 COLUMN_SCALAR Int32
true
> column_create pair_query freq1 COLUMN_SCALAR Int32
true
> column_create pair_query freq2 COLUMN_SCALAR Int32
true
> column_create item_query co COLUMN_INDEX pair_query pre
true
> table_create sequence_query TABLE_HASH_KEY ShortText
true
> table_create event_query TABLE_NO_KEY
true
> column_create sequence_query events COLUMN_VECTOR|RING_BUFFER event_query
true
> column_create event_query type COLUMN_SCALAR event_type
true
> column_create event_query time COLUMN_SCALAR Time
true
> column_create event_query item COLUMN_SCALAR item_query
true
> column_create event_query sequence COLUMN_SCALAR sequence_query
true
> table_create configuration TABLE_HASH_KEY ShortText
true
> column_create configuration weight COLUMN_SCALAR UInt32
true
> load --table configuration
> [
> {"_key": "query", "weight": 1}
> ]
1

groonga-suggest-create-dataset は実行したコマンドを出力します。新しいデータセット用にどんなテーブル・カラムを作ったかを確認できます。

7.1.8.3.2. groonga-suggest-learner を起動

学習したサジェストデータをすぐに使うかどうかを選択できます。

学習したサジェストデータをすぐに使う方法は2つあります。

前者のケースでは、 groonga-suggest-httpdgroonga-suggest-learner を同じホスト上で実行しなければいけません。

後者のケースでは、 groonga-suggest-httpdgroonga-suggest-learner を違うホストで動かせます。

学習したサジェストデータをすぐに使う必要がないとき、 groonga-suggest-learner が使っているデータベースから groonga-suggest-httpd が使っているデータベースに学習したサジェストデータを主導で反映する必要があります。通常、こちらの使い方を推奨します。なぜなら学習したサジェストデータには悪意のあるユーザーが入力由来のゴミデータが含まれているかもしれないからです。

このドキュメントでは groonga-suggest-learner から学習したサジェストデータを受け取り、学習したサジェストデータをすぐに使います。 groonga-suggest-httpdgroonga-suggest-learner はどちらも同じホストで動かします。これは説明しやすいからです。

以下は groonga-suggest-learner を起動する例です。 query データセットがあるデータベースを指定します。このドキュメントでは query データセットを作る手順は省略します。

実行例:

% groonga-suggest-learner --daemon ${DB_PATH}

groonga-suggest-learner プロセスは2つのエンドポイントを提供します。それぞれ 1234 番ポートと 1235 番ポートを使います。

  • 1234 番ポート: groonga-suggest-httpd からユーザーの入力を受け付けるエンドポイント

  • 1235 番ポート: groonga-suggest-httpd に学習したサジェストデータを送信するエンドポイント

7.1.8.3.3. groonga-suggest-httpd を起動

次の目的のため、 groonga-suggest-httpd を起動します。

  • ユーザーの入力からサジェストデータを学習するため

  • サジェスト結果をクライアントに提供するため

以下は groonga-suggest-learner と通信する groonga-suggest-httpd を起動する例です。

実行例:

% groonga-suggest-httpd --send-endpoint 'tcp://127.0.0.1:1234' --receive-endpoint 'tcp://127.0.0.1:1235' --daemon ${DB_PATH}

groonga-suggest-httpd プロセスは 8080 番ポートでHTTPリクエストを受け付けます。

リクエストをログファイルに保存したい場合は --log-base-path オプションを指定してください。

以下は各ログファイルに log というプレフィックスをつけて logs ディレクトリーに保存する例です。:

% groonga-suggest-httpd --log-base-path logs/log ${DB_PATH}

groonga-suggest-httpdlogYYYYmmddHHMMSS-00 という名前のログファイルを作成し、 logs ディレクトリー以下に保存します。

7.1.8.3.4. ユーザーの入力から学習

ユーザーの入力からサジェストデータを学習できます。

サジェストデータを学習するには次のパラメーターを指定する必要があります。

  • i: The ID of the user (You may use IP address of client)

  • l :データセット名

  • s :入力のタイムスタンプ。単位は秒。

  • t :クエリーの種類。(省略可能。ユーザーの入力がサブミットされたときだけ submit を指定します。)

  • q :ユーザーの入力

以下は query データセットで「Groonga」というユーザーの入力を学習するリクエスト例です。

.. groonga-command
.. include:: ../../example/reference/executables/groonga-suggest-httpd/learn.log
.. % curl 'http://localhost:8080/?i=127.0.0.1&l=query&s=92619&q=G'
.. % curl 'http://localhost:8080/?i=127.0.0.1&l=query&s=93850&q=Gr'
.. % curl 'http://localhost:8080/?i=127.0.0.1&l=query&s=94293&q=Gro'
.. % curl 'http://localhost:8080/?i=127.0.0.1&l=query&s=94734&q=Groo'
.. % curl 'http://localhost:8080/?i=127.0.0.1&l=query&s=95147&q=Grooon'
.. % curl 'http://localhost:8080/?i=127.0.0.1&l=query&s=95553&q=Groonga'
.. % curl 'http://localhost:8080/?i=127.0.0.1&l=query&s=95959&t=submit&q=Groonga'

入力中のデータに t=submit パラメーターをつけてはいけません。上の例では、ユーザーの入力を学習しているだけですが、ユーザーの入力を学習しながら同時に補完候補を取得することもできます。これは次のセクションで説明します。

サブミットされたデータには t=submit パラメーターをつけます。

7.1.8.3.5. サジェスト結果を使う

groonga-suggest-httpd からのサジェスト結果を使えます。

サジェスト結果を取得するには次のパラメーターを指定します。

  • n :データセット名

  • t :クエリーの種類( completecorrectsuggest のどれか。複数指定も可。)

  • q :ユーザーの入力

suggest のパラメーターを指定することもできます。

以下は 補完 結果を取得する例です。この結果は前のセクションで学習したデータを使って計算しています。 frequency_threshold=1 パラメーターを使っているのはこれが例だからです。このパラメーターは1回以上出現した入力データも有効なデータとします。通常、プロダクション環境ではこのパラメーターを指定するべきではありません。ノイズが増える可能性が高いからです。

実行例:

% curl 'http://localhost:8080/?n=query&t=complete&q=G&frequency_threshold=1'

補完用と学習用のどちらのパラメーターも指定することで補完と学習を組み合わせることができます。

実行例:

% curl 'http://localhost:8080/?i=127.0.0.1&l=query&s=96000&q=G&n=query&t=complete&frequency_threshold=1'

7.1.8.4. コマンドライン引数

7.1.8.4.1. 必須引数

必須の引数は1つです。

7.1.8.4.1.1. DATABASE_PATH

Groongaのデータベースのパスを指定します。このデータベースには1つ以上のデータセットを作っておいてください。各データセットは groonga-suggest-create-dataset で作ります。

7.1.8.4.2. 省略可能引数

-p, --port

HTTPサーバーのポート番号を指定します。

デフォルトのポート番号は 8080 です。

-t, --n-threads

最大スレッド数を指定します。

最大で128を指定できますが、パフォーマンスを出すためには最大でもCPUコア数を指定する方がよいです。

デフォルトはコア数です。

-s, --send-endpoint

ユーザーの入力送信先になる groonga-suggest-learner のエンドポイントURIを指定します。

フォーマットは tcp://${HOST}:${PORT} です。たとえば、 tcp://192.168.0.1:2929 のように指定します。

デフォルト値はありません。

-r, --receive-endpoint

groonga-suggest-learner が学習済みのサジェストデータを受信するために使用するURIを指定します。

フォーマットは tcp://${HOST}:${PORT} です。たとえば、 tcp://192.168.0.1:2929 のように指定します。

デフォルト値はありません。

-l, --log-base-path

ログのパス名のプレフィックスを指定します。

デフォルト値はありません。

--n-lines-per-log-file

1つのログファイルの最大行数を指定します。

デフォルトは 1000000 (100万行)です。

-d, --daemon

デーモン化する場合に指定します。

デフォルトではデーモン化しません。

--disable-max-fd-check

起動時の最大ファイルディスクリプター数のチェックを無効化する場合に指定します。

デフォルトはチェックします。

7.1.8.5. GETの引数

groonga-suggest-httpd GETパラメーターを受け付けます。

必須の引数があります。どれが必須かはクエリーの種類に依存します。

クエリーの種類が completecorrectsuggest のどれかのときは、道のパラメーターは suggest にそのまま渡します。つまり、 suggest のパラメーターを使うことができます。

7.1.8.5.1. 必須引数

次のパラメーターを指定する必要があります。

キー

説明

備考

q

ユーザーの入力。UTF-8でエンコードされた文字列です。

7.1.8.5.2. 学習時に必須の引数

--send-endpoint を指定したときは次のパラメーターを指定しなければいけません。

キー

説明

備考

s

1970-01-01T00:00:00Z から経過時間。

単位はミリ秒。

i

各ユーザーを識別するユニークなID。

セッションID、IPアドレスなどを使うことができるでしょう。

l

1つ以上の学習対象のデータセット名。複数のデータセットを指定する場合は dataset1|dataset2|dataset3 のように区切り文字として | を使います。

データセット名は groonga-suggest-create-dataset で指定した名前です。

7.1.8.5.3. サジェスト時に必須の引数

t パラメータに completecorrectsuggest のどれかを指定したときは次のパラメーターを指定する必要があります。

キー

説明

備考

n

サジェスト結果を計算するときに使うデータセット名。

データセット名は groonga-suggest-create-dataset で指定した名前です。

t

クエリーの種類。

completecorrectsuggest のどれか。

複数の種類を指定することもできます。複数指定するときは complete|correct のように | で区切ってください。

7.1.8.5.4. 省略可能引数

いくつか省略可能な引数があります。

キー

説明

備考

callback

JSONPの関数名

7.1.8.5.5. 学習時に指定可能な引数

--send-endpoint オプションを指定したときに指定可能なパラメーターは次の通りです。

キー

説明

備考

t

クエリーの種類。

指定可能な値は submit だけです。

ユーザーが q で指定した入力をサブミットしたときは submit を指定してください。

まだサブミットされていないユーザーの入力を指定するときは submit を指定しないでください。 submit を指定していないときに tcompletecorrectsuggest のうち1つ以上を指定するとサジェスト結果を使えます。これらの t に指定する値については サジェスト時に必須の引数 を参照してください。

7.1.8.6. 戻り値

groonga-suggest-httpd のレスポンスは次のフォーマットになります。 suggest のボディ部分と同じです。:

{
  TYPE1: [
    [CANDIDATE_1, SCORE_1],
    [CANDIDATE_2, SCORE_2],
    ...,
    [CANDIDATE_N, SCORE_N]
  ],
  TYPE2: [
    [CANDIDATE_1, SCORE_1],
    [CANDIDATE_2, SCORE_2],
    ...,
    [CANDIDATE_N, SCORE_N]
  ],
  ...
}

tsubmit を指定したときのレスポンスは次の通りです。:

{}

7.1.8.6.1. TYPE

completecorrectsuggest のどれか。

7.1.8.6.2. CANDIDATE_N

UTF-8でエンコードされた候補文字列。

7.1.8.6.3. SCORE_N

候補のスコアー。

スコアーの降順でソートされた候補リスト。

7.1.8.7. 参考