一位站在数据大屏旁边的情报分析助手，能看、能说、有肢体表达——这正是具身交互智能的核心。本文从魔珐星云控制台配置到 Python FastAPI + React 全栈工程源码，拆解情报平台如何以参数流 SDK 为中枢，让数字人嵌入数据采集→KOL 评分→大屏洞察→竞品监测的情报全链路。

魔珐星云 PC 端官方链接：https://xingyun3d.com?utm_campaign=daily&utm_source=CSDNwanfen2&utm_medium=&utm_term=&utm_content=

---

一、产品概览：当数字人走进数据情报中心

海外社媒网红营销情报平台是一个把数字人嵌入数据分析流程的 Web 应用。传统的数据大屏是沉默的——一堆图表、数字、排行榜，用户自己看、自己判断。本平台的做法不同：用户打开数据大屏，数字人情报分析助手数析便以玻璃态舞台形式常驻右下角、自动语音问候；在采集任务完成后数析播报关键发现，在 KOL 评分出炉后语音解读合作建议，在竞品监测到异常时主动提醒。平台支持 Instagram 与 TikTok 网红数据一站式批量采集，通过五维量化评分模型对每位 KOL 进行 S/A/B/C/D 五级评定，并以数据大屏呈现统计卡片、等级分布饼图、平台占比、五维雷达图与 TOP 10 排行。同时内置竞品监测追踪网红投放动态，以及告警中心自动推送任务状态与异常错误。数字人数析常驻右下角舞台，连接问候、数据播报、评分解读，全程语音陪伴。

在这条链路中，数字人数析不是数据大屏旁边的装饰动画——她是具身交互智能的载体：有形象、有声音、有肢体表达，在每一个关键节点用语音与用户对话。这区别于传统的数据分析工具，把数据采集的能力、量化评分的分析能力与数字人的具身表达能力绑定在同一次交互里。

---

二、技术架构总览

项目采用 Python FastAPI 后端 + React 18 前端的双层架构，配合 SQLite 本地数据库与 APScheduler 定时任务，整体分为五层：

层级	职责	核心文件
视图层	数据大屏 / 采集任务 / KOL 管理 / 竞品监测 / 告警 / 设置	Dashboard.jsx 等 8 个组件
数字人层	SDK 连接 / 语音播报 / 字幕 / 打断	avatar.js
逻辑层	路由 / 状态管理 / API 请求 / 图表渲染	App.jsx + api.js
服务层	RESTful API / 数据模型 / 评分算法 / 定时调度	main.py + kol_scorer.py + scheduler.py
数据层	SQLite 持久化 / Datasets API 对接	database.py + brightdata.py + models.py

数字人逻辑以 IIFE 封装的原生 JS 单例承载，通过 window.AvatarService 暴露全局接口。这意味着 React 组件中的任何模块都可以在数据加载完成、评分出炉时调用数析的语音能力——不需要额外的状态管理库，一个 script 标签即可串联整条具身交互智能链路。

---

三、前提准备

魔珐星云控制台配置

数字人数析的形象、场景、音色、表演均由魔珐星云控制台驱动。以下五步完成驱动应用创建与参数配置，是代码层接入 SDK 前的必要前提。

步骤1：魔珐星云控制台创建驱动应用

在魔珐星云控制台创建一个新的驱动应用，获取 appId 与 appSecret，这两个密钥将填入项目 avatar.js 的 AVATAR_CONFIG。

步骤2：形象配置

为数字人数析选择或上传形象资源，配置外观参数。形象配置决定了 SDK 渲染时的角色外观——在情报平台场景中，数析作为数据情报官出镜，形象需要匹配专业、可信赖的视觉调性。这是具身交互智能中"有形象"这一要素的直接来源。

步骤3：场景配置

配置数字人所在的虚拟场景，包括灯光、背景、机位等。场景配置与前端 avatar-stage 容器配合，决定数析在页面右下角舞台中的视觉呈现方式。

步骤4：音色配置

为数析选择情报分析助手音色，控制语音合成的语速与情感倾向。音色配置直接影响播报数据洞察时的听感——专业、清晰、有节奏感，是具身交互智能中"能说"这一要素的质量基础。

步骤5：表演配置

配置数析的肢体动作与表情，包括待机动作、说话时的手势、情绪表情等。表演配置让数字人在播报 KOL 评分时有自然的肢体表达，而非僵硬站桩——这是具身交互智能区别于纯语音助手的视觉支柱。

---

四、核心代码讲解

4.1 数字人服务：原生 JS 版魔珐 SDK 集成

avatar.js 是整个具身交互智能链路的视觉与语音中枢。它用 IIFE 封装，通过 window.AvatarService 暴露全局接口，管理 SDK 连接、语音播报、字幕同步与实时打断：

(() => {
  'use strict';

  /* ============== 配置 ============== */
  const AVATAR_CONFIG = {
    appId: 'your_avatar_app_id',
    appSecret: 'your_avatar_app_secret',
    gatewayUrl: 'https://nebula-agent.xingyun3d.com/user/v1/ttsa/session',
    dataSource: '2',
    customId: 'demo',
  };

  const AVATAR_IDENTITY = {
    name: '数析',
    role: '情报分析助手',
    greeting: '欢迎来到海外社媒网红营销情报平台。我是你的情报分析助手数析，帮你洞察海外社媒网红营销数据，发现高价值 KOL。',
  };

  /* ============== 状态 ============== */
  const avatarState = {
    connected: false,
    connecting: false,
    instance: null,
    subtitle: '',
    avatarState: '',
    listeners: new Set(),
  };

  /* ============== 订阅机制 ============== */
  function subscribe(listener) {
    avatarState.listeners.add(listener);
    return () => avatarState.listeners.delete(listener);
  }

  function notify() {
    avatarState.listeners.forEach(l => l());
  }

  function patch(partial) {
    Object.assign(avatarState, partial);
    notify();
  }

  /* ============== DOM 引用 ============== */
  const $ = (sel) => document.querySelector(sel);
  const containerId = 'xmov-avatar-container';

  function getSubtitleEl() {
    return $('#avatar-subtitle');
  }

  function getLoadingEl() {
    return $('#avatar-loading');
  }

  /* ============== 连接 ============== */
  async function connect() {
    if (avatarState.connected || avatarState.connecting) return;

    const containerEl = document.getElementById(containerId);
    if (!containerEl) {
      console.error('[Avatar] 容器不存在:', containerId);
      return;
    }

    patch({ connecting: true });
    updateLoadingUI(true);

    try {
      const url = new URL(AVATAR_CONFIG.gatewayUrl);
      url.searchParams.append('data_source', AVATAR_CONFIG.dataSource);
      url.searchParams.append('custom_id', AVATAR_CONFIG.customId);

      let resolveConnect;
      let rejectConnect;
      const connectPromise = new Promise((res, rej) => {
        resolveConnect = res;
        rejectConnect = rej;
      });

      const options = {
        containerId: `#${containerId}`,
        appId: AVATAR_CONFIG.appId,
        appSecret: AVATAR_CONFIG.appSecret,
        enableDebugger: false,
        gatewayServer: url.toString(),
        onProxyWidgetEvent: (event) => console.log('[Avatar SDK事件]', event),
        onStateChange: (state) => {
          patch({ avatarState: state });
        },
        onMessage: async (error) => {
          if (!avatarState.connected) {
            rejectConnect(new Error(error.message || 'SDK连接失败'));
          }
        },
        onVoiceStateChange: (status) => {
          if (status.includes('end')) {
            patch({ avatarState: 'interactive_idle' });
          }
        },
      };

      const avatar = new window.XmovAvatar(options);
      await new Promise(r => setTimeout(r, 3000));

      await avatar.init({
        onDownloadProgress: (progress) => {
          if (progress >= 100) {
            resolveConnect(true);
          }
        },
        onClose: () => {
          patch({ avatarState: '', connected: false });
        },
      });

      const timeout = new Promise((_, rej) => setTimeout(() => rej(new Error('连接超时')), 15000));
      try {
        await Promise.race([connectPromise, timeout]);
      } catch (e) {
        console.warn('[Avatar] 连接等待结束:', e.message);
      }

      avatarState.instance = avatar;
      patch({ connected: true, connecting: false });
      updateLoadingUI(false);
      console.log('[Avatar] 连接成功');

      setTimeout(() => {
        speakText(AVATAR_IDENTITY.greeting);
      }, 800);

    } catch (err) {
      console.error('[Avatar] 连接失败:', err);
      patch({ connected: false, connecting: false });
      updateLoadingUI(false);
    }
  }

  function disconnect() {
    if (avatarState.instance) {
      try {
        avatarState.instance.stop();
        avatarState.instance.destroy();
      } catch (e) {
        console.error('[Avatar] 断开失败:', e);
      }
      avatarState.instance = null;
      patch({ connected: false, avatarState: '' });
    }
  }

  /* ============== 播报 ============== */
  function speakText(text) {
    if (!avatarState.instance || !text) return;
    const ssml = `<speak>${text}</speak>`;
    avatarState.instance.speak(ssml, true, true);
    patch({ avatarState: 'speak' });
  }

  function interrupt() {
    if (!avatarState.instance) return;
    try {
      if (typeof avatarState.instance.interactiveidle === 'function') {
        avatarState.instance.interactiveidle();
      } else if (typeof avatarState.instance.interrupt === 'function') {
        avatarState.instance.interrupt();
      }
      patch({ avatarState: 'interactive_idle' });
    } catch (e) {
      console.error('[Avatar] 打断失败:', e);
    }
  }

  /* ============== 字幕 ============== */
  function setSubtitle(text) {
    patch({ subtitle: text });
    const el = getSubtitleEl();
    if (el) {
      el.textContent = text;
      el.classList.toggle('is-on', !!text);
    }
  }

  /* ============== UI 更新 ============== */
  function updateLoadingUI(show) {
    const el = getLoadingEl();
    if (el) {
      el.style.display = show ? 'flex' : 'none';
    }
  }

  /* ============== 初始化 ============== */
  function init() {
    console.log('[Avatar] 初始化数字人服务');
    connect();
  }

  if (document.readyState === 'loading') {
    document.addEventListener('DOMContentLoaded', init);
  } else {
    init();
  }

  /* ============== 暴露全局接口 ============== */
  window.AvatarService = {
    connect,
    disconnect,
    speakText,
    interrupt,
    setSubtitle,
    subscribe,
    getState: () => ({
      connected: avatarState.connected,
      connecting: avatarState.connecting,
      subtitle: avatarState.subtitle,
      avatarState: avatarState.avatarState,
    }),
    IDENTITY: AVATAR_IDENTITY,
  };

})();

关键逻辑分析：

• IIFE 封装避免污染全局命名空间，window.AvatarService 暴露 connect/speakText/interrupt 等方法。React 组件在数据加载完成后通过 window.AvatarService.speakText 让数析播报洞察——这是具身交互智能在 React 项目中的落地方案：不需要 hooks、不需要 context，原生 JS 服务层直接桥接框架层
• AVATAR_IDENTITY 定义数析的身份与问候语，贯穿页面名牌、连接问候、播报文案。connect 成功后延迟 800ms 播报问候，给魔珐 SDK 一个稳定窗口，避免初始化与播报抢资源
• subscribe + patch 实现发布-订阅模式。avatarState 变化时通知所有监听者，React 组件可以订阅状态变化并更新 UI——是具身交互智能跨框架复用的架构基础
• speakText 将纯文本包裹为 SSML 格式发送给魔珐参数流 SDK，SDK 驱动数字人发音并同步肢体动作。speak 的第二个参数 true 表示打断当前播报，第三个参数 true 表示启用表情动画
• onVoiceStateChange 回调在语音播放结束时将状态切回 interactive_idle，让数字人回到待机姿态——这是具身交互智能中"有肢体表达"的细节
• onMessage 回调在 SDK 连接失败时 reject connectPromise，配合 15 秒超时兜底，防止无限等待。连接失败不阻塞用户使用，这是具身交互智能的容错设计

4.2 KOL 五维评分：293 行 Python 量化算法

kol_scorer.py 是具身交互智能内容层的核心之一。它把每个网红的原始数据转化为五维量化评分，为数析的语音解读提供数据支撑：

def calculate_kol_score(influencer_data: dict, all_influencers: list[dict] = None) -> dict:
    scores = {
        "score_followers": _score_followers(influencer_data, all_influencers),
        "score_engagement": _score_engagement(influencer_data, all_influencers),
        "score_content": _score_content(influencer_data),
        "score_growth": _score_growth(influencer_data),
        "score_business": _score_business(influencer_data),
    }

    total = sum(scores.values())
    total = round(min(100, max(0, total)), 1)

    level = _get_level(total)
    suggestion = _get_suggestion(total, scores, influencer_data)

    return {
        "kol_score": total,
        "kol_level": level,
        "kol_suggestion": suggestion,
        **scores,
    }

关键逻辑分析：

• 五个维度各 0-20 分，满分 100。粉丝质量用对数刻度衡量量级，互动质量结合互动率与绝对互动量，内容质量考察发帖频率与一致性，增长趋势通过互动/粉丝比推算，商业价值综合量级、认证与高价值品类加成
• _get_level 把总分映射为 S/A/B/C/D 五级，_get_suggestion 根据等级与短板维度生成合作建议文案——这段文案正是数析语音播报时的内容来源，让具身交互智能不只是念数字，而是给出有判断力的分析
• 当数析说出"该 KOL 评分 92 分，S 级推荐，粉丝质量与互动质量双优，建议优先建立长期合作"的那一刻，数据评分引擎与数字人的具身表达能力完成了闭环

4.3 Datasets API 集成：NDJSON 解析与自动重试

brightdata.py 封装了 Datasets API 的调用逻辑，是具身交互智能链路的数据源头：

class BrightDataClient:
    def __init__(self, api_key: str):
        self.api_key = api_key
        self.headers = {
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json",
        }

    def scrape_profiles(self, urls: list[str], platform: str, max_retries: int = 5) -> dict:
        dataset_id = INSTAGRAM_DATASET_ID if platform == "instagram" else TIKTOK_DATASET_ID
        if platform == "instagram":
            input_data = [{"url": url} for url in urls]
        else:
            input_data = [{"url": url, "country": ""} for url in urls]

        payload = json.dumps({"input": input_data})

        last_error = None
        for attempt in range(max_retries):
            try:
                response = requests.post(
                    f"{BASE_URL}/scrape?dataset_id={dataset_id}&notify=false&include_errors=true",
                    headers=self.headers,
                    data=payload,
                    timeout=120,
                )
                if response.status_code == 202:
                    try:
                        body = response.json()
                        if "snapshot_id" in body:
                            return {"status": "pending", "snapshot_id": body["snapshot_id"], "data": []}
                    except Exception:
                        pass
                    return {"status": "error", "error": "HTTP 202: async pending", "data": []}

                if response.status_code != 200:
                    logger.error(f"Datasets API error: {response.status_code} {response.text[:200]}")
                    return {"status": "error", "error": f"HTTP {response.status_code}: {response.text[:200]}", "data": []}

                raw_text = response.text.strip()
                data_list = []
                for line in raw_text.splitlines():
                    line = line.strip()
                    if not line:
                        continue
                    try:
                        obj = json.loads(line)
                        if isinstance(obj, list):
                            data_list.extend(obj)
                        elif isinstance(obj, dict):
                            if "snapshot_id" in obj:
                                return {"status": "pending", "snapshot_id": obj["snapshot_id"], "data": []}
                            data_list.append(obj)
                    except json.JSONDecodeError:
                        continue
                return {"status": "completed", "data": data_list}

            except (requests.exceptions.ProxyError, requests.exceptions.ConnectionError,
                    requests.exceptions.Timeout, requests.exceptions.SSLError) as e:
                last_error = str(e)
                logger.warning(f"Attempt {attempt+1}/{max_retries} failed: {type(e).__name__}")
                if attempt < max_retries - 1:
                    time.sleep(5 * (attempt + 1))
                continue

关键逻辑分析：

• Instagram 与 TikTok 使用不同的 dataset_id，TikTok 需要额外的 country 字段。scrape_profiles 根据 platform 参数自动切换
• API 返回 NDJSON 格式（每行一条 JSON），需要逐行解析。也可能返回 snapshot_id 表示异步处理中，需要轮询
• 5 次重试 + 递增退避（5s/10s/15s/20s）覆盖网络抖动与代理超时。数据采集完成后，后端自动调用 kol_scorer 计算评分，再推送给前端——数析在数据就绪后语音播报，整条具身交互智能链路从采集到播报全自动

4.4 数据大屏：React 可视化与数字人播报集成

Dashboard.jsx 是数据大屏的核心组件，用 Recharts 渲染饼图与雷达图。它在数据加载完成后调用数析的语音能力，让具身交互智能贯穿数据洞察流程：

export default function Dashboard() {
  const [data, setData] = useState(null);
  const [loading, setLoading] = useState(true);
  const [activeLevel, setActiveLevel] = useState(null);
  const [activePlatform, setActivePlatform] = useState(null);

  useEffect(() => { loadData(); }, []);

  async function loadData() {
    try {
      const res = await getDashboard();
      setData(res.data);
    } catch (e) {
      console.error(e);
    } finally {
      setLoading(false);
    }
  }

关键逻辑分析：

• loadData 在组件挂载时自动调用，获取数据大屏的全部统计数据。数据就绪后更新 state，触发图表重新渲染——这是具身交互智能数据流的起点：后端采集、评分、聚合，前端展示、交互、播报
• 数据大屏通过 getDashboard API 获取 total_influencers、avg_score、avg_engagement、completed_tasks 等全局统计，为后续的图表渲染与数字人播报提供数据基础
• 这是具身交互智能赋予数据平台的价值：AI 不只是后台的计算引擎，而是一位站在你旁边的情报分析官，用声音把数据变成洞察

4.5 数字人舞台：品牌蓝玻璃态视觉

index.css 中的数字人舞台样式定义了数析在页面右下角的视觉呈现，品牌蓝配色与数据平台调性统一：

.avatar-stage {
  position: fixed;
  right: 80px;
  bottom: 32px;
  width: 280px;
  height: 420px;
  z-index: 1000;
  pointer-events: none;
}

.avatar-stage__frame {
  position: relative;
  width: 100%;
  height: 100%;
  border-radius: 20px;
  background: rgba(255, 255, 255, 0.72);
  backdrop-filter: blur(16px);
  -webkit-backdrop-filter: blur(16px);
  border: 1px solid rgba(59, 130, 246, 0.2);
  box-shadow:
    0 20px 60px -12px rgba(59, 130, 246, 0.15),
    0 8px 24px -8px rgba(0, 0, 0, 0.08);
  overflow: hidden;
  z-index: 1;
  pointer-events: auto;
}

.avatar-stage__sdk canvas,
.avatar-stage__sdk video {
  display: block !important;
  max-width: 130% !important;
  max-height: 100% !important;
  width: auto !important;
  height: auto !important;
  margin: 0 auto !important;
  position: relative !important;
  z-index: 3 !important;
  left: 0 !important;
  right: 0 !important;
}

.avatar-stage__subtitle {
  position: absolute;
  bottom: 40px;
  left: 50%;
  transform: translateX(-50%);
  max-width: 260px;
  padding: 8px 14px;
  background: rgba(14, 20, 24, 0.78);
  border: 1px solid rgba(91, 138, 158, 0.28);
  border-radius: 12px;
  font-size: 12px;
  line-height: 1.5;
  color: #f1f5f9;
  text-align: center;
  text-shadow: 0 1px 2px rgba(0, 0, 0, 0.3);
  opacity: 0;
  transition: opacity 0.3s ease;
  pointer-events: none;
  z-index: 30;
}

.avatar-stage__subtitle.is-on {
  opacity: 1;
}

关键逻辑分析：

• 玻璃态外框用 rgba(255, 255, 255, 0.72) 半透明白底 + backdrop-filter: blur(16px) 实现磨砂玻璃效果，品牌蓝描边 rgba(59, 130, 246, 0.2) 与平台主色统一
• canvas 的 max-width 设为 130%，为数字人手臂抬起等动态动作预留显示空间，避免肢体被容器裁切。left: 0 + right: 0 + margin: 0 auto 确保 canvas 在容器内水平居中
• 字幕样式背景 rgba(14, 20, 24, 0.78) + 边框 rgba(91, 138, 158, 0.28) 遵循项目统一的字幕视觉规范，深色半透明底让白色文字在任意背景下都清晰可读
• pointer-events: none 让舞台容器不拦截鼠标事件，用户点击舞台区域时仍能操作背后的数据大屏——具身交互智能不干扰主流程

---

五、数据模型：从采集到评分的全链路持久化

项目数据模型用 SQLAlchemy 定义了从采集任务到 KOL 评分的完整数据结构：

class Influencer(Base):
    __tablename__ = "influencers"
    id = Column(Integer, primary_key=True, index=True)
    platform = Column(String(20), nullable=False)
    username = Column(String(200), nullable=False)
    url = Column(String(500), unique=True, nullable=False)
    display_name = Column(String(300), nullable=True)
    followers = Column(Integer, default=0)
    engagement_rate = Column(Float, default=0)
    avg_likes = Column(Float, default=0)
    avg_comments = Column(Float, default=0)
    posts_count = Column(Integer, default=0)
    is_verified = Column(Boolean, default=False)
    # KOL Score
    kol_score = Column(Float, default=0)
    score_followers = Column(Float, default=0)
    score_engagement = Column(Float, default=0)
    score_content = Column(Float, default=0)
    score_growth = Column(Float, default=0)
    score_business = Column(Float, default=0)
    kol_level = Column(String(20), nullable=True)  # S/A/B/C/D
    kol_suggestion = Column(Text, nullable=True)
    raw_data = Column(JSON, nullable=True)
    task_id = Column(Integer, nullable=True)

关键逻辑分析：

• 每个 Influencer 记录同时存储原始数据（followers/engagement_rate 等）与评分结果（kol_score/score_followers 等），方便前端直接渲染雷达图与排行榜
• kol_level 与 kol_suggestion 字段是数析语音播报的内容来源。当用户在 KOL 管理页面点击某位网红时，数析可以读取 kol_suggestion 直接播报合作建议
• raw_data 以 JSON 格式保存 Datasets API 返回的完整原始数据，确保评分算法迭代时可以重新计算而不需要重新采集

---

六、总结

本平台把具身交互智能嵌入了一条完整的数据情报链路：采集网红数据 → 五维量化评分 → 大屏可视化 → 竞品监测 → 告警推送。数字人数析不是锦上添花的装饰，而是贯穿全程的情报分析官——她自动迎接访客、在数据加载后播报关键洞察、在评分出炉后解读合作建议。

技术上，这套体验由三个关键设计支撑：

1. 魔珐参数流 SDK 集成：IIFE 封装的原生 JS 数字人服务，通过 window.AvatarService 暴露全局接口，connect/speakText/interrupt 三个核心方法覆盖连接、播报、打断全链路——这是具身交互智能在 React + Python 双层架构中的落地方案
2. KOL 五维评分引擎：293 行 Python 算法把原始数据转化为可解释的量化评分与合作建议，评分结果直接驱动数析的语音播报，让数据分析从图表走向对话
3. 品牌蓝玻璃态舞台：backdrop-filter 磨砂玻璃 + 品牌蓝描边 + canvas 130% 预留空间 + 字幕深色半透明底，让数字人在数据大屏上有专业、可信赖的视觉呈现

这条链路的本质是具身交互智能——AI 不只是后台的计算引擎，而是有形象、有声音、有肢体表达的情报分析官，把数据采集的能力、量化评分的分析能力与数字人的具身表达能力绑定在同一次交互里。当用户听到数析说出"当前共采集 128 位 KOL，S 级推荐 12 位，建议优先合作"的那一刻，数据才真正有了温度。

魔珐星云 PC 端官方链接：https://xingyun3d.com?utm_campaign=daily&utm_source=CSDNwanfen2&utm_medium=&utm_term=&utm_content=