recsys-pipeline-architect은(는) 무엇을 하나요?
구성 가능한 추천, 랭킹, 피드 파이프라인을 위한 명세 및 스캐폴드 스킬입니다. xAI가 오픈소스로 공개한 For You 알고리즘(Apache 2.0)에서 대중화된 6단계 패턴 — Source → Hydrator → Filter → Scorer → Selector → SideEffect — 을 구현합니다. 이 스킬은 해당 패턴의 독립적인 재구현(MIT)이며, 원본 코드를 복사하지 않았습니다.
업스트림: https://github.com/mturac/recsys-pipeline-architect
사용 시기
- 사용자가 '사용자/컨텍스트에 대해 상위 K개 아이템을 선택하는' 시스템을 구축하려 할 때
- 사용자가 'X를 어떻게 랭킹해야 하나요?'라고 묻거나 피드/개인화 문제를 설명할 때
- 사용자가 스코어링 함수를 가지고 있고 그 주변에 파이프라인 연결이 필요할 때
- 사용자가 단일 관련성 점수에서 조정 가능한 가중치를 가진 다중 행동 예측으로 마이그레이션하려 할 때
- 사용자가 LLM/ML 스코어러를 래핑하고 있고 그 스택(TypeScript/Go/Python)에 필터, 하이드레이터, 사이드 이펙트 및 실행 가능한 스캐폴드가 필요할 때
- 트리거: "추천 시스템", "피드 알고리즘", "랭킹 파이프라인", "for you 피드", "후보 파이프라인", "콘텐츠 추천기", "recsys 파이프라인 아키텍처", "RAG 검색 재순위화"
사용하지 말아야 할 때
- 모델 아키텍처 작업(트랜스포머 설계, 투타워 리트리벌, 임베딩 학습) — 이 스킬은 모델 주변의 연결 구조이지 모델 자체가 아닙니다.
- 순수 ML 학습 파이프라인 — 스코어링 함수는 사용자의 책임입니다.
- 배포된 파이프라인 운영(모니터링, 오토스케일링) — 범위를 벗어납니다.
6단계 프레임워크
| # | 단계 | 역할 | 병렬 가능? |
|---|---|---|---|
| 1 | Source | 하나 이상의 출처에서 후보 가져오기 | 예 — 여러 소스가 병렬 실행 |
| 2 | Hydrator | 필터링 및 스코어링에 필요한 메타데이터로 각 후보 보강 | 예 — 독립적인 하이드레이터가 병렬 실행 |
| 3 | Filter | 절대 표시되어서는 안 되는 후보 제거(차단, 만료, 중복, 부적격) | 순차 — 각 필터는 더 적은 항목을 봄 |
| 4 | Scorer | 생존한 각 후보에 하나 이상의 점수 할당 | 순차 — 이후 스코어러는 이전 점수를 봄 |
| 5 | Selector | 최종 점수로 정렬, 상위 K 반환 | 단일 연산 |
| 6 | SideEffect | 제공된 ID 캐싱, 노출 기록, 이벤트 발행, 카운터 업데이트 | 비동기 — 응답을 절대 차단하지 않아야 함 |
이 순서가 중요한 이유
- Source가 Hydration보다 먼저: 보강 비용을 지불하기 전에 어떤 후보가 있는지 알아야 함
- Hydration이 Filtering보다 먼저: 많은 필터가 소스가 제공하지 않은 메타데이터를 필요로 함
- Filtering이 Scoring보다 먼저: 스코어링이 비용이 많이 드는 단계이므로 부적격자는 먼저 제거
- 스코어러 체인(단일 스코어러 아님): 실제 시스템은 ML 스코어링 + 다양성 재순위화 + 비즈니스 규칙을 조합함
- Selector는 Scoring 이후: 스코어링을 결정적이고 캐시 가능하게 유지
- SideEffects는 마지막에 비동기로: 부작용이 사용자 응답을 절대 차단하지 않아야 함
호출 시 워크플로우
사용자를 다음 8단계로 안내합니다.
- 사용 사례 명확히 하기(1회, 3가지 질문): 랭킹 대상 아이템? 입력 컨텍스트? 언어/런타임?
- 후보 소스 식별: 일반적으로 인-네트워크(팔로우/소유/구독) + 아웃-오브-네트워크(ML 검색 / 트렌딩 / 좋아요한 것과 유사)
- 필요한 Hydration 목록 작성: 각 필터와 스코어러에 대해 소스가 제공하지 않은 데이터는 무엇인가?
- 필터 목록 작성: 중복, 자기 자신, 기간, 차단/뮤트, 이전 제공, 적격성. 순서가 중요: 저렴한 것부터 비싼 것까지.
- 스코어러 체인 설계: 1차(ML) → 결합기(다중 행동 + 가중치) → 다양성 → 비즈니스 규칙
- Selector: 최종 점수 내림차순 정렬, 상위 K 가져오기(또는 인-네트워크/아웃-오브-네트워크에 대한 계층화된 혼합)
- SideEffects: 제공된 ID 캐싱, 노출 이벤트 발행, 카운터 업데이트, 분석 로깅 — 모두 fire-and-forget
- 사용자 스택에 맞는 스캐폴드 생성
표시해야 할 주요 트레이드오프(무음 기본값 금지)
1. 단일 점수 vs 다중 행동 예측
- 단일 점수: 관련성을 예측하는 하나의 모델 학습. 동작 변경 → 재학습.
- 다중 행동: 여러 행동(읽기, 좋아요, 공유, 건너뛰기, 신고)에 대해
P(행동)을 예측하고, 서빙 시 가중치로 결합. 동작 변경 → 가중치 변경. 재학습 없음.
X For You 시스템은 양수 및 음수 가중치를 모두 사용하는 다중 행동을 사용합니다. 사용자가 자주 튜닝할 것으로 예상되면 다중 행동을 권장합니다.
2. 스코어링에서 후보 격리
- 격리: 각 후보가 독립적으로 점수 매겨짐. 결정적이고 캐시 가능.
- 결합: 후보가 스코어링 중에 서로 참조(예: 배치에 대한 트랜스포머). 더 표현력이 좋지만 배치 간 비결정적.
기본값은 격리. 특정 이유(예: 명시적 배치 인식 다양성)가 있는 경우에만 결합.
3. 온라인 vs 오프라인
- 요청 시간(온라인): 각 요청 시 파이프라인 실행. 지연 예산: 100–300ms. 기본값.
- 사전 계산(오프라인 배치): 주기적으로 파이프라인 실행, 결과 캐싱. 더 낮은 지연 시간, 더 낮은 신선도.
- 하이브리드: 후보 검색은 오프라인, 랭킹은 온라인.
엄격한 규칙
- 벤치마크 수치를 만들지 마십시오. "얼마나 더 빠른가요?" → "워크로드에 따라 다르니 직접 실행해 보세요."
- 출처 명시. 패턴을 참조할 때는 "xAI의 오픈소스 For You 알고리즘에 의해 대중화됨" /
github.com/xai-org/x-algorithm(Apache 2.0)으로 표기. - 상표 사용 금지. 사용자의 산출물을 "X-유사"라고 명명하거나 "For You" 브랜딩을 사용하지 마십시오. 패턴은 자유롭지만 브랜드는 그렇지 않습니다. 권장 명명: "후보 파이프라인", "피드 파이프라인", "랭킹 파이프라인", "recsys 파이프라인".
- 트레이드오프 표시. 다중 행동 vs 단일, 격리 vs 결합, 온라인 vs 오프라인 — 절대 무음 기본값으로 두지 마십시오.
- 생성된 스캐폴드는 실행 가능해야 합니다. 의사 코드를 코드인 척 전달하지 마십시오.
- 필터 순서가 중요합니다. 저렴한 것부터 비싼 것까지. 보편적인 것부터 사용자별 것까지.
- 부작용은 절대 차단하지 않습니다. fire-and-forget 패턴(goroutine / await 없는 promise / asyncio 태스크)으로 래핑.
안티 패턴
- 필터링 전 스코어링(어차피 제거될 후보에 연산 낭비)
- 동기식 부작용(응답을 차단하는 캐시 쓰기/노출 발행)
- 제품이 여러 목표(참여도 vs 안전성 vs 다양성 vs 광고)에 대해 튜닝해야 할 때 단일 '관련성' 점수만 사용
- 기본값으로 결합 스코어링(비결정적, 캐싱 어려움, 재순위화 단계와 구성되지 않음)
- "설명을 위한" 의사 코드 생성 — 스캐폴드는 실제로 실행 가능해야 함
업스트림 내용
https://github.com/mturac/recsys-pipeline-architect에 있는 업스트림 저장소는 다음을 제공합니다.
- 전체 8단계 워크플로우가 포함된 완전한
SKILL.md - 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