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