SSR 친화적인 아바타 구축: 브라우저 내 AI로 Python 모델을 훈련하고 TensorFlow.js로 포팅하기
Source: Dev.to
문제
아바타 라이브러리는 보통 두 가지 유형으로 나뉩니다:
- Canvas 기반 – 빠르지만 SSR과 접근성을 깨뜨림
- SVG‑이미지 – SSR 친화적이지만 동적 테마 적용이나 컴포넌트 조합이 어려움
저는 두 가지를 모두 원했습니다: 진정한 SSR 호환성 및 사용자 사진을 이용한 지능형 아바타 생성.
Native SVG = 일류 SSR
Avatune의 모든 아바타는 캔버스나 base64 이미지가 아니라 실제 SVG 요소로 렌더링됩니다. 이는 다음을 의미합니다:
- 수분 불일치 제로 – 서버가 클라이언트와 동일한 마크업을 렌더링
- 접근성 내장 – 스크린 리더가 SVG 의미론에 접근 가능
- CSS 스타일링 작동 – 선택자로 요소를 타깃하고 CSS 변수를 사용
- DevTools에서 검사 가능 – 일반 DOM 요소처럼 디버깅
import { Avatar } from '@avatune/react';
import theme from '@avatune/pacovqzz-theme/react';
// This SSR renders as clean SVG markup
function UserCard({ seed }: { seed: string }) {
return ;
}실험적인 인‑브라우저 ML 예측기
저는 CelebA와 FairFace 데이터셋을 사용해 Python에서 TensorFlow/Keras로 여러 CNN 모델을 학습한 뒤, 브라우저 추론을 위해 TensorFlow.js로 변환했습니다:
- 머리카락 색 예측기 – 검정, 갈색, 금발, 회색
- 머리 길이 예측기 – 짧음, 중간, 길음
- 피부 톤 예측기 – 밝음, 중간, 어두움
- 수염 예측기 – 면도된 상태 vs 수염
학습 파이프라인은 Marimo 노트북(reactive Jupyter)을 사용합니다. 모델은 uint8 로 양자화되어 CDN을 통해 제공됩니다. 예측기당 전체 번들 크기는 최대 약 2 MB입니다.
타입‑안전 테마
각 테마는 강력히 타입이 지정된 색상 열거형과 레이어 구성을 내보냅니다:
import type { ReactAvatarItem } from '@avatune/types';
import { createTheme, fromHead } from '@avatune/theme-builder';
const theme = createTheme()
.withStyle({ size: 500, borderRadius: '100%' })
.addColors('hair', [HairColors.Black, HairColors.Brown, HairColors.Blond])
.addColors('skin', [SkinTones.Light, SkinTones.Medium, SkinTones.Dark])
.connectColors('head', ['ears', 'nose']) // ears + nose inherit head's skin color
.setOptional('glasses')
.mapPrediction('hairColor', 'brown', [HairColors.Brown, HairColors.Auburn])
.toFramework()
.build();TypeScript는 각 테마에 대해 어떤 색상과 아이템이 유효한지 정확히 알기 때문에 런타임에서의 놀라움이 없습니다.
SVG → 컴포넌트를 위한 맞춤 Rsbuild 플러그인
500개 이상의 SVG 파일을 여러 프레임워크에서 다룰 때 ID와 마스크 충돌이 문제가 됩니다. 두 개의 Rsbuild 플러그인이 이를 해결합니다:
이들은 SVG 파일을 적절한 프레임워크 컴포넌트로 변환하며:
- SVGO를 통한 자동 접두사 ID 적용(충돌 방지)
- 반응형 스케일링을 위한
viewBox보존 - 유연성을 위한 쿼리 기반 임포트
import Icon from './icon.svg?svelte';import Icon from './icon.svg?vue';스택
- Turborepo – 캐시가 포함된 모노레포 오케스트레이션
- Bun – 패키지 매니저(≈2배 빠른 설치)
- Rspack / Rslib – 빌드 도구(≈10배 빠른 webpack 대비)
- Biome – Lint + 포맷(ESLint + Prettier 대체)
- uv – Python 패키지 매니저(10–100배 빠른 pip 대비)
이 모노레포에는 10개의 테마, 5개의 프레임워크 렌더러(React, Vue, Svelte, Vanilla, React Native), 그리고 5개의 ML 예측기가 포함되어 있습니다.
사용해 보기
- 웹사이트 + 문서:
- GitHub:
- 플레이그라운드:
npm install @avatune/react @avatune/pacovqzz-themeML 모델은 실험 단계이므로 정확도와 성능에 대한 피드백을 환영합니다. 더 나은 속성 예측기 학습에 관심이 있다면 PR을 통해 기여해 주세요.