[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"similar-AkaliKong--MiniOneRec":3,"tool-AkaliKong--MiniOneRec":61},[4,18,26,36,44,53],{"id":5,"name":6,"github_repo":7,"description_zh":8,"stars":9,"difficulty_score":10,"last_commit_at":11,"category_tags":12,"status":17},4358,"openclaw","openclaw\u002Fopenclaw","OpenClaw 是一款专为个人打造的本地化 AI 助手，旨在让你在自己的设备上拥有完全可控的智能伙伴。它打破了传统 AI 助手局限于特定网页或应用的束缚，能够直接接入你日常使用的各类通讯渠道，包括微信、WhatsApp、Telegram、Discord、iMessage 等数十种平台。无论你在哪个聊天软件中发送消息，OpenClaw 都能即时响应，甚至支持在 macOS、iOS 和 Android 设备上进行语音交互，并提供实时的画布渲染功能供你操控。\n\n这款工具主要解决了用户对数据隐私、响应速度以及“始终在线”体验的需求。通过将 AI 部署在本地，用户无需依赖云端服务即可享受快速、私密的智能辅助，真正实现了“你的数据，你做主”。其独特的技术亮点在于强大的网关架构，将控制平面与核心助手分离，确保跨平台通信的流畅性与扩展性。\n\nOpenClaw 非常适合希望构建个性化工作流的技术爱好者、开发者，以及注重隐私保护且不愿被单一生态绑定的普通用户。只要具备基础的终端操作能力（支持 macOS、Linux 及 Windows WSL2），即可通过简单的命令行引导完成部署。如果你渴望拥有一个懂你",349277,3,"2026-04-06T06:32:30",[13,14,15,16],"Agent","开发框架","图像","数据工具","ready",{"id":19,"name":20,"github_repo":21,"description_zh":22,"stars":23,"difficulty_score":10,"last_commit_at":24,"category_tags":25,"status":17},3808,"stable-diffusion-webui","AUTOMATIC1111\u002Fstable-diffusion-webui","stable-diffusion-webui 是一个基于 Gradio 构建的网页版操作界面，旨在让用户能够轻松地在本地运行和使用强大的 Stable Diffusion 图像生成模型。它解决了原始模型依赖命令行、操作门槛高且功能分散的痛点，将复杂的 AI 绘图流程整合进一个直观易用的图形化平台。\n\n无论是希望快速上手的普通创作者、需要精细控制画面细节的设计师，还是想要深入探索模型潜力的开发者与研究人员，都能从中获益。其核心亮点在于极高的功能丰富度：不仅支持文生图、图生图、局部重绘（Inpainting）和外绘（Outpainting）等基础模式，还独创了注意力机制调整、提示词矩阵、负向提示词以及“高清修复”等高级功能。此外，它内置了 GFPGAN 和 CodeFormer 等人脸修复工具，支持多种神经网络放大算法，并允许用户通过插件系统无限扩展能力。即使是显存有限的设备，stable-diffusion-webui 也提供了相应的优化选项，让高质量的 AI 艺术创作变得触手可及。",162132,"2026-04-05T11:01:52",[14,15,13],{"id":27,"name":28,"github_repo":29,"description_zh":30,"stars":31,"difficulty_score":32,"last_commit_at":33,"category_tags":34,"status":17},1381,"everything-claude-code","affaan-m\u002Feverything-claude-code","everything-claude-code 是一套专为 AI 编程助手（如 Claude Code、Codex、Cursor 等）打造的高性能优化系统。它不仅仅是一组配置文件，而是一个经过长期实战打磨的完整框架，旨在解决 AI 代理在实际开发中面临的效率低下、记忆丢失、安全隐患及缺乏持续学习能力等核心痛点。\n\n通过引入技能模块化、直觉增强、记忆持久化机制以及内置的安全扫描功能，everything-claude-code 能显著提升 AI 在复杂任务中的表现，帮助开发者构建更稳定、更智能的生产级 AI 代理。其独特的“研究优先”开发理念和针对 Token 消耗的优化策略，使得模型响应更快、成本更低，同时有效防御潜在的攻击向量。\n\n这套工具特别适合软件开发者、AI 研究人员以及希望深度定制 AI 工作流的技术团队使用。无论您是在构建大型代码库，还是需要 AI 协助进行安全审计与自动化测试，everything-claude-code 都能提供强大的底层支持。作为一个曾荣获 Anthropic 黑客大奖的开源项目，它融合了多语言支持与丰富的实战钩子（hooks），让 AI 真正成长为懂上",160411,2,"2026-04-18T23:33:24",[14,13,35],"语言模型",{"id":37,"name":38,"github_repo":39,"description_zh":40,"stars":41,"difficulty_score":32,"last_commit_at":42,"category_tags":43,"status":17},2271,"ComfyUI","Comfy-Org\u002FComfyUI","ComfyUI 是一款功能强大且高度模块化的视觉 AI 引擎，专为设计和执行复杂的 Stable Diffusion 图像生成流程而打造。它摒弃了传统的代码编写模式，采用直观的节点式流程图界面，让用户通过连接不同的功能模块即可构建个性化的生成管线。\n\n这一设计巧妙解决了高级 AI 绘图工作流配置复杂、灵活性不足的痛点。用户无需具备编程背景，也能自由组合模型、调整参数并实时预览效果，轻松实现从基础文生图到多步骤高清修复等各类复杂任务。ComfyUI 拥有极佳的兼容性，不仅支持 Windows、macOS 和 Linux 全平台，还广泛适配 NVIDIA、AMD、Intel 及苹果 Silicon 等多种硬件架构，并率先支持 SDXL、Flux、SD3 等前沿模型。\n\n无论是希望深入探索算法潜力的研究人员和开发者，还是追求极致创作自由度的设计师与资深 AI 绘画爱好者，ComfyUI 都能提供强大的支持。其独特的模块化架构允许社区不断扩展新功能，使其成为当前最灵活、生态最丰富的开源扩散模型工具之一，帮助用户将创意高效转化为现实。",109154,"2026-04-18T11:18:24",[14,15,13],{"id":45,"name":46,"github_repo":47,"description_zh":48,"stars":49,"difficulty_score":32,"last_commit_at":50,"category_tags":51,"status":17},6121,"gemini-cli","google-gemini\u002Fgemini-cli","gemini-cli 是一款由谷歌推出的开源 AI 命令行工具，它将强大的 Gemini 大模型能力直接集成到用户的终端环境中。对于习惯在命令行工作的开发者而言，它提供了一条从输入提示词到获取模型响应的最短路径，无需切换窗口即可享受智能辅助。\n\n这款工具主要解决了开发过程中频繁上下文切换的痛点，让用户能在熟悉的终端界面内直接完成代码理解、生成、调试以及自动化运维任务。无论是查询大型代码库、根据草图生成应用，还是执行复杂的 Git 操作，gemini-cli 都能通过自然语言指令高效处理。\n\n它特别适合广大软件工程师、DevOps 人员及技术研究人员使用。其核心亮点包括支持高达 100 万 token 的超长上下文窗口，具备出色的逻辑推理能力；内置 Google 搜索、文件操作及 Shell 命令执行等实用工具；更独特的是，它支持 MCP（模型上下文协议），允许用户灵活扩展自定义集成，连接如图像生成等外部能力。此外，个人谷歌账号即可享受免费的额度支持，且项目基于 Apache 2.0 协议完全开源，是提升终端工作效率的理想助手。",100752,"2026-04-10T01:20:03",[52,13,15,14],"插件",{"id":54,"name":55,"github_repo":56,"description_zh":57,"stars":58,"difficulty_score":32,"last_commit_at":59,"category_tags":60,"status":17},4721,"markitdown","microsoft\u002Fmarkitdown","MarkItDown 是一款由微软 AutoGen 团队打造的轻量级 Python 工具，专为将各类文件高效转换为 Markdown 格式而设计。它支持 PDF、Word、Excel、PPT、图片（含 OCR）、音频（含语音转录）、HTML 乃至 YouTube 链接等多种格式的解析，能够精准提取文档中的标题、列表、表格和链接等关键结构信息。\n\n在人工智能应用日益普及的今天，大语言模型（LLM）虽擅长处理文本，却难以直接读取复杂的二进制办公文档。MarkItDown 恰好解决了这一痛点，它将非结构化或半结构化的文件转化为模型“原生理解”且 Token 效率极高的 Markdown 格式，成为连接本地文件与 AI 分析 pipeline 的理想桥梁。此外，它还提供了 MCP（模型上下文协议）服务器，可无缝集成到 Claude Desktop 等 LLM 应用中。\n\n这款工具特别适合开发者、数据科学家及 AI 研究人员使用，尤其是那些需要构建文档检索增强生成（RAG）系统、进行批量文本分析或希望让 AI 助手直接“阅读”本地文件的用户。虽然生成的内容也具备一定可读性，但其核心优势在于为机器",93400,"2026-04-06T19:52:38",[52,14],{"id":62,"github_repo":63,"name":64,"description_en":65,"description_zh":66,"ai_summary_zh":66,"readme_en":67,"readme_zh":68,"quickstart_zh":69,"use_case_zh":70,"hero_image_url":71,"owner_login":72,"owner_name":73,"owner_avatar_url":74,"owner_bio":75,"owner_company":76,"owner_location":77,"owner_email":78,"owner_twitter":78,"owner_website":78,"owner_url":79,"languages":80,"stars":89,"forks":90,"last_commit_at":91,"license":92,"difficulty_score":93,"env_os":94,"env_gpu":95,"env_ram":96,"env_deps":97,"category_tags":106,"github_topics":107,"view_count":32,"oss_zip_url":78,"oss_zip_packed_at":78,"status":17,"created_at":118,"updated_at":119,"faqs":120,"releases":149},9440,"AkaliKong\u002FMiniOneRec","MiniOneRec","Minimal reproduction of OneRec","MiniOneRec 是全球首个完全开源的生成式推荐框架，旨在为大规模推荐系统提供从数据构建到模型训练的一站式解决方案。它主要解决了传统推荐方法难以有效融合大语言模型语义知识、以及生成式推荐流程复杂且缺乏统一复现标准的痛点。\n\n该工具特别适合推荐算法工程师、AI 研究人员以及希望探索下一代推荐技术的开发者使用。其核心工作流包含三个关键阶段：首先通过独特的 SID 构建技术，将商品标题和描述转化为紧凑的语义令牌；接着利用监督微调（SFT），让模型在学习用户行为序列的同时，通过对齐目标继承大模型的通用世界知识；最后引入面向推荐的强化学习（RL）进一步优化策略。\n\nMiniOneRec 的技术亮点在于其创新的“残量量化变分自编码器（RQ-VAE）”用于生成离散物品代码，以及支持多 GPU 并行的高效文本向量化能力。此外，项目持续更新，不仅修复了数据泄露等潜在问题，还提供了灵活的训练选项（如冻结大模型参数仅训练嵌入层），并兼容多种主流数据集。无论是用于学术研究复现，还是构建工业级原型，MiniOneRec 都提供了一个透明、高效且易于扩展的基础设施。","\u003Cdiv align=\"center\">\n\n\n\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FAkaliKong_MiniOneRec_readme_82a24ab36e77.png\" width=\"500em\" >\u003C\u002Fimg> \n\n**An Open-Source Framework for\nScaling Generative Recommendation**\n\n![Python](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FPython-3.10+-blue.svg)\n![License](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLicense-Apache--2.0-green.svg)\n\u003Ca href=\"https:\u002F\u002Farxiv.org\u002Fabs\u002F2510.24431\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fstatic\u002Fv1?label=arXiv&message=Paper&color=red\">\u003C\u002Fa>\n\n\u003Ca href=\"https:\u002F\u002Farxiv.org\u002Fabs\u002F2510.24431\">📄 Technical Report\u003C\u002Fa> | \u003Ca href=\"https:\u002F\u002Fhuggingface.co\u002Fkkknight\u002FMiniOneRec\">🤗 Huggingface\u003C\u002Fa> | \u003Ca href=\"https:\u002F\u002Fmodelscope.cn\u002Fmodels\u002Fk925238839\u002FMiniOneRec\">🤖  Modelscope\u003C\u002Fa>\n\u003C\u002Fdiv>\n\n**MiniOneRec** is the first fully open-source **generative recommendation** framework, which provides an end-to-end workflow spanning **SID construction**, **supervised fine-tuning (SFT)**, and recommendation-oriented **reinforcement learning (RL)**. \n\n---\n\n## 📢 Announcement\n\n- 2026-01-04 — Regarding the potential discrepancies between the reproduced results based on the Instruct model and our reported metrics, please check whether the CC metric in the evaluation log is non-zero (refer to calc.py). If it is non-zero, it indicates that the model is still generating a large number of invalid items, and constrained decoding has not been successful. We suspect this issue may be related to the versions of dependencies such as the transformer library, and we are still investigating the cause to provide a universal solution. In the meantime, you may switch the Instruct model to a base model, such as Qwen2.5-base, to avoid this problem.\n\n- 2025-12-04 — We update new scripts to support processing the Amazon23 dataset.\n\n- 2025-12-01 — We fix a bug in data.py that could cause the SID–item alignment task to see the answers in advance. This was because we had previously attempted to use partial trajectories to guide the full SID–item generation and does not affect the model performance.\n\n- 2025-11-20 — The SID construction method in **RQ-Kmeans+** has been updated (first proposed in **GPR** and this is the first open-source reproduction).\n\n- 2025-11-19 — We implemented a multi-GPU parallel text-to-embedding method based on Accelerate, which is significantly more efficient than the original version: rq\u002Ftext2emb\u002Famazon_text2emb.py\n\n- 2025-11-19 — The SID construction method in **constrained-RQ-Kmeans** has been updated.\n\n- 2025-11-07 — Thank you for submitting issues! Based on your feedback, we have released a new implementation. If you encounter any problems while running the code, please update to and consult the **latest version** first.\n  \n- 2025-11-07 — You can now choose to freeze the LLM parameters during the SFT stage and train only the embeddings for the newly added SID vocabulary.\n\n- 2025-10-31 — You can now directly download the implementation **checkpoints** of our MiniOnRec model.\n\n- 2025-10-31 — The SID construction method in **RQ-Kmeans** has been updated.\n\n---\n\n## 🛠️ Key Techniques \n\u003Cdiv align=\"center\">\n\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FAkaliKong_MiniOneRec_readme_34246ccafd0d.png\" width=100% >\u003C\u002Fimg> \n\u003C\u002Fdiv>\n\n- **SID Construction: MiniOneRec begins by transforming every product into a compact, semantically meaningful token.** It concatenates an item’s title and description, feeds this sentence through a frozen text encoder, and then quantises the resulting embedding with a three-level RQ-VAE.\n\n- **SFT: With all items rewritten as SIDs, the model is first trained in a supervised fashion.** It views the chronologically ordered user history as a token sequence and learns, via next-token prediction, to generate the SID of the next product the user is likely to consume. Crucially, this stage is co-trained with a set of language-alignment objectives that map back and forth between natural language and SID space, allowing the recommender to inherit the world knowledge embedded in large language models while grounding that knowledge in discrete item codes.\n\n- **Recommendation-Oriented RL: After SFT, MiniOneRec is further polished with a recommendation-oriented RL phase based on GRPO.** Multiple candidate recommendations are generated for each prompt, their rewards are normalised within the group to stabilise gradients, and a KL penalty keeps the updated policy close to its reference. Because the action space is a closed list of item SIDs, the system switches to constrained beam search, which guarantees that every beam is unique and valid, greatly improving sampling efficiency and diversity. The reward signal itself blends a binary correctness term with a rank-aware component that penalises high-probability yet incorrect items more heavily, and can be augmented with collaborative-filtering scores. Together, this pipeline enables MiniOneRec to couple dense linguistic knowledge, achieving a high-performance, lightweight generative recommendation system.\n\n---\n\n## 📊 Evaluation\n\n\u003Cdiv align=\"center\">\n\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FAkaliKong_MiniOneRec_readme_21a96563d566.png\" width=100% >\u003C\u002Fimg> \n\u003C\u002Fdiv>\n\n---\n\n## 🗂️ Repository Overview\n\n| File \u002F Directory          | Description                                                                                                   |\n| ------------------------- | ------------------------------------------------------------------------------------------------------------- |\n| `sft.sh`                  | Shell script to start the Supervised Fine-Tuning (SFT) stage                                           |\n| `sft.py`                  | Python implementation of the SFT training loop                                                            |\n| `sft_gpr.py`              | GPR-inspired SFT with Value-Aware Fine-Tuning (VAFT): implements weighted loss based on simulated item value                            |\n| `rl.sh`                   | Shell script to start the Reinforcement Learning (RL) stage                             |\n| `rl.py`                   | Python implementation of the RL training loop                                              |\n| `rl_gpr.py`               | GPR-inspired RL with Hierarchy Enhanced Policy Optimization (HEPO)                                                 |\n| `minionerec_trainer.py`   | MiniOneRec trainer — GRPO-based trainer specialized for generative recommendation                              |\n| `configs\u002F`                | YAML configuration files                                            |\n| `evaluate.sh`     | One-click offline Top-K evaluation script                                                        |\n| `evaluate.py`     | Evaluation utilities for computing HR@K and NDCG@K.                                                           |\n| `LogitProcessor.py`                | Logit processor for constrained decoding (Python implementation)                                         |\n| `data.py`                | Data pipeline for SFT and RL training                          |\n| `convert_dataset.py`                | Converts an RQ-trained dataset to the SFT-then-RL format                                            |\n| `convert_dataset_gpr.py`           | GPR-inspired dataset converter: injects simulated heterogeneous tokens (U\u002FE\u002FI\u002FO) to emulate unified input representation                                         |\n| `data\u002Famazon18_data_process.sh`                |    Shell script to filter and preprocess Amazon18 data into an RQ-ready format                                      |\n| `data\u002Famazon18_data_process.py`                |   Python implementation of the Amazon18 data preprocessing pipeline                                        |\n| `data\u002Famazon18_data_process_gpr.py`            |   GPR-inspired Amazon18 preprocessing: extracts heterogeneous features for unified input representation                         |\n| `data\u002Famazon23_data_process.sh`                |    Shell script to filter and preprocess Amazon23 data into an RQ-ready format                                      |\n| `data\u002Famazon23_data_process.py`                |   Python implementation of the Amazon23 data preprocessing pipeline                                        |\n| `rq\u002Ftext2emb\u002Famazon_text2emb.sh`                |   Shell script to generate item embeddings (title + description) via emb_model for the Amazon dataset                                   |\n| `rq\u002Ftext2emb\u002Famazon_text2emb.py`                |   Python implementation of the above embedding generation                                         |\n| `rq\u002Ftext2emb\u002Famazon_text2emb_gpr.py`           |   GPR-inspired text-to-embedding                                 |\n| `rq\u002Fgenerate_indices.py`                |   Generates the SID file after training an RQ-VAE model                                       |\n| `rq\u002Frqvae.sh`                |   Shell script to train RQ-VAE on Amazon item embeddings                        |\n| `rq\u002Frqvae.py`                |   Python implementation of RQ-VAE training                                            |\n| `rq\u002Frqkmeans_faiss.py`                |   Python implementation of RQ-Kmeans training based on faiss                                          |\n| `rq\u002Frqkmeans_constrained.py`                |   Python implementation of Constrained RQ-Kmeans                         |\n| `rq\u002Frqkmeans_constrained.sh`                |   Shell script to train constrained RQ-Kmeans constrained on Amazon item embeddings                        |\n| `rq\u002Frqkmeans_plus.py`                |   Python implementation of RQ-Kmeans+                        |\n| `rq\u002Frqkmeans_plus.sh`                |   Shell script to train RQ-Kmeans+ constrained on Amazon item embeddings                        |\n| `rq\u002Fgenerate_indices_plus.py`                |   Generates the SID file after training an RQ-Kmeans+ model                                       |\n| `rq\u002Fgenerate_indices_plus.sh`                |   Shell script to generate the SID file after training an RQ-Kmeans+ model                                       |\n| `requirements.txt`        | List of Python dependencies                                                                                |\n\n---\n\n## 🚀 Quickstart\n\nUse the pre-trained Industrial\u002FOffice SIDs we provide for a quick start!\nReproduction can be achieved with just 4–8 A100\u002FH100 GPUs.\n\n### 1. Create an isolated Python environment\n\n```bash\nconda create -n MiniOneRec python=3.11 -y\nconda activate MiniOneRec\n```\n\n### 2. Install required packages\n\n```bash\npip install -r requirements.txt\n```\n\n### 3. SFT\n\n```bash\nbash sft.sh\n```\n\n### 4. Recommendation-Oriented RL\n\n```bash\nbash rl.sh\n```\n\n### 5. Run the evaluation bash\n\n```bash\nbash evaluate.sh\n```\n\n---\n\n## 📜 Full Pipeline Walk-through\n\n### 0. Prerequisites\n- GPUs: \u003Ce.g., 4–8 × A100\u002FH100 80 GB or comparable>\n- Python: 3.11\n\n### 1. Environment Setup\n- **1.1 Clone the repo**\n```\ngit clone https:\u002F\u002Fgithub.com\u002FAkaliKong\u002FMiniOneRec.git\ncd MiniOneRec\n```\n- **1.2 Create and activate a conda env**\n```\nconda create -n MiniOneRec python=3.11 -y\nconda activate MiniOneRec\n```\n- **1.3 Install dependencies**\n```\npip install -r requirements.txt\n```\n\n### 2. Data Preparation\n\n- **2.1 Download the raw dataset (Optional)**  \n  Get it from the official page:\n  [Amazon Reviews 2023](https:\u002F\u002Famazon-reviews-2023.github.io\u002F), \n  [Amazon Reviews 2018](https:\u002F\u002Fcseweb.ucsd.edu\u002F~jmcauley\u002Fdatasets\u002Famazon_v2\u002F), \n  [Amazon Reviews 2014](https:\u002F\u002Fcseweb.ucsd.edu\u002F~jmcauley\u002Fdatasets\u002Famazon\u002Flinks.html).\n  Note: The Industrial and Office datasets are included in Amazon 2018; the Amazon 2014 and 2023 versions require slight modifications to our data\u002Famazon18_data_process.py.\n- **2.2 Filter and preprocess**\n```\nbash data\u002Famazon18_data_process.sh \\\n     --dataset  your_dataset_type \\ # e.g. Industrial\n     --user_k 5 \\\n     --item_k 5 \\\n     --st_year 2017 \\\n     --st_month 10 \\\n     --ed_year 2018 \\\n     --ed_month 11 \\\n     --output_path .\u002Fdata\u002FAmazon18\n```\n- **2.3 Encode item text to embeddings**\n```\nbash rq\u002Famazon_text2emb.sh \\\n     --dataset your_dataset_type \\ # e.g., Industrial \n     --root your_processed_dataset_path \\\n     --plm_name qwen \\\n     --plm_checkpoint your_emb_model_path\n```\n\n### 3. SID Construction\n\nChoose either 3.1.1, 3.1.2, 3.1.3 or 3.1.4.\n\n- **3.1.1 Train RQ-VAE on the embeddings**\n```\nbash rq\u002Frqvae.sh \\\n      --data_path xxx\u002Fdata\u002FIndustrial_and_Scientific\u002FIndustrial_and_Scientific.emb-qwen-td.npy \\\n      --ckpt_dir .\u002Foutput\u002FIndustrial_and_Scientific \\\n      --lr 1e-3 \\\n      --epochs 10000 \\\n      --batch_size 20480\n```\n\n- **3.1.2 Train RQ-Kmeans on the embeddings**\n\n```\nconda install faiss-gpu\npython rqkmeans_faiss.py --dataset Industrial_and_Scientific # The RQ-Kmeans method based on semantic embeddings has a relatively high collision rate.\n```\n\n- **3.1.3 Train constrained RQ-Kmeans on the embeddings**\nFor conflicting items, we add an extra layer to perform deduplication; meanwhile, we use a balanced constraint to ensure that the SIDs are evenly distributed.\n```\npip install k_means_constrained\npip install polars\nbash rqkmeans_constrained.sh\n```\n\n- **3.1.4 Train RQ-Kmeans+ on the embeddings**\n```\npip install k_means_constrained\npip install polars\nbash rqkmeans_constrained.sh\nbash rqkmeans_plus.sh\n```\n\n- **3.2 Generate indices(only RQ-VAE & RQ-Kmeans+ needed)**\n```\npython rq\u002Fgenerate_indices.py\n# or\nbash rq\u002Fgenerate_indices_plus.sh\n```\n\n- **3.3 Convert dataset format**\n```\npython convert_dataset.py \\\n     --dataset_name Industrial_and_Scientific \\\n     --data_dir \u002Fpath\u002Fto\u002FIndustrial_and_Scientific \\\n     --output_dir \u002Fpath\u002Fto\u002Fourput_dir \\\n\n```\n\n### 4. SFT\n\n```\nbash sft.sh \\\n     --base_model your_model_path \\\n     --output_dir your_ourput_dir \\\n     --sid_index_path your_.index.json_path \\\n     --item_meta_path your_.item.json_path\n```\n\n### 5. Recommendation-Oriented RL\n> (Optional) For production-scale datasets, considering the cost of reinforcement learning and diminishing marginal returns, you can perform the RL stage using only a relatively small subset on the order of tens of thousands of samples.\n```\nbash rl.sh \\\n     --model_path your_model_path \\\n     --output_dir output_dir \\\n```\n\n### 6. Offline Evaluation\n\n```\nbash evaluate.sh \\\n     --exp_name your_model_path \n```\n\n---\n\n## 🤖 Supported LLM Providers\n\nMiniOneRec supports multiple LLM providers for text enrichment tasks (e.g., user preference and item characteristic extraction). Configure the provider in your `api_info` dictionary:\n\n| Provider | `provider` value | Default Base URL | Example Models |\n|----------|-----------------|------------------|----------------|\n| OpenAI | `\"openai\"` | — | `text-davinci-003` |\n| DeepSeek | `\"deepseek\"` | `https:\u002F\u002Fapi.deepseek.com` | `deepseek-chat` |\n| [MiniMax](https:\u002F\u002Fwww.minimaxi.com) | `\"minimax\"` | `https:\u002F\u002Fapi.minimax.io\u002Fv1` | `MiniMax-M2.7`, `MiniMax-M2.5` |\n\n**Example — using MiniMax:**\n\n```python\napi_info = {\n    \"provider\": \"minimax\",\n    \"api_key_list\": [\"your-minimax-api-key\"],\n    \"base_url\": \"https:\u002F\u002Fapi.minimax.io\u002Fv1\",  # optional, this is the default\n}\nget_res_batch(\"MiniMax-M2.7\", prompt_list, max_tokens=512, api_info=api_info)\n```\n\n---\n\n## 📝 Upcoming Features\n\nWe are actively extending MiniOneRec’s capabilities. The following enhancements are already on our roadmap:\n* ⏱️ **More SID Construction Algorithms**: forthcoming support for R-VQ, RQ-Kmeans, RQ-OPQ, and RQ-VAE-v2 (PLUM).\n* ⚙️ **MiniOneRec-Think**: a module that seamlessly integrates dialogue, reasoning, and personalized recommendation, providing an all-in-one solution for complex interactive scenarios.\n* 🔍 **Broader Dataset Support**: additional popular public datasets, including Yelp, to further validate the generality of our algorithms.\n\n---\n\n## 🏫 Institutions  \u003C!-- omit in toc -->\n\nThis project is developed by the following institutions:\n\n- \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FAkaliKong_MiniOneRec_readme_8b80d4ad727a.png\" width=\"28px\"> [LDS](https:\u002F\u002Fdata-science.ustc.edu.cn\u002F_upload\u002Ftpl\u002F15\u002F04\u002F5380\u002Ftemplate5380\u002Findex.html)\n- \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FAkaliKong_MiniOneRec_readme_d0ba8feabc58.jpg\" width=\"28px\"> [AlphaLab](https:\u002F\u002Falphalab-ustc.github.io\u002Findex.html)\n- \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FAkaliKong_MiniOneRec_readme_bbed2415dfda.jpg\" width=\"28px\"> [NExT](https:\u002F\u002Fwww.nextcenter.org\u002F)\n \n---\n\n## 🧩 Contributing\n\nWe welcome and appreciate all contributions! If you have ideas to improve MiniOneRec, please feel free to submit a pull request (PR).\n\n---\n## 🙏 Acknowledgements\n\nThis repository reuses or adapts portions of code from the following open-source projects. We gratefully acknowledge their authors and contributors:\n\n- [ReRe](https:\u002F\u002Fgithub.com\u002Fsober-clever\u002FReRe)\n- [LC-Rec](https:\u002F\u002Fgithub.com\u002Fzhengbw0324\u002FLC-Rec)\n\n---\n\n## 🔖 Citation \u003C!-- omit in toc -->\n\nIf you find our code\u002Fpaper\u002Fmodel helpful, please consider citing our papers 📝 and staring us ⭐️！\n\n```bib\n@misc{MiniOneRec,\n      title={MiniOneRec: An Open-Source Framework for Scaling Generative Recommendation}, \n      author={Xiaoyu Kong and Leheng Sheng and Junfei Tan and Yuxin Chen and Jiancan Wu and An Zhang and Xiang Wang and Xiangnan He},\n      year={2025},\n      eprint={2510.24431},\n      archivePrefix={arXiv},\n      primaryClass={cs.IR},\n}\n\n@article{ReRe,\n      title={Reinforced Preference Optimization for Recommendation}, \n      author={Junfei Tan and Yuxin Chen and An Zhang and Junguang Jiang and Bin Liu and Ziru Xu and Han Zhu and Jian Xu and Bo Zheng and Xiang Wang},\n      journal={arXiv preprint arXiv:2510.12211},\n      year={2025},\n}\n\n@inproceedings{RecZero,\n      title={Think before Recommendation: Autonomous Reasoning-enhanced Recommender}, \n      author={Xiaoyu Kong and Junguang Jiang and Bin Liu and Ziru Xu and Han Zhu and Jian Xu and Bo Zheng and Jiancan Wu and Xiang Wang},\n      year={2025},\n      booktitle={NeurIPS},\n}\n\n```\n\n---\n\n\u003Cdiv align=\"center\">\nWe welcome contributions from the community! 🤝\n\u003C\u002Fdiv>\n","\u003Cdiv align=\"center\">\n\n\n\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FAkaliKong_MiniOneRec_readme_82a24ab36e77.png\" width=\"500em\" >\u003C\u002Fimg> \n\n**一个用于扩展生成式推荐的开源框架**\n\n![Python](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FPython-3.10+-blue.svg)\n![License](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLicense-Apache--2.0-green.svg)\n\u003Ca href=\"https:\u002F\u002Farxiv.org\u002Fabs\u002F2510.24431\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fstatic\u002Fv1?label=arXiv&message=Paper&color=red\">\u003C\u002Fa>\n\n\u003Ca href=\"https:\u002F\u002Farxiv.org\u002Fabs\u002F2510.24431\">📄 技术报告\u003C\u002Fa> | \u003Ca href=\"https:\u002F\u002Fhuggingface.co\u002Fkkknight\u002FMiniOneRec\">🤗 Huggingface\u003C\u002Fa> | \u003Ca href=\"https:\u002F\u002Fmodelscope.cn\u002Fmodels\u002Fk925238839\u002FMiniOneRec\">🤖  Modelscope\u003C\u002Fa>\n\u003C\u002Fdiv>\n\n**MiniOneRec** 是首个完全开源的 **生成式推荐** 框架，提供涵盖 **SID 构建**、**监督微调 (SFT)** 和面向推荐的 **强化学习 (RL)** 的端到端工作流。\n\n---\n\n## 📢 公告\n\n- 2026-01-04 — 关于基于 Instruct 模型复现的结果与我们报告的指标之间可能存在差异的问题，请检查评估日志中的 CC 指标是否为非零值（参考 calc.py）。若该指标非零，则表明模型仍在生成大量无效商品，约束解码并未成功。我们怀疑此问题可能与 transformer 库等依赖项的版本有关，目前仍在调查原因并寻求通用解决方案。在此期间，您可以将 Instruct 模型切换为基础模型，例如 Qwen2.5-base，以避免该问题。\n\n- 2025-12-04 — 我们更新了新脚本，以支持处理 Amazon23 数据集。\n\n- 2025-12-01 — 我们修复了 data.py 中的一个 bug，该 bug 可能导致 SID–商品对齐任务提前看到答案。这是因为我们之前曾尝试使用部分轨迹来指导完整的 SID–商品生成，但这并不影响模型性能。\n\n- 2025-11-20 — **RQ-Kmeans+** 中的 SID 构建方法已更新（首次提出于 **GPR**，这也是首次开源复现）。\n\n- 2025-11-19 — 我们基于 Accelerate 实现了一种多 GPU 并行的文本转嵌入方法，其效率显著高于原始版本：rq\u002Ftext2emb\u002Famazon_text2emb.py。\n\n- 2025-11-19 — **约束 RQ-Kmeans** 中的 SID 构建方法已更新。\n\n- 2025-11-07 — 感谢您提交的问题！根据您的反馈，我们发布了新的实现。如果您在运行代码时遇到任何问题，请先更新至并参考 **最新版本**。\n  \n- 2025-11-07 — 现在您可以在 SFT 阶段选择冻结 LLM 参数，仅训练新增 SID 词汇表的嵌入。\n\n- 2025-10-31 — 您现在可以直接下载我们 MiniOnRec 模型的 **检查点** 实现。\n\n- 2025-10-31 — **RQ-Kmeans** 中的 SID 构建方法已更新。\n\n---\n\n## 🛠️ 核心技术 \n\u003Cdiv align=\"center\">\n\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FAkaliKong_MiniOneRec_readme_34246ccafd0d.png\" width=100% >\u003C\u002Fimg> \n\u003C\u002Fdiv>\n\n- **SID 构建：MiniOneRec 首先将每件商品转化为一个紧凑且语义上意义明确的标记。** 它将商品的标题和描述拼接在一起，将该句子输入到一个冻结的文本编码器中，然后使用三级 RQ-VAE 对生成的嵌入进行量化。\n\n- **SFT：当所有商品都被重写为 SID 后，模型首先以监督方式训练。** 它将按时间顺序排列的用户历史视为一个标记序列，并通过预测下一个标记的方式，学习生成用户接下来可能消费的商品的 SID。至关重要的是，这一阶段与一组语言对齐目标共同训练，这些目标在自然语言和 SID 空间之间来回映射，使推荐系统能够在离散的商品编码基础上继承大型语言模型中蕴含的世界知识。\n\n- **面向推荐的 RL：在 SFT 之后，MiniOneRec 还会通过基于 GRPO 的面向推荐的 RL 阶段进一步优化。** 对每个提示生成多个候选推荐，其奖励在组内进行归一化以稳定梯度，并通过 KL 正则项使更新后的策略保持接近参考策略。由于动作空间是封闭的商品 SID 列表，系统会切换到约束束搜索，这保证了每个束都是唯一且有效的，从而大大提高了采样效率和多样性。奖励信号本身结合了二元正确性项和排名感知组件，后者会对高概率但错误的商品施加更重的惩罚，并可辅以协同过滤得分。这些机制共同使 MiniOneRec 能够融合密集的语言学知识，构建出高性能、轻量级的生成式推荐系统。\n\n---\n\n## 📊 评估\n\n\u003Cdiv align=\"center\">\n\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FAkaliKong_MiniOneRec_readme_21a96563d566.png\" width=100% >\u003C\u002Fimg> \n\u003C\u002Fdiv>\n\n---\n\n## 🗂️ 仓库概览\n\n| 文件\u002F目录          | 描述                                                                                                   |\n| ------------------------- | ------------------------------------------------------------------------------------------------------------- |\n| `sft.sh`                  | 用于启动监督微调（SFT）阶段的 Shell 脚本                                           |\n| `sft.py`                  | SFT 训练循环的 Python 实现                                                            |\n| `sft_gpr.py`              | 基于 GPR 思想的价值感知微调（VAFT）的 SFT：实现基于模拟物品价值的加权损失                            |\n| `rl.sh`                   | 用于启动强化学习（RL）阶段的 Shell 脚本                             |\n| `rl.py`                   | RL 训练循环的 Python 实现                                              |\n| `rl_gpr.py`               | 基于 GPR 思想的层次增强策略优化（HEPO）的强化学习                                                 |\n| `minionerec_trainer.py`   | MiniOneRec 训练器——基于 GRPO 的生成式推荐专用训练器                              |\n| `configs\u002F`                | YAML 配置文件                                            |\n| `evaluate.sh`     | 一键离线 Top-K 评估脚本                                                        |\n| `evaluate.py`     | 用于计算 HR@K 和 NDCG@K 的评估工具。                                                           |\n| `LogitProcessor.py`                | 用于约束解码的 Logit 处理器（Python 实现）                                         |\n| `data.py`                | SFT 和 RL 训练的数据流水线                          |\n| `convert_dataset.py`                | 将 RQ 训练的数据集转换为先 SFT 后 RL 的格式                                            |\n| `convert_dataset_gpr.py`           | 基于 GPR 思想的数据集转换器：注入模拟的异构标记（U\u002FE\u002FI\u002FO），以模拟统一的输入表示                                         |\n| `data\u002Famazon18_data_process.sh`                |    用于将 Amazon18 数据筛选并预处理为 RQ 可用格式的 Shell 脚本                                      |\n| `data\u002Famazon18_data_process.py`                |   Amazon18 数据预处理流水线的 Python 实现                                        |\n| `data\u002Famazon18_data_process_gpr.py`            |   基于 GPR 思想的 Amazon18 预处理：提取异构特征以实现统一的输入表示                         |\n| `data\u002Famazon23_data_process.sh`                |    用于将 Amazon23 数据筛选并预处理为 RQ 可用格式的 Shell 脚本                                      |\n| `data\u002Famazon23_data_process.py`                |   Amazon23 数据预处理流水线的 Python 实现                                        |\n| `rq\u002Ftext2emb\u002Famazon_text2emb.sh`                |   用于通过嵌入模型为 Amazon 数据集生成商品嵌入向量（标题 + 描述）的 Shell 脚本                                   |\n| `rq\u002Ftext2emb\u002Famazon_text2emb.py`                |   上述嵌入生成的 Python 实现                                         |\n| `rq\u002Ftext2emb\u002Famazon_text2emb_gpr.py`           |   基于 GPR 思想的文本到嵌入向量转换                                 |\n| `rq\u002Fgenerate_indices.py`                |   在训练完 RQ-VAE 模型后生成 SID 文件                                       |\n| `rq\u002Frqvae.sh`                |   用于在 Amazon 商品嵌入上训练 RQ-VAE 的 Shell 脚本                        |\n| `rq\u002Frqvae.py`                |   RQ-VAE 训练的 Python 实现                                            |\n| `rq\u002Frqkmeans_faiss.py`                |   基于 faiss 的 RQ-Kmeans 训练的 Python 实现                                          |\n| `rq\u002Frqkmeans_constrained.py`                |   约束型 RQ-Kmeans 的 Python 实现                         |\n| `rq\u002Frqkmeans_constrained.sh`                |   用于在 Amazon 商品嵌入上训练约束型 RQ-Kmeans 的 Shell 脚本                        |\n| `rq\u002Frqkmeans_plus.py`                |   RQ-Kmeans+ 的 Python 实现                        |\n| `rq\u002Frqkmeans_plus.sh`                |   用于在 Amazon 商品嵌入上训练 RQ-Kmeans+ 的 Shell 脚本                        |\n| `rq\u002Fgenerate_indices_plus.py`                |   在训练完 RQ-Kmeans+ 模型后生成 SID 文件                                       |\n| `rq\u002Fgenerate_indices_plus.sh`                |   用于在训练完 RQ-Kmeans+ 模型后生成 SID 文件的 Shell 脚本                                       |\n| `requirements.txt`        | Python 依赖包列表                                                                                |\n\n---\n\n## 🚀 快速入门\n\n使用我们提供的工业\u002F办公领域预训练 SID，即可快速上手！仅需 4–8 张 A100\u002FH100 显卡即可完成复现。\n\n### 1. 创建隔离的 Python 环境\n\n```bash\nconda create -n MiniOneRec python=3.11 -y\nconda activate MiniOneRec\n```\n\n### 2. 安装所需包\n\n```bash\npip install -r requirements.txt\n```\n\n### 3. SFT\n\n```bash\nbash sft.sh\n```\n\n### 4. 推荐导向的强化学习\n\n```bash\nbash rl.sh\n```\n\n### 5. 运行评估脚本\n\n```bash\nbash evaluate.sh\n```\n\n---\n\n## 📜 全流程详解\n\n### 0. 前置条件\n- 显卡：例如 4–8 张 A100\u002FH100 80 GB 或同等性能显卡\n- Python 版本：3.11\n\n### 1. 环境搭建\n- **1.1 克隆仓库**\n```\ngit clone https:\u002F\u002Fgithub.com\u002FAkaliKong\u002FMiniOneRec.git\ncd MiniOneRec\n```\n- **1.2 创建并激活 Conda 环境**\n```\nconda create -n MiniOneRec python=3.11 -y\nconda activate MiniOneRec\n```\n- **1.3 安装依赖**\n```\npip install -r requirements.txt\n```\n\n### 2. 数据准备\n\n- **2.1 下载原始数据集（可选）**  \n  可从官方页面获取：\n  [Amazon Reviews 2023](https:\u002F\u002Famazon-reviews-2023.github.io\u002F)、\n  [Amazon Reviews 2018](https:\u002F\u002Fcseweb.ucsd.edu\u002F~jmcauley\u002Fdatasets\u002Famazon_v2\u002F)、\n  [Amazon Reviews 2014](https:\u002F\u002Fcseweb.ucsd.edu\u002F~jmcauley\u002Fdatasets\u002Famazon\u002Flinks.html)。\n  注意：工业与办公类数据集包含在 Amazon 2018 中；而 Amazon 2014 和 2023 版本需要对我们提供的 data\u002Famazon18_data_process.py 脚本进行少量修改。\n- **2.2 过滤与预处理**\n```\nbash data\u002Famazon18_data_process.sh \\\n     --dataset  your_dataset_type \\ # 例如 Industrial\n     --user_k 5 \\\n     --item_k 5 \\\n     --st_year 2017 \\\n     --st_month 10 \\\n     --ed_year 2018 \\\n     --ed_month 11 \\\n     --output_path .\u002Fdata\u002FAmazon18\n```\n- **2.3 将商品文本编码为嵌入向量**\n```\nbash rq\u002Famazon_text2emb.sh \\\n     --dataset your_dataset_type \\ # 例如 Industrial \n     --root your_processed_dataset_path \\\n     --plm_name qwen \\\n     --plm_checkpoint your_emb_model_path\n```\n\n### 3. SID 构建\n\n请从 3.1.1、3.1.2、3.1.3 或 3.1.4 中选择一种方法。\n\n- **3.1.1 在嵌入上训练 RQ-VAE**\n```\nbash rq\u002Frqvae.sh \\\n      --data_path xxx\u002Fdata\u002FIndustrial_and_Scientific\u002FIndustrial_and_Scientific.emb-qwen-td.npy \\\n      --ckpt_dir .\u002Foutput\u002FIndustrial_and_Scientific \\\n      --lr 1e-3 \\\n      --epochs 10000 \\\n      --batch_size 20480\n```\n\n- **3.1.2 在嵌入上训练 RQ-Kmeans**\n\n```\nconda install faiss-gpu\npython rqkmeans_faiss.py --dataset Industrial_and_Scientific # 基于语义嵌入的 RQ-Kmeans 方法存在较高的冲突率。\n```\n\n- **3.1.3 在嵌入上训练约束型 RQ-Kmeans**\n对于存在冲突的商品，我们增加一层去重处理；同时采用平衡约束以确保 SID 分布均匀。\n```\npip install k_means_constrained\npip install polars\nbash rqkmeans_constrained.sh\n```\n\n- **3.1.4 在嵌入上训练 RQ-Kmeans+**\n```\npip install k_means_constrained\npip install polars\nbash rqkmeans_constrained.sh\nbash rqkmeans_plus.sh\n```\n\n- **3.2 生成索引（仅 RQ-VAE 和 RQ-Kmeans+ 需要）**\n```\npython rq\u002Fgenerate_indices.py\n# 或\nbash rq\u002Fgenerate_indices_plus.sh\n```\n\n- **3.3 转换数据集格式**\n```\npython convert_dataset.py \\\n     --dataset_name Industrial_and_Scientific \\\n     --data_dir \u002Fpath\u002Fto\u002FIndustrial_and_Scientific \\\n     --output_dir \u002Fpath\u002Fto\u002Fourput_dir \\\n\n```\n\n### 4. SFT\n\n```\nbash sft.sh \\\n     --base_model your_model_path \\\n     --output_dir your_ourput_dir \\\n     --sid_index_path your_.index.json_path \\\n     --item_meta_path your_.item.json_path\n```\n\n### 5. 推荐导向的强化学习\n> （可选）对于生产规模的数据集，考虑到强化学习的成本以及边际收益递减，可以仅使用数万条样本的较小子集来执行强化学习阶段。\n```\nbash rl.sh \\\n     --model_path your_model_path \\\n     --output_dir output_dir \\\n```\n\n### 6. 离线评估\n\n```\nbash evaluate.sh \\\n     --exp_name your_model_path \n```\n\n---\n\n## 🤖 支持的 LLM 提供商\n\nMiniOneRec 支持多种 LLM 提供商用于文本增强任务（例如用户偏好和商品特征提取）。请在您的 `api_info` 字典中配置提供商：\n\n| 提供商 | `provider` 值 | 默认基础 URL | 示例模型 |\n|----------|-----------------|------------------|----------------|\n| OpenAI | `\"openai\"` | — | `text-davinci-003` |\n| DeepSeek | `\"deepseek\"` | `https:\u002F\u002Fapi.deepseek.com` | `deepseek-chat` |\n| [MiniMax](https:\u002F\u002Fwww.minimaxi.com) | `\"minimax\"` | `https:\u002F\u002Fapi.minimax.io\u002Fv1` | `MiniMax-M2.7`, `MiniMax-M2.5` |\n\n**示例 — 使用 MiniMax：**\n\n```python\napi_info = {\n    \"provider\": \"minimax\",\n    \"api_key_list\": [\"your-minimax-api-key\"],\n    \"base_url\": \"https:\u002F\u002Fapi.minimax.io\u002Fv1\",  # 可选，默认值\n}\nget_res_batch(\"MiniMax-M2.7\", prompt_list, max_tokens=512, api_info=api_info)\n```\n\n---\n\n## 📝 即将推出的功能\n\n我们正在积极扩展 MiniOneRec 的功能。以下改进已列入我们的路线图：\n* ⏱️ **更多 SID 构建算法**：即将支持 R-VQ、RQ-Kmeans、RQ-OPQ 和 RQ-VAE-v2 (PLUM)。\n* ⚙️ **MiniOneRec-Think**：一个无缝集成对话、推理和个性化推荐的模块，为复杂的交互场景提供一体化解决方案。\n* 🔍 **更广泛的数据集支持**：还将加入 Yelp 等热门公开数据集，进一步验证我们算法的通用性。\n\n---\n\n## 🏫 合作机构  \u003C!-- omit in toc -->\n\n本项目由以下机构共同开发：\n\n- \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FAkaliKong_MiniOneRec_readme_8b80d4ad727a.png\" width=\"28px\"> [LDS](https:\u002F\u002Fdata-science.ustc.edu.cn\u002F_upload\u002Ftpl\u002F15\u002F04\u002F5380\u002Ftemplate5380\u002Findex.html)\n- \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FAkaliKong_MiniOneRec_readme_d0ba8feabc58.jpg\" width=\"28px\"> [AlphaLab](https:\u002F\u002Falphalab-ustc.github.io\u002Findex.html)\n- \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FAkaliKong_MiniOneRec_readme_bbed2415dfda.jpg\" width=\"28px\"> [NExT](https:\u002F\u002Fwww.nextcenter.org\u002F)\n \n---\n\n## 🧩 贡献说明\n\n我们欢迎并感谢所有贡献！如果您有任何改进 MiniOneRec 的想法，请随时提交拉取请求（PR）。\n\n---\n## 🙏 致谢\n\n本仓库复用或改编了以下开源项目的部分代码。我们衷心感谢这些项目的作者和贡献者：\n\n- [ReRe](https:\u002F\u002Fgithub.com\u002Fsober-clever\u002FReRe)\n- [LC-Rec](https:\u002F\u002Fgithub.com\u002Fzhengbw0324\u002FLC-Rec)\n\n---\n\n## 🔖 引用 \u003C!-- omit in toc -->\n\n如果您觉得我们的代码\u002F论文\u002F模型有所帮助，请考虑引用我们的论文 📝 并为我们点亮 ⭐️！\n\n```bib\n@misc{MiniOneRec,\n      title={MiniOneRec: 一个用于扩展生成式推荐的开源框架}, \n      author={Xiaoyu Kong 和 Leheng Sheng 和 Junfei Tan 和 Yuxin Chen 和 Jiancan Wu 和 An Zhang 和 Xiang Wang 和 Xiangnan He},\n      year={2025},\n      eprint={2510.24431},\n      archivePrefix={arXiv},\n      primaryClass={cs.IR},\n}\n\n@article{ReRe,\n      title={用于推荐的强化偏好优化}, \n      author={Junfei Tan 和 Yuxin Chen 和 An Zhang 和 Junguang Jiang 和 Bin Liu 和 Ziru Xu 和 Han Zhu 和 Jian Xu 和 Bo Zheng 和 Xiang Wang},\n      journal={arXiv 预印本 arXiv:2510.12211},\n      year={2025},\n}\n\n@inproceedings{RecZero,\n      title={先思考再推荐：自主推理增强型推荐系统}, \n      author={Xiaoyu Kong 和 Junguang Jiang 和 Bin Liu 和 Ziru Xu 和 Han Zhu 和 Jian Xu 和 Bo Zheng 和 Jiancan Wu 和 Xiang Wang},\n      year={2025},\n      booktitle={NeurIPS},\n}\n\n```\n\n---\n\n\u003Cdiv align=\"center\">\n我们欢迎社区的贡献！🤝\n\u003C\u002Fdiv>","# MiniOneRec 快速上手指南\n\nMiniOneRec 是首个完全开源的**生成式推荐**框架，提供从语义 ID（SID）构建、监督微调（SFT）到面向推荐的强化学习（RL）的全流程端到端解决方案。\n\n## 1. 环境准备\n\n### 系统要求\n- **操作系统**: Linux (推荐)\n- **Python 版本**: 3.10+ (官方示例使用 3.11)\n- **GPU 资源**: 复现建议配置 4–8 张 A100\u002FH100 (80GB) 或同等算力显卡\n- **依赖库**: PyTorch, Transformers, Accelerate, FAISS 等\n\n### 前置检查\n确保已安装 `conda` 和 `git`。国内用户建议配置 pip 国内镜像源以加速下载。\n\n## 2. 安装步骤\n\n### 2.1 克隆仓库\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002FAkaliKong\u002FMiniOneRec.git\ncd MiniOneRec\n```\n\n### 2.2 创建虚拟环境\n```bash\nconda create -n MiniOneRec python=3.11 -y\nconda activate MiniOneRec\n```\n\n### 2.3 安装依赖\n建议使用国内镜像源加速安装：\n```bash\npip install -r requirements.txt -i https:\u002F\u002Fpypi.tuna.tsinghua.edu.cn\u002Fsimple\n```\n\n> **注意**：若需处理 Amazon 数据集或进行 SID 构建，请确保已安装 `faiss-gpu` 及相关 NLP 模型依赖。\n\n## 3. 基本使用\n\n本指南演示如何使用官方提供的预训练 Industrial\u002FOffice 语义 ID (SIDs) 进行快速启动和复现。\n\n### 3.1 监督微调 (SFT)\n运行以下脚本启动 SFT 阶段，模型将学习根据用户历史序列预测下一个商品的 SID。\n```bash\nbash sft.sh\n```\n\n### 3.2 面向推荐的强化学习 (RL)\nSFT 完成后，运行以下脚本基于 GRPO 算法进行强化学习微调，以优化推荐排序和多样性。\n```bash\nbash rl.sh\n```\n\n### 3.3 模型评估\n执行一键离线评估脚本，计算 HR@K 和 NDCG@K 指标。\n```bash\nbash evaluate.sh\n```\n\n---\n\n### 💡 进阶提示\n- **数据集准备**：若需从头处理数据（如 Amazon23），请参考 `data\u002F` 目录下的预处理脚本（如 `amazon23_data_process.sh`）。\n- **SID 构建**：若需自定义商品编码，可使用 `rq\u002F` 目录下的工具链（文本向量化 -> RQ-VAE\u002FKmeans 聚类 -> 生成 SID）。\n- **已知问题**：若在使用 Instruct 模型时遇到生成大量无效物品的问题（评估日志中 CC 指标非零），建议暂时切换至 Base 模型（如 `Qwen2.5-base`）以规避约束解码兼容性问题。","某大型电商平台的算法团队正致力于升级其推荐系统，试图利用大语言模型的语义理解能力来提升长尾商品的点击率。\n\n### 没有 MiniOneRec 时\n- **语义鸿沟难跨越**：传统推荐模型仅依赖物品 ID 进行协同过滤，无法理解商品标题和描述中的深层语义，导致新上架或冷门商品难以被准确推荐。\n- **生成式推荐落地难**：团队想尝试前沿的“生成式推荐”技术，但缺乏从物品编码（SID 构建）到强化学习（RL）的全流程开源框架，自研成本极高且周期漫长。\n- **训练效率低下**：在处理海量商品库时，缺乏高效的文本向量化与量化编码方案，多 GPU 并行处理能力不足，数据预处理耗时数天。\n- **模型幻觉严重**：直接微调大模型进行推荐时，常生成不存在的物品 ID，缺乏有效的约束解码机制来保证输出结果的合法性。\n\n### 使用 MiniOneRec 后\n- **语义化物品编码**：利用 MiniOneRec 的 RQ-VAE 技术，将商品标题和描述转化为紧凑的语义 token（SID），让模型能像理解自然语言一样理解商品特征。\n- **端到端全流程支持**：直接复用其提供的 SID 构建、监督微调（SFT）及推荐导向强化学习（RL）的一站式工作流，将原本数月的研发周期缩短至数周。\n- **高效并行处理**：借助基于 Accelerate 的多 GPU 并行文本嵌入脚本，大幅提升了大规模数据集（如 Amazon23）的处理效率，数据准备时间减少 80%。\n- **精准约束生成**：通过内置的约束解码机制和语言对齐目标，彻底解决了模型生成无效物品 ID 的问题，确保推荐结果真实可点击。\n\nMiniOneRec 通过打通语义理解与离散物品编码的壁垒，让企业能以最低成本快速部署具备世界知识的高精度生成式推荐系统。","https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FAkaliKong_MiniOneRec_1093ab08.png","AkaliKong","Xiaoyu Kong","https:\u002F\u002Foss.gittoolsai.com\u002Favatars\u002FAkaliKong_dea93d8f.jpg","I am Xiaoyu Kong, a PhD student at the University of Science and Technology of China (USTC), focusing on large language models (LLMs) and recommender systems.","University of Science and Technology of China","Hefei, China",null,"https:\u002F\u002Fgithub.com\u002FAkaliKong",[81,85],{"name":82,"color":83,"percentage":84},"Python","#3572A5",98.1,{"name":86,"color":87,"percentage":88},"Shell","#89e051",1.9,1457,205,"2026-04-18T10:32:59","Apache-2.0",4,"Linux","必需，推荐 4-8 张 NVIDIA A100 或 H100 (80GB 显存)，用于复现完整流程","未说明",{"notes":98,"python":99,"dependencies":100},"1. 官方推荐使用 Python 3.11 创建隔离环境。2. 复现完整训练流程建议配置 4-8 张 A100\u002FH100 GPU。3. 存在依赖版本兼容性问题：若使用 Instruct 模型评估时出现大量无效生成（CC 指标非零），可能是 transformer 等库版本导致，建议暂时切换至 Base 模型（如 Qwen2.5-base）规避。4. 支持 Amazon18 和 Amazon23 数据集，需自行下载原始数据并运行预处理脚本。5. 提供预训练的 SID 和模型检查点以供快速启动。","3.10+",[101,102,103,104,105],"torch","transformers","accelerate","faiss","datasets",[35,14],[108,109,110,111,112,113,114,115,116,117],"generative-ai","generative-recommendation","generative-recommenders","large-language-model","large-language-models","llm","recommendation","recommendation-system","recommender-system","scaling-laws","2026-03-27T02:49:30.150509","2026-04-19T09:39:18.353034",[121,126,131,135,140,145],{"id":122,"question_zh":123,"answer_zh":124,"source_url":125},42353,"强化学习（RL）训练后模型性能相比 SFT 基线下降，可能原因是什么？如何优化？","性能下降的主要原因可能是代码实现与论文描述存在不一致，特别是在对齐阶段。根据论文附录，SFT 阶段应使用'用户偏好总结（User Preference Summarization）'进行对齐，但直接克隆的代码库中可能未包含此逻辑或实现相反（例如 description2sid 的对齐任务在论文中仅在 SFT 阶段进行，而代码中可能在 RL 阶段进行了错误处理）。建议仔细对照论文附录检查代码，确认是否缺失了关键的对齐步骤或参数配置被注释\u002F替换，并尝试手动修复这些差异以复现论文效果。","https:\u002F\u002Fgithub.com\u002FAkaliKong\u002FMiniOneRec\u002Fissues\u002F58",{"id":127,"question_zh":128,"answer_zh":129,"source_url":130},42354,"运行 rl.sh 脚本时报错 ImportError: cannot import name 'RLTitle2Sid_2LayerDataset'，如何解决？","该错误是因为代码版本过旧。`RLTitle2Sid_2LayerDataset` 和 `RLTitle2Sid_1LayerDataset` 是早期探索性研究中使用的类，已在最新版本的 `rl.py` 中被移除。解决方法是更新代码库到最新版本（git pull），并在新的 `rl.sh` 脚本中运行。在新版本中，许多之前为空的参数已在 shell 脚本中设置了显式值，直接使用更新后的脚本即可正常运行，无需手动修改 Python 代码中的导入项。","https:\u002F\u002Fgithub.com\u002FAkaliKong\u002FMiniOneRec\u002Fissues\u002F10",{"id":132,"question_zh":133,"answer_zh":134,"source_url":125},42355,"在使用 RQ-VAE 生成的 SID 进行实验时，效果与作者报告的结果有差距，原因可能是什么？","这种差距通常是由“对齐问题”引起的。论文附录明确指出，在 SFT 对齐阶段会使用“用户偏好总结（User Preference Summarization）”技术，但直接从 GitHub 克隆的默认代码库中往往没有实现这一特定的对齐逻辑。此外，代码中可能存在其他与论文描述不一致的地方（如某些功能被注释或替换）。建议用户深入对比论文附录与源代码，重点检查并补全缺失的对齐步骤，特别是针对 SFT 阶段的处理逻辑。",{"id":136,"question_zh":137,"answer_zh":138,"source_url":139},42356,"Codebook 的容量（2^24）远超数据集中的物品总数，这对生成 SID 有什么影响？覆盖率如何分析？","虽然 Codebook 的理论容量（3 层 x 256 向量 = 2^24）远大于数据集物品数量，但这正是分层量化设计的特性，旨在提供足够的表达空间以覆盖潜在的物品特征分布。在实际生成 SID 时，模型只会激活其中一小部分码本向量。关于具体的覆盖率分析和独立编码率细节，通常取决于训练过程中码本的收敛情况。如果复现时发现覆盖率异常低，可能需要检查训练超参数或码本初始化策略，确保模型能够充分利用码本空间来表示物品特征。","https:\u002F\u002Fgithub.com\u002FAkaliKong\u002FMiniOneRec\u002Fissues\u002F1",{"id":141,"question_zh":142,"answer_zh":143,"source_url":144},42357,"迁移能力实验中，Qwen-Text 模型如何通过标题预测下一个物品并与具体物品关联？","在迁移能力实验中，Qwen-Text 模型通过预测下一个物品的标题文本来进行推荐。为了将生成的标题文本关联到具体的物品 ID，通常需要利用物品标题的嵌入向量（embeddings）进行相似度检索。即：模型生成标题 -> 计算该标题嵌入与候选物品标题嵌入的相似度 -> 返回相似度最高的物品 ID 作为推荐结果。这种机制允许纯文本模型在没有直接输出 ID 的情况下完成推荐任务。","https:\u002F\u002Fgithub.com\u002FAkaliKong\u002FMiniOneRec\u002Fissues\u002F36",{"id":146,"question_zh":147,"answer_zh":148,"source_url":144},42358,"Qwen-SID 模型在没有额外微调的情况下，是如何理解 SID（序列 ID）并进行工作的？","Qwen-SID 模型之所以能在无额外微调的情况下理解 SID，是因为 SID 本质上是一种离散化的语义标识符，其构建过程（如通过 RQ-VAE）已经将物品的语义信息编码进了 ID 结构中。模型在预训练阶段已经具备了处理此类离散令牌的能力。如果效果不佳，可能需要检查是否需要对模型进行特定的扩展或适配，以更好地映射 SID 空间与模型内部的词汇表空间，确保模型能正确解析这些特殊 ID 的含义。",[]]