Recotem 2.0.0のリリース - 今日のひとこと

レコメンドシステム構築ツール 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 エージェントとも組み合わせやすいレコメンド基盤へと進化しています。ぜひお試しください。