Realtime Multimodal Assistant

基于三个独立模块构建的 Web 端实时智能交互助手。项目采用 FastAPI 后端和浏览器前端，由 total 总控层统一调度人脸识别、视觉理解、智能语音对话三个模块，不合并各模块源码，只通过适配器接口进行调用。如果你有Claude code或者codex可以直接把本开源地址给到它,它能直接帮你复刻出来.

功能概览

• 摄像头实时预览与非镜像显示
• 人脸身份识别与浏览器端人脸注册
• 当前画面内容理解与底部实时描述展示
• 点击录音、点击结束后自动语音识别
• 多模态上下文融合问答
• AI 文本回复与语音播放
• 天气实时查询，例如“北京的天气如何”
• 统一 Web 页面调度三个独立 AI 模块

目录结构

realtime-multimodal-assistant/
├── people_face/      # 人脸识别独立模块
├── SmolVLM/          # 视觉理解独立模块
├── whisper_tts/      # 智能语音对话独立模块
├── total/            # Web 前端、FastAPI 后端、Orchestrator 总控层
├── .gitignore
├── LICENSE
└── README.md

核心架构

Web 前端
  ↓
FastAPI 后端
  ↓
Orchestrator 总控层
  ↓
统一适配器接口
  ├── 人脸识别模块
  ├── 视觉理解模块
  └── 智能语音对话模块

total/app/orchestrator.py 是总控层入口，负责把摄像头画面、人脸身份、画面描述、语音识别文本和天气查询结果组合成多模态上下文，再决定是否走本地规则、天气接口或大模型对话。

三个模块的技术实现

1. 人脸识别模块 people_face

人脸识别模块负责注册、编码、存储和检索人脸身份信息。模块通过摄像头或上传照片获取图像，先进行人脸检测与对齐，再提取人脸 embedding，并将身份信息写入本地 SQLite 数据库。向量检索部分使用 FAISS 索引保存和查询人脸特征，识别时把当前画面中的人脸向量与已注册向量进行相似度匹配，超过阈值后返回姓名和置信度。

开源仓库不包含任何已注册人脸照片、SQLite 数据库、FAISS 索引或 embedding 文件。使用者需要在本地运行后通过 Web 注册功能重新录入自己的身份。

2. 视觉理解模块 SmolVLM

视觉理解模块使用轻量视觉语言模型对当前摄像头帧进行图像描述。总控层不会持续阻塞等待模型，而是按固定间隔提交当前帧，由视觉模块返回自然语言描述，例如人物、背景、桌面物体和场景状态。项目中保留模型下载脚本和调用接口，模型权重需要使用者本地自行下载。

3. 智能语音对话模块 whisper_tts

语音模块负责一轮完整语音交互：浏览器录音结束后上传音频，后端调用语音识别得到文本，再结合总控层中的人脸身份、画面描述和用户问题生成回答，最后通过 TTS 输出语音文件供浏览器播放。模块支持通过 .env 配置大模型 API Key、语音模型路径和运行目录。

4. 总体模块 total

total 是本项目的统一程序入口，包含：

• run.py：启动 FastAPI Web 服务
• app/main.py：HTTP API 与静态页面
• app/orchestrator.py：多模态调度与上下文融合
• app/adapters/：对三个独立模块和天气接口的统一适配
• app/static/：浏览器端摄像头、录音、注册和结果展示逻辑
• tests/：基于 unittest 的核心逻辑测试

未开源内容

以下内容因为隐私、体积或密钥安全原因不会提交到 GitHub：

• 已注册人脸照片
• faces.sqlite3、faiss.index、embeddings.pkl
• 视觉语言模型权重
• Vosk / Whisper / TTS 等语音模型权重
• .env 本地密钥文件

仓库中保留 .env.example、模型下载脚本和 README 说明，使用者可以按说明在本地重新构建这些资源。

环境准备

建议使用 Python 3.10 或 3.11。

cd realtime-multimodal-assistant
python -m venv .venv
.\.venv\Scripts\activate
python -m pip install --upgrade pip
pip install -r total\requirements.txt
pip install -r people_face\requirements.txt
pip install -r SmolVLM\requirements.txt
pip install -r whisper_tts\requirements.txt

部分人脸识别依赖在 Windows 上可能需要 Visual C++ Build Tools。若 insightface 或 onnxruntime 安装失败，请先安装对应编译工具或使用预编译 wheel。

模型和数据构建

人脸数据库

首次运行时不需要已有数据库。启动 Web 后，在页面中上传照片并填写姓名即可注册人脸，系统会自动创建本地数据库和向量索引。

推荐把人脸数据目录放在本地私有目录，例如：

FACE_DATA_DIR=face_data_clean

视觉理解模型

SmolVLM/scripts/download_model.py 提供模型下载入口。下载后将模型放到 SmolVLM/models/，或在环境变量中配置自己的模型路径。

python SmolVLM\scripts\download_model.py

语音识别与语音合成模型

语音模块需要本地语音识别模型和 TTS 运行目录。参考 whisper_tts/.env.example 创建自己的 .env：

copy whisper_tts\.env.example whisper_tts\.env

如果使用 DeepSeek 或其他大模型服务，请只在本地 .env 中填写 API Key，不要提交到仓库。

总体配置

参考 total/.env.example 创建总控层配置：

copy total\.env.example total\.env

常用配置包括三个模块路径、数据目录、视觉理解刷新间隔、天气查询超时时间和对话模型参数。

运行项目

cd total
python run.py

浏览器访问：

http://127.0.0.1:8000

关闭服务时，在运行服务的终端按 Ctrl+C。

测试

本项目使用标准库 unittest：

cd total
python -m unittest discover -s tests -v

开源说明

本仓库采用 MIT License。代码可用于课程设计、实验展示和二次开发。涉及人脸、语音和摄像头数据时，请确保获得使用者授权，并遵守所在地区的数据安全与隐私保护要求。