recsys-pipeline-architect

recsys-pipeline-architect

用于构建可组合推荐、排序和信息流管道的规格与脚手架技能。它编码了六阶段模式 —— Source -> Hydrator -> Filter -> Scorer -> Selector -> SideEffect —— 由 xAI 开源的 For You 算法（Apache 2.0）推广。此技能是该模式的独立重新实现（MIT）—— 未从原始代码复制任何代码。

上游：https://github.com/mturac/recsys-pipeline-architect

何时使用

• 用户想要构建任何"为用户/上下文选择前 K 个项目"的系统
• 用户问"我该如何对 X 排序"或描述信息流/个性化问题
• 用户有评分函数并需要围绕它的管道基础设施
• 用户想要从单个相关性分数迁移到带可调权重的多动作预测
• 用户正在包装 LLM/ML 评分器并需要过滤器、水合器、副作用和其技术栈（TypeScript / Go / Python）中的可运行脚手架
• 触发词："推荐系统"、"信息流算法"、"排序管道"、"for you feed"、"候选管道"、"内容推荐器"、"recsys 的管道架构"、"RAG 检索重排序器"

何时不使用

• 模型架构工作（transformer 设计、双塔检索、嵌入训练）—— 此技能是模型周围的基础设施，不是模型本身
• 纯 ML 训练管道 —— 评分函数是用户的责任
• 运营已部署的管道（监控、自动扩展）—— 超出范围

六阶段框架

#	阶段	任务	可并行？
1	Source	从一个或多个来源获取候选者	是 —— 多个来源并行运行
2	Hydrator	用过滤和评分所需的元数据丰富每个候选者	是 —— 独立的水合器并行运行
3	Filter	丢弃不应显示的候选者（已阻止、已过期、重复、不合格）	顺序 —— 每个过滤器看到更少的项目
4	Scorer	为每个存活的候选者分配一个或多个分数	顺序 —— 后续评分器看到前面的分数
5	Selector	按最终分数排序，返回前 K 个	单操作
6	SideEffect	缓存已服务的 ID、记录展示、发出事件、更新计数器	异步 —— 绝不能阻塞响应

为什么是这个精确顺序

• 来源在水合之前：在付费丰富之前知道有哪些候选者
• 水合在过滤之前：许多过滤器需要来源未提供的元数据
• 过滤在评分之前：评分是昂贵的阶段；先丢弃不合格的
• 评分器链（不是单个评分器）：真实系统组合 ML 评分 + 多样性重排序 + 业务规则
• 选择器在评分之后：保持评分确定性和可缓存
• 副作用在最后且异步：副作用绝不能阻塞用户响应

调用时的工作流

引导用户完成这八个步骤：

1. 明确用例（一轮，三个问题）：排序的项目？输入上下文？语言/运行时？
2. 识别候选来源：通常是网络内（关注/拥有/订阅）+ 网络外（ML 检索 / 趋势 / 相似推荐）
3. 列出必需的水合：对于每个过滤器和评分器，它需要什么来源未提供的数据？
4. 列出过滤器：重复、自身、年龄、阻止/静音、已展示、资格。顺序重要 —— 便宜的在昂贵的之前。
5. 设计评分器链：主评分（ML）-> 组合器（带权重的多动作）-> 多样性 -> 业务规则
6. 选择器：按最终分数降序排序，取前 K 个（或网络内/网络外的分层混合）
7. 副作用：缓存已服务的 ID、发出展示事件、更新计数器、记录分析 —— 全部即发即弃
8. 在用户的技术栈中生成脚手架

要展示的关键权衡（不要静默默认）

1. 单一分数 vs 多动作预测

• 单一分数：训练一个模型预测相关性。要改变行为 -> 重新训练。
• 多动作：为多个动作（阅读、点赞、分享、跳过、报告）预测 P(action)，在服务时用权重组合。要改变行为 -> 改变权重。无需重新训练。

X For You 系统使用带正向和负向权重的多动作。当用户期望频繁调整时推荐多动作。

2. 评分中的候选隔离

• 隔离的：每个候选者独立评分。确定性，可缓存。
• 联合的：候选者在评分期间相互关注（例如，批次的 transformer）。更具表达力但跨批次不确定。

默认为隔离。仅当有特定原因时使用联合（例如，明确的批次感知多样性）。

3. 在线 vs 离线

• 请求时（在线）：管道在每个请求上运行。延迟预算：100-300ms。默认。
• 预计算（离线批处理）：管道定期运行，结果缓存。更低延迟，更低新鲜度。
• 混合：候选检索离线，排名在线。

硬性规则

1. 不要编造基准数据。 "快多少？" -> "取决于工作负载，自己跑。"
2. 归属纪律。 当引用该模式时，归属为"由 xAI 开源的 For You 算法推广" / github.com/xai-org/x-algorithm（Apache 2.0）。
3. 不使用商标。 不要将用户的产物命名为"X-like"或使用"For You"品牌。模式是免费的；品牌不是。建议命名："候选管道"、"信息流管道"、"排序管道"、"recsys 管道"。
4. 展示权衡。 多动作 vs 单一、隔离 vs 联合、在线 vs 离线 —— 永远不要静默默认。
5. 生成的脚手架必须能运行。 不允许伪代码冒充代码。
6. 过滤器顺序重要。 便宜的在昂贵的之前。通用的在用户特定的之前。
7. 副作用永不阻塞。 包装在即发即弃模式中（goroutines / 不 await 的 promise / asyncio 任务）。

反模式

• 评分在过滤之前（浪费计算在将被丢弃的候选者上）
• 同步副作用（缓存写入 / 展示发出阻塞响应）
• 当产品需要为多个目标调优时使用单一"相关性"分数（参与度 vs 安全 vs 多样性 vs 广告）
• 默认联合评分（不确定、更难缓存、不与重排序阶段组合）
• 生成伪代码"用于说明" —— 脚手架必须实际能运行

上游内容

https://github.com/mturac/recsys-pipeline-architect 的上游仓库包含：

• 完整的 SKILL.md 带完整 8 步工作流
• 5 个按需加载的参考文档：4 种语言的接口（TS/Go/Python/Rust）、多动作评分模式、候选隔离、过滤器手册（12 种模式）、评分器手册（加权和、MMR、多样性惩罚、位置去偏）
• 3 个可运行的示例脚手架，每个都在其测试套件上绿色通过：
  • Strapi v5 插件（TypeScript / Jest — 3/3 通过）
  • Zentra 兼容管道（Go 泛型 — 3/3 通过）
  • PMAI 任务优先级排序器（Python / FastAPI / pytest — 3/3 通过）
• v0.1.0 版本已标记
• MIT 许可；模式归属 xAI X For You 算法（Apache 2.0）

通过 skills.sh 安装：npx skills add mturac/recsys-pipeline-architect