レコメンドシステム構築ツール Recotem の 2.0.0 をリリースしました。
2.0 は 1.x からの完全な作り直しです。これまでの Django / Vue / Celery とデータベース・メッセージブローカーで構成された Web アプリケーションを廃止し、pip でインストールできる単一の Python パッケージと 1 つの Docker イメージにまとめました。レシピファイル（YAML）を 1 つ書き、コマンドを実行するだけでレコメンドモデルを作成でき、作成したモデルは Recotem が提供する Docker でそのままレコメンド API として立ち上げられます。
Recotem 2.0 で変わったこと
- レシピ駆動のワークフロー: 1 つの YAML レシピがそのまま 1 モデル・1 エンドポイントに対応します（1 recipe = 1 model = 1 endpoint）。
- 2 つの CLI コマンド:
recotem train <recipe.yaml>で学習し、recotem serve --recipes <dir>で配信します。 - FastAPI による配信:
/v1/recipes/{name}:recommendなどのエンドポイントでレコメンドを返します。アーティファクトの更新を検知してホットスワップします。 - 署名付きアーティファクト: 学習と配信は HMAC 署名付きのアーティファクトファイルのみでやり取りするため、別々のマシンで動かせます。共有データベースもメッセージブローカーも不要です。
- 多様なデータソース:
csv/parquet/bigquery/sql（PostgreSQL / MySQL / SQLite）に対応しています。 - Optuna によるハイパーパラメータ探索: irspack のアルゴリズムに対して自動でチューニングします。
なお Python 3.12 以上が必要です。1.x との互換性はなく、モデルは再学習が必要です。
インストール
pip install recotemまたは Docker イメージを利用します。
docker pull ghcr.io/codelibs/recotem:2.0.0レシピファイルでモデルを定義する
モデルは 1 つの YAML レシピで定義します。データソース、カラムの対応、前処理、学習アルゴリズム、出力先をまとめて記述します。以下はチュートリアル用のレシピ例です。
name: purchase_log
source:
# csv, parquet, bigquery（またはプラグイン名）を選択
type: csv
path: https://raw.githubusercontent.com/codelibs/recotem/refs/tags/v1.0.0/frontend/e2e/test_data/purchase_log.csv
# ネットワーク経由のパスでは sha256 が必須
sha256: 945fc769205a5976d38c5783500ae473afbb04608043b703951a699993c8f8be
dtype:
user_id: str
item_id: str
schema:
user_column: user_id
item_column: item_id
cleansing:
drop_null_ids: true
dedup: keep_last
min_rows: 100
min_users: 10
min_items: 10
training:
# IALS, CosineKNN, TopPop, RP3beta, DenseSLIM, TruncatedSVD, BPRFM から選択し Optuna が最適化
algorithms: [IALS, TopPop]
# ndcg, map, recall, hit から選択
metric: ndcg
cutoff: 10
n_trials: 10
parallelism: 1
split:
scheme: random
heldout_ratio: 0.2
seed: 42
output:
path: ./artifacts/purchase_log.recotem
versioning: append_sha
training.algorithms に複数のアルゴリズムを指定すると、Optuna が n_trials の範囲で組み合わせを探索し、metric で最良のモデルを選びます。
コマンドでモデルを作成する
まず署名用と API 用のキーを生成します。
recotem keygen --type signing --kid dev
recotem keygen --type api --kid dev生成したキーを環境変数に設定します。
export RECOTEM_SIGNING_KEYS="dev:<signing から得た平文>"
export RECOTEM_API_KEYS="dev:sha256:<api から得たハッシュ>"
export RECOTEM_API_PLAINTEXT="<api から得た平文>"レシピの内容を検証してから学習を実行します。
recotem validate examples/tutorial-purchase-log/recipe.yaml
recotem train examples/tutorial-purchase-log/recipe.yaml学習が完了すると、output.path に署名付きのアーティファクトファイルが出力されます。これがそのままレコメンドモデルの実体になります。
Docker でレコメンドAPIを立ち上げる
作成したモデルは、Recotem が提供する Docker でレコメンド API として配信できます。レシピを置いたディレクトリを指定して serve するだけです。
recotem serve --recipes examples/tutorial-purchase-log/付属の compose.yaml を使えば、学習と配信を Docker だけで完結できます。
docker compose run --rm train
docker compose up -d serve立ち上がった API には HTTP でリクエストします。ユーザーへのレコメンドは次のように取得します。
curl -sX POST http://localhost:8080/v1/recipes/purchase_log:recommend \
-H "X-API-Key: $RECOTEM_API_PLAINTEXT" \
-H "Content-Type: application/json" \
-d '{"user_id": "1", "limit": 5}' | jq .アイテムに関連するアイテムのレコメンドも取得できます。
curl -sX POST http://localhost:8080/v1/recipes/purchase_log:recommend-related \
-H "X-API-Key: $RECOTEM_API_PLAINTEXT" \
-H "Content-Type: application/json" \
-d '{"seed_items": ["<item_id>"], "limit": 5}' | jq .このほか :recommend-batch によるバッチ推論や、Prometheus 向けの /metrics エンドポイントにも対応しています。Helm チャートや Kubernetes 用のマニフェストも同梱しているため、コンテナ環境へそのままデプロイできます。
Claude Code でレコメンドモデルを作成する
2.0 ではレシピが単なる YAML ファイルになり、学習も配信もコマンド 1 つで実行できるようになりました。この設計により、Claude Code のような AI コーディングエージェントを使ったモデル作成も可能になります。
例えば、手元のデータのカラム構成を Claude Code に伝えれば、適切な source や schema を持つレシピファイルを生成してもらえます。そのまま recotem validate と recotem train を実行してモデルを作成し、評価結果を見ながらアルゴリズムや n_trials を調整する、といった一連の流れをエージェントに任せられます。レコメンドモデルの構築に必要な作業が「ファイルを書く」「コマンドを実行する」に集約されたことで、AI エージェントとの相性が大きく向上しました。
1.x からの移行
2.0 へは自動移行のパスがありません。次の点に注意してください。
- モデルは再学習する: 1.x のモデルは 2.0 の署名付きアーティファクト形式と互換性がありません。
- データベース・メッセージブローカーは不要: 2.0 はステートレスで、永続化されるのは署名付きアーティファクトファイルだけです。
- API クライアントを更新する:
/predict/{name}は廃止され、POST /v1/recipes/{name}:recommendに変わりました。 - キーを生成する:
recotem keygenで署名用・API 用のキーを生成し、RECOTEM_SIGNING_KEYS/RECOTEM_API_KEYSに設定します。
まとめ
Recotem 2.0.0 は、レシピファイルとコマンドでレコメンドモデルを手軽に作成し、Docker でそのまま API として配信できるツールに生まれ変わりました。重厚な Web アプリケーションから、軽量で AI エージェントとも組み合わせやすいレコメンド基盤へと進化しています。ぜひお試しください。