MiniOneRec : reproduire une recommandation générative de bout en bout

Le problème : passer d'un catalogue à une suite de tokens

Un système de recommandation classique classe des items. Un recommandeur génératif les écrit. La différence n'est pas cosmétique : il faut d'abord transformer chaque produit en une séquence discrète que le modèle peut prédire token par token. MiniOneRec s'attaque à cette étape et à celles qui suivent, dans un seul dépôt Python sous licence Apache-2.0. Le public visé est celui qui veut reproduire une chaîne complète plutôt que consommer une API : le README annonce un flux de bout en bout couvrant la construction de SID, le supervised fine-tuning et une phase de reinforcement learning orientée recommandation. Le dépôt se présente comme la première reproduction entièrement open source d'un cadre de recommandation générative, ce qui situe l'ambition : il s'agit d'un support de reproduction, pas d'un produit.

Comment un article devient un SID

La première étape est décrite dans le README. Le titre et la description d'un item sont concaténés, la phrase passe dans un encodeur de texte gelé, et l'embedding obtenu est quantifié par un RQ-VAE à trois niveaux. Le résultat est un code court, le SID, qui remplace l'identifiant produit dans toutes les étapes suivantes. Ce choix a une conséquence directe : deux items aux descriptions proches tombent dans des codes proches, ce qu'un identifiant arbitraire ne permet pas. Le dépôt documente plusieurs variantes de cette construction, dont RQ-Kmeans, constrained-RQ-Kmeans et RQ-Kmeans+, cette dernière étant présentée comme la première reproduction open source d'une méthode proposée dans GPR. Une note du 19 novembre 2025 signale qu'une version multi-GPU du calcul texte vers embedding repose sur Accelerate, dans rq/text2emb/amazon_text2emb.py. La construction des SID n'est donc pas un détail figé : c'est la partie du dépôt qui a le plus bougé.

SFT : prédire le prochain SID sans perdre le langage

Une fois le catalogue converti, l'historique utilisateur chronologique est traité comme une séquence de tokens et le modèle apprend par next-token prediction à produire le SID du produit suivant. Le point intéressant est le co-entraînement : le README décrit des objectifs d'alignement linguistique qui font l'aller-retour entre langage naturel et espace SID. L'intention est de conserver la connaissance du monde portée par le LLM tout en l'ancrant sur des codes discrets. Le dépôt propose aussi une variante GPR, sft_gpr.py, présentée comme un Value-Aware Fine-Tuning avec une perte pondérée par une valeur d'item simulée. Deux scripts coexistent donc pour la même étape, avec des hypothèses différentes sur ce qui mérite d'être appris en priorité. Le README précise également qu'il est possible de geler les paramètres du LLM pendant le SFT et de n'entraîner que les embeddings du vocabulaire SID ajouté, ce qui change fortement le coût matériel de l'étape.

RL et décodage contraint : la partie qui casse

Après le SFT vient une phase de RL basée sur GRPO. Plusieurs recommandations candidates sont générées pour chaque prompt, leurs récompenses sont normalisées à l'intérieur du groupe, et une pénalité KL maintient la politique mise à jour près de sa référence. Le signal de récompense combine un terme binaire de correction et une composante sensible au rang qui pénalise davantage les items probables mais faux, avec la possibilité d'y ajouter des scores de filtrage collaboratif. L'action étant une liste fermée de SID, le système bascule vers une recherche par faisceau contrainte censée garantir des faisceaux uniques et valides. C'est ici que la documentation devient franchement utile. Une note du 4 janvier 2026 demande de vérifier si la métrique CC du journal d'évaluation est non nulle, en renvoyant à calc.py. Si elle l'est, le modèle génère encore beaucoup d'items invalides et le décodage contraint n'a pas fonctionné. L'équipe soupçonne un lien avec la version de bibliothèques comme transformers et indique ne pas avoir de solution universelle, en suggérant de passer d'un modèle Instruct à un modèle de base tel que Qwen2.5-base. Autrement dit, la garantie annoncée sur les faisceaux dépend d'un environnement de dépendances que le dépôt ne verrouille pas complètement.

Mise en route : les scripts et les fichiers de configuration

L'entrée se fait par des scripts shell. sft.sh lance l'étape de supervised fine-tuning et sft.py en contient la boucle ; rl.sh et rl.py font de même pour le RL. Les hyperparamètres passent par des fichiers YAML rangés dans configs/. L'évaluation hors ligne se fait avec evaluate.sh, tandis que evaluate.py calcule HR@K et NDCG@K. Le décodage contraint est implémenté dans LogitProcessor.py. Pour la variante GPR, les points d'entrée sont sft_gpr.py pour le Value-Aware Fine-Tuning et rl_gpr.py pour le Hierarchy Enhanced Policy Optimization. minionerec_trainer.py porte l'entraîneur GRPO spécialisé. Le README renvoie vers des checkpoints hébergés sur Hugging Face et ModelScope, et vers un rapport technique sur arXiv. Il ne fournit pas de commande d'installation détaillée dans l'extrait disponible, ni de fichier de dépendances épinglé ; c'est une lacune à combler en lisant le dépôt avant de lancer quoi que ce soit.

Les limites que le dépôt reconnaît lui-même

Le journal des modifications est le document le plus instructif du dépôt. Le 1er décembre 2025, une correction porte sur un bug dans data.py qui pouvait faire voir les réponses à l'avance à la tâche d'alignement SID-item, l'équipe précisant qu'il s'agissait d'une tentative antérieure d'utiliser des trajectoires partielles et que cela n'affectait pas les performances du modèle. Le 7 novembre 2025, le README invite à mettre à jour vers la dernière version avant de signaler un problème, ce qui suppose que les premières versions avaient des défauts connus. La question du décodage contraint reste ouverte à la date de la dernière note disponible. Un lecteur qui évalue ce dépôt doit donc traiter la reproductibilité comme un chantier actif, pas comme un acquis. Le dépôt n'a par ailleurs publié aucune release, ce qui complique le suivi des versions stables.

Ce qui distingue cette approche d'un pipeline classique

La comparaison la plus nette est avec une chaîne de filtrage collaboratif suivie d'un réordonnancement, où les identifiants d'items sont arbitraires et où le modèle apprend une fonction de score. Ici, l'item est un code produit par un RQ-VAE, et le modèle génère ce code. La différence de mécanisme entraîne une différence de coût : il faut construire les SID pour tout le catalogue avant de pouvoir entraîner quoi que ce soit, et toute modification de l'encodeur de texte ou du quantifieur invalide les SID existants. En échange, le système hérite du langage du LLM sous-jacent, ce qui est l'argument central du co-entraînement décrit plus haut. Un autre point de comparaison interne au dépôt : la variante GPR remplace la perte standard par une pondération par valeur simulée et la politique par HEPO. Le dépôt ne tranche pas entre les deux, et l'extrait disponible ne permet pas de dire laquelle est la plus stable.

Coût de maintenance et cadre de licence

Le rythme des commits visibles dans le journal est élevé : plusieurs entrées entre fin octobre 2025 et mai 2026, avec des changements de méthode de construction de SID et des corrections de bugs. Adopter ce dépôt implique de suivre ces changements, car les SID et les checkpoints ne sont pas nécessairement compatibles d'une version à l'autre. Le projet est distribué sous Apache-2.0, ce qui autorise l'usage commercial et la modification, avec les obligations habituelles de conservation des mentions de licence et d'état des modifications. Le dépôt ne contient aucun élément suggérant des restrictions supplémentaires, mais les checkpoints hébergés sur Hugging Face et ModelScope peuvent relever de conditions propres, à vérifier séparément. Rien dans le matériel fourni ne permet d'estimer le coût GPU des étapes SFT et RL ; le README mentionne seulement une version multi-GPU plus efficace pour le calcul des embeddings.

Conclusion éditoriale

MiniOneRec convient à une équipe qui veut reproduire une chaîne complète de recommandation générative et qui accepte de lire calc.py pour interpréter ses métriques. À éviter si vous cherchez un service de recommandation prêt à l'emploi ou si vous ne pouvez pas immobiliser plusieurs GPU. Avant de vous engager, vérifiez le taux de CC non nul dans le journal d'évaluation et testez le script sur un modèle de base plutôt qu'Instruct.

Sources officielles

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