recsys-pipeline-architect

Recsys Pipeline Architect

一个用于构建可组合推荐、排序和 feed 管道的 spec-and-scaffold 技能。它编码了 xAI 开源的 For You 算法（Apache 2.0）所推广的六阶段模式，并将其应用于任何“为（用户、上下文）返回 top K”的问题。

概述

生产环境中的大多数“推荐系统”并不是奇异的机器学习——它们是管道：从一个或多个来源获取候选，用元数据丰富它们，剔除不合格项，对其余项打分，排序并选出 top K，然后触发异步副作用。这个模式是通用的。评分函数和条目会变；管道形态不会变。

本技能是该模式的独立重新实现（MIT）——未复制原始项目中的任何代码。

何时使用本技能

• 构建任何返回“某用户/上下文下的 top K 条目”的系统
• 设计或重构个性化 feed（内容、搜索结果、通知）
• 将 LLM/ML 评分器包装进恰当的管道配套中（来源、补全、过滤器、副作用）
• 添加带可调权重的多动作预测（而非单一相关性分数）
• 构建 RAG 检索重排序器（廉价检索 → 昂贵重排）
• 设计任务优先级排序器或告警分诊系统

六阶段框架

#	阶段	职责	并行？
1	Source	从一个或多个来源获取候选	是——多个来源并行运行
2	Hydrator	用过滤和评分所需的元数据丰富候选	是——相互独立的 hydrator 并行运行
3	Filter	剔除不合格候选（已屏蔽、已过期、重复、不符合资格）	串行——每个过滤器看到的条目更少
4	Scorer	为每个存活的候选分配一个或多个分数	串行——后续 scorer 能看到先前的分数
5	Selector	按最终分数排序，返回 top K	单一操作
6	SideEffect	缓存、记录日志、发出事件、更新已服务历史	异步——绝不能阻塞响应

为何是这一确切顺序

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

被调用时的工作流

引导用户完成八个步骤：

1. 明确用例（仅当缺失时进行一轮、三个问题）：被排序的条目、输入上下文、语言/运行时
2. 识别候选来源（通常是网内 + 网外，但单一来源也有效）
3. 列出所需的补全——对每个过滤器和 scorer，它需要哪些来源未提供的数据？
4. 列出过滤器——廉价先于昂贵，通用先于用户特定（重复、自身、时效、屏蔽/静音、先前已服务、资格）
5. 设计 scorer 链——主 ML/启发式 → 组合器（带权重的多动作）→ 多样性 → 业务规则
6. Selector——按最终分数降序排序，取 top K（或分层混合）
7. SideEffects——缓存已服务 ID、发出曝光事件、更新计数器、记录分析；全部 fire-and-forget
8. 在用户的技术栈中生成脚手架

需要提出的关键权衡

绝不要在以下问题上默默采用默认值——它们是伪装成技术问题的产品决策。

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

• 单一分数： 训练一个模型来预测相关性。要改变行为 → 重新训练。
• 多动作： 为多个动作预测 P(action)（P(read)、P(like)、P(share)、P(skip)、P(report)），在服务时用权重组合。要改变行为 → 改变权重。无需重新训练。

X For You 算法使用多动作，同时带有正权重和负权重。当用户期望频繁调优时，推荐使用多动作。

2. 候选隔离 vs 联合打分

• 隔离： 每个候选独立打分。确定性、可缓存。
• 联合： 候选在打分时相互关注（例如对整个批次使用 transformer）。表达力更强，但跨批次非确定性。

默认使用隔离。只有在有特定理由时（例如显式的批次感知多样性）才使用联合。

3. 在线 vs 离线批处理

• 请求时（在线）： 流水线在每次请求时运行。延迟预算：100–300ms。
• 预计算（离线批处理）： 流水线周期性运行，结果被缓存。延迟更低，新鲜度更低。
• 混合： 候选召回离线，排序在线。

硬性规则

1. 不要编造基准数字。 “这个有多快？” → “取决于工作负载，自己跑一下。”
2. 归属纪律。 将该模式归属为“由 xAI 开源的 For You 算法推广” / github.com/xai-org/x-algorithm（Apache 2.0）。
3. 不得使用商标。 不要将用户的产物命名为“X-like”，也不要使用“For You”品牌。使用中性名称：“candidate pipeline”、“feed pipeline”、“ranking pipeline”。
4. 明示权衡。 多动作 vs 单一、隔离 vs 联合、在线 vs 离线 —— 绝不静默采用默认值。
5. 生成的脚手架必须能运行。 不允许用伪代码冒充代码。
6. 过滤顺序很重要。 便宜的在前，昂贵的在后。通用的在前，用户特定的在后。
7. 副作用绝不阻塞。 用即发即忘模式包装（goroutines / 不 await 的 promises / asyncio tasks）。

反模式

• ❌ 在过滤之前打分（对将被丢弃的候选浪费算力）
• ❌ 同步副作用（缓存写入 / 曝光上报阻塞响应）
• ❌ 当产品需要多目标调优时，只使用单一的“相关性”分数
• ❌ 将联合打分作为默认（非确定性、不可缓存、无法与重排序组合）
• ❌ “仅供说明”的伪代码 —— 脚手架必须真正能运行

常见用例

内容信息流（Strapi v5 插件，TypeScript）

用户有一个包含 5 万篇文章的 CMS，想要一个个性化的“for you”信息流。走完 8 个步骤 → 生成一个 Strapi 插件脚手架，包含多动作打分、作者多样性、标准过滤器、异步副作用通道。

RAG 检索重排序器（Python 异步）

用户的 RAG 从向量数据库返回 top-50 块，想要用更昂贵的打分器进行重排序并返回 top-5。单源流水线，带打分器链（便宜的召回 + 昂贵的重排序）。

任务优先级排序器（FastAPI 服务）

用户有一个传入任务建议的队列，想要根据“这个用户接下来应该做什么”并考虑其过往模式来进行排序。物品反转为（任务而非内容），同样的形态适用。

通知分诊（离线批处理作业）

用户想要一个每日摘要，从过去 24 小时的队列中挑选 top 10。离线批处理流水线。来源 = 队列，过滤器 = 时效/去重/资格，打分器 = 紧迫性 × 用户亲和力，选择器 = top 10，副作用 = 发送邮件（仍然是异步的）。

上游

本技能是上游仓库的单文件适配器，该仓库提供 5 个按需加载的参考文档和 3 个可运行的示例脚手架（Strapi v5 / Go / Python — 每一个都通过了其测试套件，共 9/9 个测试全部通过）。

• 上游： https://github.com/mturac/recsys-pipeline-architect
• 版本： v0.1.0 (MIT)
• 参考资料： 4 种语言的接口（TS/Go/Python/Rust）、多动作评分、候选隔离、过滤器实用手册（12 种模式）、评分器实用手册
• 跨平台安装： npx skills add mturac/recsys-pipeline-architect