recsys-pipeline-architect

Recsys Pipeline Architect

組み合わせ可能なレコメンデーション、ランキング、フィードのパイプラインを構築するための仕様・スキャフォールドスキルです。xAI がオープンソース化した For You アルゴリズム（Apache 2.0）で広まった 6 段階のパターンを体系化し、あらゆる「(ユーザー, コンテキスト) に対する top K」問題に適用します。

概要

本番環境にあるほとんどの「レコメンデーションシステム」は、特殊な ML ではありません。それらはパイプラインです。1 つ以上のソースから候補を取得し、メタデータで enrich し、対象外のものを除外し、残りをスコアリングし、ソートして top K を選び、その後で非同期の副作用を発火します。このパターンは普遍的です。スコアリング関数とアイテムは変わりますが、パイプラインの形は変わりません。

このスキルはこのパターンの独立した再実装です（MIT）。元のコードは一切コピーしていません。

このスキルを使う場面

• 「ユーザー/コンテキストに対する top K アイテム」を返すあらゆるシステムの構築
• パーソナライズされたフィード（コンテンツ、検索結果、通知）の設計またはリファクタリング
• LLM/ML スコアラーを適切なパイプラインの配管（ソース、ハイドレーション、フィルター、副作用）に組み込む
• 単一の関連度スコアではなく、調整可能な重みを持つマルチアクション予測を追加する
• RAG の検索リランカー（安価な検索 → 高コストなリランク）の構築
• タスクの優先順位付けやアラートトリアージシステムの設計

6 段階フレームワーク

#	段階	役割	並列?
1	ソース	1 つ以上の起点から候補を取得する	はい — 複数のソースが並列で動作
2	ハイドレーター	フィルタリングとスコアリングに必要なメタデータで候補を enrich する	はい — 独立したハイドレーターが並列で動作
3	フィルター	対象外の候補を除外する（ブロック済み、期限切れ、重複、対象外）	逐次 — 各フィルターはより少ないアイテムを見る
4	スコアラー	生き残った各候補に 1 つ以上のスコアを割り当てる	逐次 — 後続のスコアラーは前のスコアを見る
5	セレクター	最終スコアでソートし、top K を返す	単一操作
6	副作用	キャッシュ、ログ、イベントの発行、served-history の更新	非同期 — レスポンスを絶対にブロックしてはならない

なぜこの正確な順序なのか

• ハイドレーションの前にソース: enrich のコストを払う前に、どの候補が存在するかを知る
• フィルタリングの前にハイドレーション: 多くのフィルターはソースが提供しなかったメタデータを必要とする
• スコアリングの前にフィルタリング: スコアリングは高コストな段階 — 対象外のものを先に除外する
• スコアラーチェーン（単一スコアラーではない）: 実際のシステムは ML スコアリング + 多様性リランキング + ビジネスルールを組み合わせる
• スコアリングの後にセレクター: スコアリングを決定的かつキャッシュ可能に保つ
• 副作用は最後かつ非同期: 副作用はユーザーレスポンスを絶対にブロックしてはならない

呼び出されたときのワークフロー

ユーザーを 8 つのステップに沿って案内します:

1. ユースケースを明確化する（1 ラウンド、不足している場合のみ 3 つの質問）: ランキング対象のアイテム、入力コンテキスト、言語/ランタイム
2. 候補ソースを特定する（通常は in-network + out-of-network、ただし単一ソースも有効）
3. 必要なハイドレーションを列挙する — 各フィルターとスコアラーについて、ソースが提供しなかったどのデータを必要とするか?
4. フィルターを列挙する — 高コストの前に安価なもの、ユーザー固有の前に普遍的なもの（重複、自分自身、経過時間、ブロック/ミュート、過去に配信済み、適格性）
5. スコアラーチェーンを設計する — プライマリ ML/ヒューリスティック → コンバイナー（重み付きマルチアクション）→ 多様性 → ビジネスルール
6. セレクター — 最終スコアで降順にソートし、top K を取得する（または層別ミックス）
7. 副作用 — 配信済み ID をキャッシュし、インプレッションイベントを発行し、カウンターを更新し、アナリティクスをログに記録する。すべて fire-and-forget
8. ユーザーのスタックでスキャフォールドを生成する

表面化すべき主要なトレードオフ

これらについて暗黙のうちにデフォルトを選んではいけません — これらは技術的な決定に見えて、実は製品上の決定です。

1. 単一スコア vs マルチアクション予測

• 単一スコア: 関連性を予測するモデルを 1 つ学習させます。動作を変えるには → 再学習が必要です。
• マルチアクション: 多数のアクション（P(read)、P(like)、P(share)、P(skip)、P(report)）について P(action) を予測し、配信時に重み付けして統合します。動作を変えるには → 重みを変更するだけです。再学習は不要です。

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. 副作用は決してブロックしないこと。 fire-and-forget パターン（goroutine / await なしの promise / asyncio タスク）でラップしてください。

アンチパターン

• ❌ フィルタリング前のスコアリング（破棄される候補に計算資源を浪費します）
• ❌ 同期的な副作用（キャッシュ書き込み / インプレッション送信がレスポンスをブロックします）
• ❌ プロダクトが多目的チューニングを必要としているのに、単一の「関連性」スコアを使うこと
• ❌ デフォルトとしての同時スコアリング（非決定的で、キャッシュ不可で、リランキングと組み合わせられません）
• ❌ 「説明用」の疑似コード — スキャフォールドは実際に実行できる必要があります

一般的なユースケース

コンテンツフィード（Strapi v5 プラグイン、TypeScript）

ユーザーが 5 万件の記事を持つ CMS を持っており、パーソナライズされた「for you」フィードを求めています。8 つのステップを順に進めます → マルチアクションスコアリング、著者の多様性、標準フィルター、非同期副作用レーンを備えた Strapi プラグインのスキャフォールドを生成します。

RAG 検索リランカー（Python 非同期）

ユーザーの RAG がベクトル DB から上位 50 件のチャンクを返しており、より高コストなスコアラーでリランキングして上位 5 件を返したいと考えています。単一ソースのパイプラインで、スコアラーチェーン（安価な検索 + 高コストなリランク）を使用します。

タスク優先度付け（FastAPI サービス）

ユーザーが受信するタスク候補のキューを持っており、過去のパターンを考慮して「このユーザーが次に何に取り組むべきか」でランク付けしたいと考えています。項目が反転している（コンテンツではなくタスク）だけで、同じ形が当てはまります。

通知トリアージ（オフラインバッチジョブ）

ユーザーが、直近 24 時間のキューから上位 10 件を選ぶ日次ダイジェストを求めています。オフラインバッチパイプラインです。ソース = キュー、フィルター = 経過時間 / 重複排除 / 対象条件、スコアラー = 緊急度 × ユーザー親和性、セレクター = 上位 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