インストール

Recotem には Python 3.12 以上 が必要です。インストール方法は 2 つあります。Python パッケージとしてインストールする方法と、Docker イメージを使う方法です。どちらも同じ CLI と動作を提供します。

オプション A — pip

pip install recotem

注意 — pip install recotem が完了できないプラットフォームがあります

Recotem が依存する irspack は、Linux の x86-64 と arm64 (glibc または musl)、Apple Silicon の macOS、x86-64 の Windows 向けにしかホイールを公開しておらず、ソースディストリビューションも配布していません。そのため Intel の macOS と arm64 の Windows では、pip がインストールできるものもビルドできるものも存在せず、次のエラーで失敗します。

ERROR: No matching distribution found for irspack==0.5.2

コンパイラやビルドフラグでは回避できません。代わりにオプション B — Docker を使ってください。イメージはこれらのプラットフォームすべてで動作します。

インストールが成功したか確認します。

recotem --help

train、serve、inspect、validate、schema、keygen の 6 つのコマンドの一覧が表示されるはずです。シェルが recotem を見つけられない場合、パッケージが PATH に含まれていない仮想環境にインストールされています。先に環境をアクティベートするか、python -m recotem --help で実行してください。

オプションエクストラ

コアパッケージには CSV と Parquet のデータソースが含まれています。追加機能が必要な場合はエクストラをインストールしてください。

エクストラ	コマンド	追加される機能
BigQuery データソース	pip install "recotem[bigquery]"	Google BigQuery からインタラクションデータを読み込む
PostgreSQL データソース	pip install "recotem[postgres]"	psycopg 経由で PostgreSQL からインタラクションデータを読み込む
MySQL / MariaDB データソース	pip install "recotem[mysql]"	PyMySQL 経由で MySQL または MariaDB からインタラクションデータを読み込む
SQLite データソース	pip install "recotem[sqlite]"	SQLite からインタラクションデータを読み込む (標準ライブラリの sqlite3 を使用)
Amazon S3	pip install "recotem[s3]"	S3 からアーティファクトとデータを読み書きする
Google Cloud Storage	pip install "recotem[gcs]"	GCS からアーティファクトとデータを読み書きする
Azure Blob Storage	pip install "recotem[azure]"	Azure からアーティファクトとデータを読み書きする
Prometheus メトリクス	pip install "recotem[metrics]"	モニタリング用のオプトイン /v1/metrics エンドポイント (X-API-Key が必要)
BPRFM アルゴリズム	pip install "recotem[bprfm]"	training.algorithms で BPRFM を使えるようにする
すべて	pip install "recotem[all]"	上記すべてを一度に導入

エクストラは組み合わせて使えます: pip install "recotem[s3,metrics]"

BPRFM にはエクストラが必要です

irspack は BPRFMRecommender を別途インストールする lightfm パッケージの背後にゲートしており、そのインポートに失敗するとクラスをエクスポートしません。bprfm エクストラなしで training.algorithms に BPRFM を指定すると、recotem validate も recotem train もデータ取得の前に終了コード 4 と irspack does not know recommender class 'BPRFMRecommender' で失敗します。公式 Docker イメージには既に含まれています。サービング側の制限が 1 つあります。探索の勝者が BPRFM になったレシピは :recommend-related と :batch-recommend-related に応答できず、501 RELATED_NOT_SUPPORTED を返します (サービング API を参照)。

依存パッケージは lightfm-next で、同じ lightfm モジュールを提供する保守されたフォークです (本家 lightfm は 1.17 以降リリースがなく、Python 3.12 でビルドできません)。注意点が 2 つあります。linux/aarch64 のホイールが公開されていないため、arm64 では pip install "recotem[bprfm]" がソースからビルドされ C コンパイラが必要です (公開 Docker イメージは両アーキテクチャでビルド済みのため影響を受けません)。また macOS では OpenMP なしでビルドされるため、BPRFM の学習はシングルスレッドになります。

オプション B — Docker

公式イメージは GitHub Container Registry で公開されています。

docker pull ghcr.io/codelibs/recotem:latest

イメージは非 root ユーザー (UID 1000) で実行されます。学習や配信の際は、レシピディレクトリとアーティファクトディレクトリをボリュームとしてマウントしてください。チュートリアルの compose.yaml に完全な動作例があります。チュートリアルを参照してください。

イメージが正常に動作するか確認します。

docker run --rm ghcr.io/codelibs/recotem:latest --help

鍵の生成

Recotem は 2 種類の鍵を使います。train や serve を実行する前に一度だけ生成する必要があります。

署名鍵

署名鍵は学習済みモデルのアーティファクトの完全性を保護します。recotem train がアーティファクトへの署名に使用し、recotem serve が読み込み前の検証に使用します。アーティファクトが改ざんされたり破損したりしていると検証に失敗し、モデルは読み込まれません。

recotem keygen --type signing --kid prod

出力例:

kid=prod
plaintext=<64 文字の hex 文字列>
fingerprint=<8 文字の hex>  # 参考情報のみ。サーバーログと照合できます
env_entry=RECOTEM_SIGNING_KEYS=prod:<64 文字の hex 文字列>

env_entry の行をコピーしてシェルでエクスポートするか、シークレットマネージャーに保存してください。

export RECOTEM_SIGNING_KEYS="prod:<64 文字の hex 文字列>"

API キー

API キーはサービング API を呼び出せるクライアントを制御します。認証不要の 3 つのプローブ (GET /v1/health、GET /v1/health/live、GET /v1/health/ready) を除くすべてのエンドポイントで必要で、/v1/recipes/{name}:recommend などのレシピ動詞も含まれます。クライアントは X-API-Key HTTP ヘッダーとして送信します。サーバーはキーのハッシュのみを保存し、平文は保存しません。

recotem keygen --type api --kid client-a

出力例:

kid=client-a
plaintext=<43 文字の base64url 文字列>  ← API クライアントに共有するキー
hash=sha256:<64 文字の hex>
env_entry=RECOTEM_API_KEYS=client-a:sha256:<64 文字の hex>

サーバー用に env_entry の行をエクスポートし、クライアントから X-API-Key ヘッダーとして渡すために plaintext の値を手元に保管してください。

export RECOTEM_API_KEYS="client-a:sha256:<64 文字の hex>"
export RECOTEM_API_PLAINTEXT="<43 文字の base64url 文字列>"

RECOTEM_API_KEYS が設定されていない場合、サーバーは 127.0.0.1 のみにバインドされます (ループバックのみ)。ネットワークインターフェースにサーバーを公開する前に API キーを設定してください。

まとめ: 各変数の役割

変数	使用するコマンド	目的
RECOTEM_SIGNING_KEYS	train と serve	アーティファクトファイルの HMAC 署名と検証
RECOTEM_API_KEYS	serve	/v1 API 呼び出し元の認証 (サーバーはハッシュのみ保存)
X-API-Key: <plaintext>	HTTP クライアント	3 つのプローブ GET /v1/health、GET /v1/health/live、GET /v1/health/ready を除くすべての /v1 リクエストに付加して送信

RECOTEM_SIGNING_KEYS と RECOTEM_API_KEYS はどちらも複数のエントリをカンマ区切りで指定できます (kid1:value,kid2:value)。これにより、ダウンタイムなしで鍵のローテーションが可能です。ローテーション手順についてはオペレーションガイドを参照してください。

次のステップ

チュートリアルに従って、10 分以内に最初の推薦システムを学習・配信してみましょう。