recotem

Recotem은 추천 모델의 학습과 서빙을 단순화하는 레시피 중심의 추천 시스템 프레임워크입니다. irspack을 기반으로 하며, 단일 YAML 레시피 파일을 사용하여 데이터 소스, 학습 알고리즘, 하이퍼파라미터 검색, 출력 위치 등 전체 파이프라인을 정의합니다. `recotem train` 명령은 서명된 바이너리 아티팩트를 생성하고, `recotem serve` 명령은 `/v1/recipes/{name}:recommend` 및 `:recommend-related`와 같은 엔드포인트를 노출하는 FastAPI 서버를 실행하며, 새 아티팩트가 나타나면 자동으로 핫스왑합니다. 데이터베이스나 메시지 브로커가 필요 없어 가볍고 배포가 쉽습니다. 주요 기능은 다음과 같습니다: - **레시피 중심 구성**: 단일 YAML 파일이 데이터 수집부터 서빙까지 전체 모델을 정의합니다. - **하이퍼파라미터 최적화**: Optuna를 사용하여 irspack 알고리즘을 검색합니다. - **특징 인식 iALS**: 범주형, 수치형, 다중 레이블 등 항목/사용자 측 특징을 지원하여 추천을 개선합니다. - **콜드 스타트 지원**: 속성 특징을 사용하여 알 수 없는 사용자나 항목에 대해 추천할 수 있습니다. - **플러그형 데이터 소스**: CSV, Parquet, BigQuery, SQL(PostgreSQL, MySQL, SQLite)을 기본 지원하며, Python 엔트리 포인트를 통해 확장 가능합니다. - **안전한 아티팩트**: 다중 키 회전 및 결정적 클래스 허용 목록으로 HMAC 서명되어 안전한 역직렬화를 보장합니다. - **API 키 인증**: 선택적 `X-API-Key` 헤더를 지원하며, 키는 저장 시 해시됩니다. - **유연한 스토리지**: fsspec을 사용하여 로컬, S3, GCS, Azure, HTTPS 경로를 지원합니다. - **관찰 가능성**: 선택적 Prometheus 메트릭과 비밀 정보를 제거한 구조화된 JSON 로그를 제공합니다. 이 도구는 재현성과 운영 단순성을 위해 설계되었습니다. 학습은 배치 작업(예: cron, Airflow, Kubernetes CronJob)으로 실행되고, 서빙은 새 아티팩트를 감시하고 원자적으로 교체하는 장기 실행 프로세스입니다. 이 분리를 통해 학습과 서빙이 서로 다른 머신에서 실행될 수 있으며, 아티팩트 파일을 통해서만 통신합니다. 설치는 pip을 통해 특정 데이터 소스용 확장(예: `recotem[bigquery]`, `recotem[s3]`)과 함께 수행됩니다. 멀티 아키텍처 Docker 이미지는 ghcr.io에서 제공됩니다. 이 프로젝트는 Python 3.12+가 필요하며, glibc Linux(x86-64/arm64), macOS(Apple Silicon), Windows(x86-64)를 지원합니다. `bprfm`과 같은 일부 확장은 플랫폼 지원 범위가 좁아 소스에서 빌드해야 할 수 있습니다. 빠른 시작 예제는 작은 CSV에서 TopPop 추천기를 학습하고 HTTP를 통해 추천을 서빙하는 방법을 보여줍니다. 문서 사이트(recotem.org)는 포괄적인 가이드, API 참조 및 운영 세부 정보를 제공합니다.