7.1.8. groonga-suggest-httpd#
7.1.8.1. 概要#
groonga-suggest-httpd は次の機能に対するHTTPインターフェイスを提供するプログラムです。
サジェスト を実行した結果を返す
学習用にログを保存する
groonga-suggest-httpd は suggest コマンドのようなサジェスト機能を提供します。いくつかパラメーター名が異なることに注意してください。
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
true
> 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-httpdと groonga-suggest-learner のどちらも同じデータベースを使う
groonga-suggest-httpdが groonga-suggest-learner から学習したサジェストデータを受け取る
前者のケースでは、 groonga-suggest-httpd と groonga-suggest-learner を同じホスト上で実行しなければいけません。
後者のケースでは、 groonga-suggest-httpd と groonga-suggest-learner を違うホストで動かせます。
学習したサジェストデータをすぐに使う必要がないとき、 groonga-suggest-learner が使っているデータベースから groonga-suggest-httpd が使っているデータベースに学習したサジェストデータを主導で反映する必要があります。通常、こちらの使い方を推奨します。なぜなら学習したサジェストデータには悪意のあるユーザーが入力由来のゴミデータが含まれているかもしれないからです。
このドキュメントでは groonga-suggest-learner から学習したサジェストデータを受け取り、学習したサジェストデータをすぐに使います。 groonga-suggest-httpd と groonga-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-httpd は logYYYYmmddHHMMSS-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：クエリーの種類（complete、correct、suggestのどれか。複数指定も可。）
q：ユーザーの入力
suggest のパラメーターを指定することもできます。
以下は 補完 結果を取得する例です。この結果は前のセクションで学習したデータを使って計算しています。 frequency_threshold=1 パラメーターを使っているのはこれが例だからです。このパラメーターは1回以上出現した入力データも有効なデータとします。通常、プロダクション環境ではこのパラメーターを指定するべきではありません。ノイズが増える可能性が高いからです。
実行例:
$ curl 'http://localhost:8080/?n=query&t=complete&q=G&frequency_threshold=1'
{"complete":[[1],[["_key","ShortText"],["_score","Int32"]],["groonga",1]]}
補完用と学習用のどちらのパラメーターも指定することで補完と学習を組み合わせることができます。
実行例:
$ curl 'http://localhost:8080/?i=127.0.0.1&l=query&s=96000&q=G&n=query&t=complete&frequency_threshold=1'
{"complete":[[1],[["_key","ShortText"],["_score","Int32"]],["groonga",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パラメーターを受け付けます。
必須の引数があります。どれが必須かはクエリーの種類に依存します。
クエリーの種類が complete 、 correct 、 suggest のどれかのときは、道のパラメーターは suggest にそのまま渡します。つまり、 suggest のパラメーターを使うことができます。
7.1.8.5.1. 必須引数#
次のパラメーターを指定する必要があります。
キー |
説明 |
備考 |
|---|---|---|
|
ユーザーの入力。UTF-8でエンコードされた文字列です。 |
7.1.8.5.2. 学習時に必須の引数#
--send-endpoint を指定したときは次のパラメーターを指定しなければいけません。
キー |
説明 |
備考 |
|---|---|---|
|
|
単位はミリ秒。 |
|
各ユーザーを識別するユニークなID。 |
セッションID、IPアドレスなどを使うことができるでしょう。 |
|
1つ以上の学習対象のデータセット名。複数のデータセットを指定する場合は |
データセット名は groonga-suggest-create-dataset で指定した名前です。 |
7.1.8.5.3. サジェスト時に必須の引数#
t パラメータに complete 、 correct 、 suggest のどれかを指定したときは次のパラメーターを指定する必要があります。
キー |
説明 |
備考 |
|---|---|---|
|
サジェスト結果を計算するときに使うデータセット名。 |
データセット名は groonga-suggest-create-dataset で指定した名前です。 |
|
クエリーの種類。
|
複数の種類を指定することもできます。複数指定するときは |
7.1.8.5.4. 省略可能引数#
いくつか省略可能な引数があります。
キー |
説明 |
備考 |
|---|---|---|
|
JSONPの関数名 |
7.1.8.5.5. 学習時に指定可能な引数#
--send-endpoint オプションを指定したときに指定可能なパラメーターは次の通りです。
キー |
説明 |
備考 |
|---|---|---|
|
クエリーの種類。 指定可能な値は |
ユーザーが まだサブミットされていないユーザーの入力を指定するときは |
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]
],
...
}
t に submit を指定したときのレスポンスは次の通りです。:
{}
7.1.8.6.1. TYPE#
complete 、 correct 、 suggest のどれか。
7.1.8.6.2. CANDIDATE_N#
UTF-8でエンコードされた候補文字列。
7.1.8.6.3. SCORE_N#
候補のスコアー。
スコアーの降順でソートされた候補リスト。