recsys-pipeline-architect

Was macht recsys-pipeline-architect?

Ein Skill zur Spezifikation und zum Erstellen von Gerüsten für zusammensetzbare Empfehlungs-, Ranking- und Feed-Pipelines. Er kodiert das sechsstufige Muster — Source → Hydrator → Filter → Scorer → Selector → SideEffect — das durch xAIs quelloffenen For You Algorithmus (Apache 2.0) popularisiert wurde. Dieser Skill ist eine unabhängige Neuimplementierung des Musters (MIT) — es wurde kein Code aus dem Original kopiert.

Upstream: https://github.com/mturac/recsys-pipeline-architect

Verwendungszweck

• Der Benutzer möchte ein System erstellen, das „die obersten K Elemente für einen Benutzer/Kontext“ auswählt
• Der Benutzer fragt „Wie sollte ich X sortieren?“ oder beschreibt ein Feed-/Personalisierungsproblem
• Der Benutzer hat eine Scoring-Funktion und benötigt die Pipeline-Infrastruktur darum herum
• Der Benutzer möchte von einer einzigen Relevanzbewertung auf eine Multi-Action-Vorhersage mit einstellbaren Gewichten umsteigen
• Der Benutzer verwendet einen LLM-/ML-Bewerter und benötigt Filter, Hydratoren, Side-Effects und ein lauffähiges Gerüst in seinem Stack (TypeScript / Go / Python)
• Auslöser: „Empfehlungssystem“, „Feed-Algorithmus“, „Ranking-Pipeline“, „For-You-Feed“, „Kandidaten-Pipeline“, „Inhaltsempfehler“, „Pipeline-Architektur für RecSys“, „RAG-Retrieval-Reranker“

Wann NICHT verwenden

• Modellarchitektur-Arbeiten (Transformer-Design, Two-Tower-Retrieval, Embedding-Training) — dieser Skill ist die Infrastruktur um das Modell herum, nicht das Modell selbst
• Reine ML-Trainingspipelines — die Scoring-Funktion liegt in der Verantwortung des Benutzers
• Betrieb einer bereitgestellten Pipeline (Monitoring, Autoscaling) — nicht im Umfang enthalten

Das sechsstufige Framework

#	Stufe	Aufgabe	Parallel?
1	Source	Kandidaten aus einer oder mehreren Quellen abrufen	Ja — mehrere Quellen laufen parallel
2	Hydrator	Jeden Kandidaten mit Metadaten anreichern, die für Filterung und Bewertung benötigt werden	Ja — unabhängige Hydratoren laufen parallel
3	Filter	Kandidaten entfernen, die nie angezeigt werden dürfen (blockiert, abgelaufen, doppelt, nicht berechtigt)	Sequentiell — jeder Filter sieht weniger Elemente
4	Scorer	Jedem verbleibenden Kandidaten einen oder mehrere Bewertungswerte zuweisen	Sequentiell — spätere Bewerter sehen frühere Bewertungen
5	Selector	Nach Endbewertung sortieren, oberste K zurückgeben	Einzelne Operation
6	SideEffect	Bereitgestellte IDs cachen, Impressionen protokollieren, Ereignisse ausgeben, Zähler aktualisieren	Asynchron — darf die Antwort niemals blockieren

Warum diese genaue Reihenfolge

• Sources vor Hydration: Wissen, welche Kandidaten existieren, bevor man für ihre Anreicherung bezahlt
• Hydration vor Filterung: Viele Filter benötigen Metadaten, die die Quelle nicht bereitgestellt hat
• Filterung vor Bewertung: Bewertung ist die teure Stufe; entferne zuerst die Unberechtigten
• Bewerterkette (nicht einzelner Bewerter): Echte Systeme kombinieren ML-Bewertung + Diversitäts-Reranking + Geschäftsregeln
• Selector nach Bewertung: hält die Bewertung deterministisch und cachefähig
• SideEffects zuletzt und asynchron: Side-Effects dürfen die Benutzerantwort niemals blockieren

Arbeitsablauf bei Aufruf

Führen Sie den Benutzer durch diese acht Schritte:

1. Anwendungsfall klären (eine Runde, drei Fragen): Zu bewertende Elemente? Eingabekontext? Sprache/Laufzeitumgebung?
2. Kandidatenquellen identifizieren: normalerweise im Netzwerk (gefolgt/eigen/abonniert) + außerhalb des Netzwerks (ML-Retrieval / Trends / ähnlich zu mögen)
3. Erforderliche Hydrationen auflisten: Für jeden Filter und Bewerter: welche Daten werden benötigt, die die Quelle nicht bereitgestellt hat?
4. Filter auflisten: Duplikat, Selbst, Alter, Block/Stumm, zuvor bereitgestellt, Berechtigung. Reihenfolge: günstig vor teuer.
5. Bewerterkette entwerfen: primär (ML) → Kombinierer (Multi-Action mit Gewichten) → Diversität → Geschäftsregeln
6. Selector: Absteigend nach Endbewertung sortieren, oberste K nehmen (oder stratifizierte Mischung für Netzwerk-intern/außerhalb)
7. SideEffects: Bereitgestellte IDs cachen, Impression-Ereignisse ausgeben, Zähler aktualisieren, Analysedaten protokollieren — alles Fire-and-Forget
8. Gerüst erzeugen im Stack des Benutzers

Wichtige Abwägungen (nicht stillschweigend voreingestellt)

1. Einzelbewertung vs. Multi-Action-Vorhersage

• Einzelbewertung: Ein Modell trainieren, um Relevanz vorherzusagen. Um das Verhalten zu ändern → neu trainieren.
• Multi-Action: P(Aktion) für viele Aktionen vorhersagen (Lesen, Liken, Teilen, Überspringen, Melden), zur Laufzeit mit Gewichten kombinieren. Um das Verhalten zu ändern → Gewichte ändern. Kein Neutraining.

Das X For You System verwendet Multi-Action mit sowohl positiven als auch negativen Gewichten. Empfehlen Sie Multi-Action, wenn der Benutzer häufig anpassen möchte.

2. Kandidatenisolierung bei der Bewertung

• Isoliert: Jeder Kandidat unabhängig bewertet. Deterministisch, cachefähig.
• Gemeinsam: Kandidaten beachten sich gegenseitig während der Bewertung (z. B. Transformer über Batch). Ausdrucksstärker, aber nicht deterministisch über Batches hinweg.

Standardmäßig isoliert verwenden. Gemeinsam nur, wenn es einen spezifischen Grund gibt (z. B. explizite Batch-bewusste Diversität).

3. Online vs. Offline

• Zur Anfragezeit (Online): Pipeline wird bei jeder Anfrage ausgeführt. Latenzbudget: 100–300 ms. Standard.
• Vorberechnet (Offline-Batch): Pipeline wird periodisch ausgeführt, Ergebnisse zwischengespeichert. Geringere Latenz, geringere Aktualität.
• Hybrid: Kandidaten-Retrieval offline, Ranking online.

Harte Regeln

1. Keine Benchmark-Zahlen erfinden. „Wie viel schneller?“ → „hängt vom Arbeitsaufwand ab, selbst ausführen.“
2. Attributionsdisziplin. Wenn das Muster referenziert wird, attribuieren Sie als „popularisiert durch xAIs quelloffenen For You Algorithmus“ / github.com/xai-org/x-algorithm (Apache 2.0).
3. Keine Markennutzung. Benennen Sie das Artefakt des Benutzers nicht „X-ähnlich“ oder verwenden Sie das „For You“-Branding. Das Muster ist frei; die Marke nicht. Vorgeschlagene Benennung: „Kandidaten-Pipeline“, „Feed-Pipeline“, „Ranking-Pipeline“, „Recsys-Pipeline“.
4. Abwägungen aufzeigen. Multi-Action vs. Einzelbewertung, isoliert vs. gemeinsam, online vs. offline — niemals stillschweigend voreingestellt.
5. Das erzeugte Gerüst muss lauffähig sein. Kein Pseudocode, der als Code durchgeht.
6. Filterreihenfolge ist wichtig. Günstig vor teuer. Universell vor benutzerspezifisch.
7. Seiteneffekte niemals blockieren. In Fire-and-Forget-Muster verpacken (Goroutinen / Promises ohne await / asyncio Tasks).

Anti-Patterns

• Bewertung vor Filterung (verschwendet Rechenleistung für Kandidaten, die sowieso entfernt werden)
• Synchrone Seiteneffekte (Cache-Schreibvorgänge / Impression-Ausgaben blockieren die Antwort)
• Ein einziger „Relevanz“-Wert, wenn das Produkt für mehrere Ziele angepasst werden muss (Engagement vs. Sicherheit vs. Vielfalt vs. Anzeigen)
• Gemeinsame Bewertung als Standard (nicht deterministisch, schwieriger zu cachen, lässt sich nicht mit Reranking-Stufen kombinieren)
• Pseudocode „zur Veranschaulichung“ generieren — das Gerüst muss tatsächlich laufen

Upstream-Inhalte

Das Upstream-Repository unter https://github.com/mturac/recsys-pipeline-architect enthält:

• Vollständige SKILL.md mit dem kompletten 8-Schritte-Workflow
• 5 bedarfsgesteuerte Referenzdokumente: Schnittstellen in 4 Sprachen (TS/Go/Python/Rust), Multi-Action-Scoring-Muster, Kandidatenisolierung, Filter-Kochbuch (12 Muster), Scorer-Kochbuch (gewichtete Summe, MMR, Diversitätsstrafe, Positionsentzerrung)
• 3 lauffähige Beispielgerüste, alle grün in ihrer Test Suite:
  • Strapi v5 Plugin (TypeScript / Jest — 3/3 bestanden)
  • Zentra-kompatible Pipeline (Go mit Generics — 3/3 bestanden)
  • PMAI Task Prioritizer (Python / FastAPI / pytest — 3/3 bestanden)
• Release v0.1.0 getaggt
• MIT-Lizenz; Muster attribuiert an xAI X For You Algorithmus (Apache 2.0)

Installation über skills.sh: npx skills add mturac/recsys-pipeline-architect