AI Expression Engine - 虚拟人多模态情感引擎

🚀 在线体验：https://expression-frontend-289870540208.asia-east1.run.app

A dual-core hybrid emotion tagging engine for virtual characters, combining local keyword dictionaries with LLM semantic fallback.

基于「本地极速字典 + 大模型语义兜底」双核混合路由架构的虚拟人情感标注引擎。

项目简介：AI Expression Engine (虚拟人多模态情感引擎) 本项目是一个专为AI智能硬件（如桌面陪伴机器人、带屏智能音箱等）微小型屏幕设计的轻量级情感计算中枢。 在硬件设备进行语音播报的并发处理阶段，本引擎通过双核架构（本地规则字典 + 云端大模型 API）实时解析对话文本的语义与上下文意图，并精准输出高度匹配的细粒度情感标签。 支持虚拟人展示对应身体表情，提升交互体验。

🧠 核心架构：双核情感决策引擎

针对智能硬件（如桌面机器人、带屏音箱）计算资源受限、对交互延迟极度敏感的业务痛点，本项目后端采用了**“多级级联架构” (Cascade Processing)**。对外提供极简的统一调用入口，对内通过双引擎智能路由，在保障高可用性的同时实现了极致的降本增效。

📍 统一设备接口 (软硬件解耦)

• Endpoint: POST /api/analyze-emotion
• 设计理念: 硬件端（或前端）无需关心复杂的处理逻辑，只需发送对话文本。单一接口设计大幅降低了设备固件的对接与维护成本。

⚙️ 内部处理机制 (动态路由与降级)

1. 边缘/本地规则引擎 (快反射核)

• 触发机制: 优先拦截并匹配高频明确的情绪词库及正则规则。
• 业务价值:
  • 极速响应: 实现毫秒级返回，确保虚拟人表情与语音播报画音同步，告别交互迟滞感。
  • 成本控制: 零 Token 消耗，处理日常对话中 70% 的无业务逻辑交互。
  • 高可用兜底: 在云端 API 波动或设备处于弱网环境时，依然能提供基础的交互反馈，避免设备“变砖”。

2. 云端大模型 API (深思考核)

• 触发机制: 当本地引擎无法解析复杂语境、隐喻或长尾长句时，动态路由至云端大模型。
• 业务价值: 利用 LLM 强大的语义理解能力精准识别复杂情绪，保障产品体验的“高智商”上限。通过这种按需调用的策略，整体 API 调用费用较全量上云方案缩减了一大半。

---

Architecture / 架构

Input Text
    │
    ▼
┌─────────────────────┐
│  Smart Segmentation  │  ← 智能断句（中英文标点 + 逗号短语级切分）
│  Punctuation Absorb  │  ← 标点吸附 & 长尾符号合并 & 短句防碎片
└─────────┬───────────┘
          ▼
┌─────────────────────┐
│  Local Rule Engine   │  ← 本地关键词字典（微秒级响应）
│  EMOTION_RULES dict  │
└─────────┬───────────┘
          │ miss
          ▼
┌─────────────────────┐
│  LLM Semantic Route  │  ← 自定义 LLM (OpenAI / DeepSeek / MiniMax)
│  OpenAI-compatible   │     + Gemini API 双重兜底
└─────────┬───────────┘
          │ fail
          ▼
      [ neutral ]        ← 优雅降级

Features / 特性

• Dual-Core Hybrid Routing / 双核混合路由 — Local keyword matching (microsecond latency) with LLM semantic fallback for unrecognized expressions.
• Smart Segmentation / 智能断句 — Supports Chinese & English punctuation, comma-level phrase splitting, punctuation absorption, orphan symbol merging, and short-sentence anti-fragmentation.
• Multi-Provider LLM / 多供应商 LLM — Built-in presets for OpenAI, DeepSeek, MiniMax, and any OpenAI-compatible API.
• Connection Testing / 连接测试 — One-click LLM connection validation before processing.
• Atomic API / 原子化接口 — Dedicated single-sentence /api/analyze-emotion endpoint with emotion source tracing (local_rule / llm_fallback / default).
• SaaS-Grade UI / SaaS 级界面 — Modern React + Tailwind CSS V4 interface with left-right panel layout, emotion checkboxes, and chat-bubble result rendering.
• LocalStorage Persistence / 本地持久化 — LLM configuration auto-saved in browser.

Tech Stack / 技术栈

Layer	Technology
Backend	Node.js, Express, CORS
Frontend	React 19, Vite 8, Tailwind CSS V4
LLM Integration	OpenAI-compatible API, Google Gemini
Icons	Lucide React
HTTP Client	Axios

Quick Start / 快速开始

Prerequisites / 前置条件

• Node.js >= 18
• npm >= 9

Backend / 后端

cd ai-expression-engine
npm install
cp .env.template .env  # Configure your API keys
node server.js
# Server running at http://localhost:3000

Frontend / 前端

cd client
npm install
npm run dev
# UI available at http://localhost:5173

API Endpoints / 接口文档

POST /api/process-text

Batch process text into emotion-tagged script segments.

// Request
{
  "text": "哼，你这个小冤家！我今天很开心。",
  "allowedEmotions": ["angry_pout", "happy", "neutral"],
  "llmConfig": {
    "provider": "openai",
    "baseUrl": "https://api.openai.com/v1",
    "apiKey": "sk-...",
    "model": "gpt-3.5-turbo"
  }
}

// Response
{
  "success": true,
  "script": [
    { "text": "哼，你这个小冤家！", "emotion": "angry_pout" },
    { "text": "我今天很开心。", "emotion": "happy" }
  ]
}

POST /api/analyze-emotion

Single-sentence emotion analysis with source tracing.

// Request
{ "text": "哼，讨厌你" }

// Response
{
  "success": true,
  "text": "哼，讨厌你",
  "emotion": "angry_pout",
  "source": "local_rule"
}

POST /api/test-connection

Validate LLM API connectivity.

// Request
{ "provider": "openai", "baseUrl": "https://api.openai.com/v1", "apiKey": "sk-...", "model": "gpt-3.5-turbo" }

// Response
{ "success": true, "message": "连接测试成功" }

Supported Emotions / 支持的情感

ID	Label	Emoji
angry_pout	生气	💢
teasing	调侃	😏
happy	开心	😄
sad	难过	😢
anxious	焦虑	😰
neutral	中性	😐

Deployment / 部署

Docker images are provided for both backend and frontend:

# Backend
docker build -t ai-expression-engine-api .
docker run -p 3000:3000 --env-file .env ai-expression-engine-api

# Frontend
cd client
docker build -t ai-expression-engine-ui .
docker run -p 80:80 ai-expression-engine-ui

License / 许可

MIT