MiniOneRec：SID構築からGRPOまでを1本のパイプラインに収めた生成推薦の再現実装

既存の推薦モデルではなく、なぜ「生成」なのか

通常の推薦モデルは、ユーザーと商品のID埋め込みを作り、その内積や浅いネットワークで候補をスコアリングする。商品数が増えれば出力層も比例して膨らみ、新規商品への対応は別途作り込む必要がある。MiniOneRecが解こうとしているのはこの構造そのものだ。READMEにある通り、商品をタイトルと説明文の連結から凍結済みテキストエンコーダで埋め込み、それを3段階のRQ-VAEで量子化してSID（Semantic ID）という離散トークンに置き換える。推薦は「次の商品のSIDを次トークン予測で生成する」問題に翻訳される。想定読者は、推薦モデルの設計をID埋め込みから言語モデルの語彙空間へ移したい研究者、あるいはその再現実装を出発点にしたいエンジニアである。

SID構築：タイトルと説明文を3段のRQ-VAEで離散化する

パイプラインの最初の工程は、すべての商品をSIDに書き換えることだ。READMEの記述では、商品のタイトルと説明文を連結した文を凍結テキストエンコーダに通し、得られた埋め込みを3レベル構成のRQ-VAEで量子化する。ここで重要なのは、SIDが単なる連番ではなく、テキストの意味を反映したコードになる点である。意味が近い商品は近いコード列になりやすく、言語モデルが持つ語彙空間の上に推薦の行動空間を載せられる。リポジトリにはRQ-Kmeans、RQ-Kmeans+、constrained-RQ-Kmeansといった複数の構築手法が更新履歴つきで並んでおり、単一の正解アルゴリズムを固定していない。手法ごとにコードの割り当て方が変わるため、同じデータでもSID列は異なる。評価結果を比較するときは、どの構築手法の出力を使ったかを必ず揃える必要がある。

SFTは次トークン予測だけでは終わらない

SIDが振られた後、モデルは教師あり学習に入る。ユーザー履歴を時系列順のトークン列とみなし、次に消費されそうな商品のSIDを次トークン予測で生成できるように学習する。READMEが「Crucially」と書いているのは、この段階が言語アラインメント目的のタスクと共訓練される点だ。自然言語とSID空間を双方向に写像する補助タスクを混ぜることで、大規模言語モデルが持つ世界知識を推薦側に引き継がせつつ、その知識を離散的な商品コードに接地させる。エントリポイントはsft.shとsft.pyで、設定はconfigs/配下のYAMLに置かれる。更新履歴には、SFT段階でLLMパラメータを凍結し、新規追加したSID語彙の埋め込みだけを学習する選択肢が加わったと記されている。計算資源が限られる環境ではこの凍結モードが現実的な出発点になる。

GRPOと制約付きビーム探索が効く理由

SFTの後、推薦向けのRL段階が続く。READMEによればGRPOをベースに、各プロンプトに対して複数の推薦候補を生成し、その報酬をグループ内で正規化して勾配を安定させる。同時にKLペナルティで更新後の方針を参照モデルから離しすぎないように制御する。行動空間が商品SIDの閉じたリストである点を活かし、推論時は制約付きビーム探索に切り替える。これにより各ビームが一意かつ有効な商品に対応することが保証され、サンプリング効率と多様性が上がる。報酬は二値の正解項と、確率が高いのに誤っている候補をより強く罰するランク考慮項の組み合わせで、協調フィルタリングのスコアを加えることもできる。実装はrl.sh、rl.py、minionerec_trainer.py、そして制約付きデコードを担うLogitProcessor.pyが対応する。

動かす前に押さえる実行手順と設定の所在

入口はシェルスクリプトで統一されている。SFTはsft.sh、RLはrl.sh、オフライン評価はevaluate.shを実行する。評価スクリプトはHR@KとNDCG@Kを計算し、evaluate.pyがその実体である。ハイパーパラメータやパスはconfigs/配下のYAMLに集約されているので、まずそこを自分のデータセットに合わせて書き換える。SID構築はRQ系のスクリプト群が担当し、Amazon23データセット向けの処理スクリプトも追加されている。テキスト埋め込みの生成はAccelerateベースのマルチGPU並列版がrq/text2emb/amazon_text2emb.pyとして用意されており、旧版より効率的だと更新履歴に記されている。学習済みチェックポイントはHugging FaceとModelScopeの両方から取得できる。

再現性の落とし穴：CC指標と依存ライブラリ

このリポジトリで最も注意すべき制約は、制約付きデコードが環境によって期待通り動かないという既知の問題だ。2026年1月4日の告知は、Instructモデルでの再現結果が報告値とずれる場合、評価ログのCC指標が非ゼロでないかを確認するよう求めている。非ゼロならモデルが大量の無効商品を生成しており、制約付きデコードが効いていないことを意味する。原因はtransformersなど依存ライブラリのバージョンにあると推測され、汎用的な解決策はまだ調査中と明記されている。暫定回避としてQwen2.5-baseのようなベースモデルに切り替える方法が示されている。つまり同じコードでも、環境次第で有効なSIDを生成できるかどうかが変わる。再現実験を計画するなら、依存関係のバージョンを固定し、CC指標を最初に確認する手順を組むべきだ。

GPR系の派生実装とTS-Recという別系統

リポジトリには標準のSFT/RLとは別に、GPRに着想を得た派生実装が同居している。sft_gpr.pyは商品価値を模擬した重み付き損失（Value-Aware Fine-Tuning）を実装し、rl_gpr.pyはHierarchy Enhanced Policy Optimizationを実装する。標準のGRPOが報酬の正しさとランクに基づくのに対し、こちらは商品価値や階層構造を損失設計に織り込む点が異なる。2026年5月13日にはTS-Recコードベースが追加され、別論文の手法に従うことが告知されている。1つのリポジトリに複数の手法系統が並ぶ構成は、比較検証には便利だが、どのスクリプトがどの論文に対応するかを追わないと結果の解釈を誤る。

代替手段としての二段階検索と、MiniOneRecが向かない場面

生成推薦の対極にあるのは、埋め込みベースの二段階検索だ。ユーザーと商品をベクトル化し、近似最近傍探索で候補を絞ってからランキングモデルで並べ替える。この方式は行動空間が固定のベクトル空間で、候補数やレイテンシを制御しやすい。MiniOneRecは行動空間を言語モデルの語彙に置き換える代わりに、SID構築、SFT、RLという3段の工程と、それぞれに固有の失敗モードを引き受ける。特に制約付きデコードが効かなければ無効商品を生成し続けるため、オンライン推論の安定性が最優先の用途には向かない。またデータセットごとにSID構築スクリプトを用意する必要があり、新規ドメインへの適用コストは二段階検索より高い。Apache-2.0で提供されているため改変と再配布の自由度は高いが、同梱のモデル重みやデータセットの扱いは別途確認が必要で、ここは法的助言ではなく確認事項として挙げておく。

編集部の結論

MiniOneRecは、生成推薦のSID構築からSFT、GRPOによるRLまでを自分の手元で動かして挙動を確認したい研究・検証目的のチームに向く。既存の推薦基盤を置き換える目的や、低レイテンシのオンライン推論が要件に入る場合は適さない。導入前に確認すべきは、評価ログのCC指標が非ゼロになっていないか（calc.py参照）、transformersなど依存ライブラリのバージョンで制約付きデコードが期待通り動くか、そしてデータセットごとのSID構築スクリプトが自分のデータ形式に対応しているかの3点である。

公式情報源

1. AkaliKong/MiniOneRec on GitHub
2. Issues
3. License: Apache-2.0
4. README