Skip to main content
xgboost (XGBOOST) 辞書 は、ロード時に学習用の行を格納したソーステーブルから XGBoost の勾配ブースティングモデルを学習し、入力された任意の特徴量ベクトルに対して数値の目的変数を予測します。特徴量カラムが辞書キーとなり、単一の属性がモデルの学習対象となる目的変数になります。 特徴量が数値である表形式データの回帰や二値分類に適しています。たとえば、複数の測定値から値を予測する、学習済みの目的変数に基づいて行をスコアリングする、といった用途が挙げられます。多クラス分類の目的関数はサポートされていません (レイアウトのパラメータを参照) 。
XGBoost インテグレーションは実験的機能です。XGBOOST 辞書 を作成する前、または predictXGBoost を呼び出す前に、enable_xgboost 設定で有効化してください。
サポートされているのは CREATE DICTIONARY のみです。サーバー設定ファイルで定義した XGBOOST 辞書 はロードに失敗します。
この 辞書 をクエリする唯一の方法は predictXGBoost です。この関数は特徴量を個別の引数として受け取って予測を返し、追加の予測パラメータも指定できます。この 辞書 は行ではなく学習済みモデルを保持するため、汎用的な辞書インターフェイス (dictGet、dictHas、SELECT * FROM dict) はサポートされておらず、使用するとエラーになります。

クイックスタート

ここでは、線形の目的変数 y = 2*x1 + 3*x2 を対象に回帰モデルを学習させます。 1. 学習データの行を格納するソーステーブルを作成します。カラムは特徴量を先に並べ、最後に目的変数を配置します。
2. 学習データを挿入する:
3. XGBOOST レイアウトで 辞書 を作成します。特徴量カラムをキーとし、y をターゲット属性とします:
PRIMARY KEY (x1, x2) により、x1 と x2 が特徴量になります。モデルが学習する目的変数は y で、キーに含まれない唯一のカラムとして推論されます。LAYOUT 内のパラメータは XGBoost のハイパーパラメータです (レイアウトのパラメータ を参照) 。 4. 予測 — predictXGBoost は特徴量を位置順に受け取り、予測値を返します。
真の値は 2*1 + 3*2 = 8 なので、モデルの予測は 8 に近い値になります。

仕組み

学習 (ロード時) 。 ソースの各行は (features..., target) という 1 件の観測値です。辞書 のロード時にソースはブロック単位で読み込まれ、その後、データ全体を対象にモデルが 1 回だけ学習されます。特徴量と目的変数の値は浮動小数点数として読み込まれるため、キーカラムは数値型、ターゲット属性は floating-point 型である必要があります (辞書 の構造を参照) 。
学習時には学習データ全体がメモリ上に保持されます。 ソースをブロック単位で読み込んでも、アウトオブコア学習にはなりません。各ブロックは消費されずに蓄積されるため、学習データ全体は最初のブースティングラウンドの前にメモリに常駐し、最後のラウンドが終わるまで常駐し続けます。
予測 (クエリ実行時) 。 予測時、モデルはキーカラムの宣言順に並んだ特徴量ベクトルを受け取り、学習済みのブースターで評価して Float64 を返します。NULL の特徴量は欠損値としてモデルに渡され、XGBoost が学習時に習得した方法で処理するため、予測が NULL になることはありません。すべての特徴量が定数の場合、モデルは行ごとではなくブロックごとに 1 回だけ評価されます。 モデルは永続化されません。 モデルは 辞書 がロードされている間だけメモリ上に存在し、ロードのたびに (サーバー再起動後も含めて) ソースから再学習されます。 モデルの再学習。 ロードのたびにスクラッチから学習されるため、SYSTEM RELOAD DICTIONARY を実行すると、ソーステーブルの現在の内容でモデルが再学習されます。
LIFETIME を 0 以外に設定した場合も再学習が行われます。存続期間の経過によってトリガーされた再読み込みは、通常の読み込みと同じように扱われるためです。学習データの増加に合わせてモデルを定期的にリフレッシュしたい場合は、この設定を使用してください。

辞書 の構造

XGBOOST 辞書 の形状は固定されています。
  • PRIMARY KEY は、ネイティブの数値型(整数および浮動小数点数)の 1 つ以上のカラムで構成され、これが特徴量となります。クエリ実行時、この「キー」は予測時に渡す特徴量ベクトルを指し、保存済みのルックアップキーではありません。特徴量の順序はキーカラムの宣言順に従い、predictXGBoost は位置引数をこの順序でバインドします。
  • これらに加えて、Float32 または Float64 型の属性を 1 つだけ宣言します。これがモデルの学習対象となる目的変数です。この属性は常に、特徴量キーに含まれない唯一のカラムとして推論されます。目的変数を指定するパラメータはなく、属性を 2 つ以上宣言するとエラーになります。
これらの要件を満たさないカラムは、辞書 の作成時ではなく、読み込み時に拒否されます。

レイアウトのパラメータ

指定できるのは以下のパラメータのみです。それ以外の名前を指定するとロードに失敗するため、タイプミスが黙って無視されることはなく、モデルの学習時に検出されます。num_iterations は ClickHouse 側で処理されます (説明を参照)。それ以外のパラメータはすべて文字列としてそのまま XGBoost ブースターに転送され、XGBoost 自体のデフォルト値と値の範囲が適用されます。詳しくは XGBoost パラメータリファレンス を参照してください。 パラメータ名は大文字と小文字を区別せず、各パラメータは 1 回しか指定できません。値には正の整数、浮動小数点数、または引用符で囲んだ文字列を指定する必要があります。負のリテラルはレイアウトに渡される前に 辞書 の DDL 自体で拒否されるため、負の seed は指定できません。 例えば、ステップサイズ eta もあわせて設定する 辞書 は次のようになります。

予測パラメータ

predictXGBoost は、特徴量に続く末尾の任意引数として、map で構築した XGBoost 予測パラメータの定数 Map を受け取ります。
パラメータ名は、XGBoost の XGBoosterPredictFromDMatrix の予測パラメータに対応しています。指定できるのは以下のキーのみで、それ以外のキーを指定するとクエリは失敗します。いずれのパラメータも整数またはブール型であるため、Map の値は整数型である必要があります。

注記

  • 計算型 辞書 のセマンティクス。 これは計算型の 辞書 であり、行ではなく学習済みモデルを保持します。クエリする唯一の方法は predictXGBoost です。汎用の 辞書 インターフェイスはサポートされておらず、使用するとエラーになります。対象となるのは dictGet (参照すべき保存済みの属性は存在せず、“キー” は予測の入力となる特徴量ベクトルです) 、dictHas (キーは保存されていません) 、SELECT * FROM dict、および 辞書 をテーブルとして結合する操作です。predictXGBoost が唯一のエントリーポイントであるため、予測のたびに enable_xgboost 設定を有効にしておく必要があります。
  • 数値カラムのみ。 すべての特徴量 (キー) カラムはネイティブな数値型である必要があり、ターゲット属性は Float32 または Float64 でなければなりません。学習時および予測時、値は浮動小数点数として読み込まれます。predictXGBoost の特徴量引数は Nullable にすることもできます。詳しくは 仕組み を参照してください。
  • system.dictionaries には保存済みの項目が表示されません。 この 辞書 は行を保存する代わりにモデルを学習するため、direct 辞書 と同様に element_count は 0 となり、bytes_allocated も 0 になります。学習済みモデルは XGBoost が管理しており、XGBoost は保持しているメモリ量を報告しないためです。query_count と found_rate は、predictXGBoost によってモデルに渡された行数をカウントします。特徴量がすべて定数である呼び出しはブロックごとに 1 回だけ評価されるため、1 行ごとではなく 1 ブロックごとに 1 行としてカウントされます。
  • 再読み込みに失敗しても以前のモデルが維持されます。 再学習が失敗した場合 (ソーステーブルが削除された、スキーマが変更された、ハイパーパラメータが受け付けられなくなったなど) でも、辞書 による予測が失敗するようになるわけではありません。最後に学習に成功したモデルを引き続き使用し、エラーはその代わりに記録されます。モデルが現在のソースデータを反映しているかどうかを確認するには、system.dictionaries の last_successful_update_time と last_exception を比較してください:
  • XGBoost’s のメッセージはサーバーログに出力されます。 メッセージは XGBoost ロガーで、XGBoost が指定したログレベルのまま書き込まれます。また、学習または予測を行うクエリに関連付けられるため、system.text_log にも表示されます。より多くのメッセージを確認するには verbosity を上げてください。
  • 特徴量の順序が重要です。 predictXGBoost は位置依存の特徴量引数を宣言順にキーカラムへ対応付けます。そのため、特徴量引数の数はキーカラムの数と一致している必要があります。