构建 SSR 友好型头像与浏览器内 AI：我如何训练 Python 模型并将其移植到 TensorFlow.js

Source: Dev.to

问题

头像库通常分为两类：

• 基于 Canvas – 快速，但会破坏 SSR 和可访问性
• SVG 作为图片 – 支持 SSR，但缺乏动态主题或组件组合

我想要两者兼顾：真正的 SSR 兼容 以及 从用户照片生成智能头像。

原生 SVG = 一等的 SSR

Avatune 中的每个头像都渲染为真实的 SVG 元素，而不是 canvas 或 base64 图片。这意味着：

• 零水合不匹配 – 服务器渲染的标记与客户端完全相同
• 内置可访问性 – 屏幕阅读器可以读取 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 ;
}

实验性的浏览器内机器学习预测器

我在 Python 中使用 TensorFlow/Keras 对 CelebA 和 FairFace 数据集训练了多个 CNN 模型，然后将它们转换为 TensorFlow.js 以在浏览器中推理：

• 发色预测器 – 黑色、棕色、金色、灰色
• 发长预测器 – 短发、中等、长发
• 肤色预测器 – 浅色、中等、深色
• 胡须预测器 – 干净剃须 vs 有胡须

训练管道使用 Marimo 笔记本（响应式 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 能准确知道每个主题下哪些颜色和项目是有效的——不再有运行时的意外。

自定义 Rsbuild 插件用于 SVG → 组件

在多个框架中处理 500+ SVG 文件时，ID 和 mask 冲突会成为问题。两个 Rsbuild 插件可以解决此问题：

• @avatune/rsbuild-plugin-svg-to-svelte
• @avatune/rsbuild-plugin-svg-to-vue

它们将 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 个机器学习预测器。

试一试

• 网站 + 文档：
• GitHub：
• 演示平台：

npm install @avatune/react @avatune/pacovqzz-theme

这些机器学习模型仍属实验性质——欢迎提供关于准确性和性能的反馈。如果你有兴趣训练更好的属性预测器，欢迎提交 PR。