🌟 辉仔 (HuiZai AI) - 你的智能语音伙伴

一个聪明、贴心的 AI 助手，集成 Live2D 数字人、RAG 检索增强、智能语音交互

认识辉仔 • 功能特性 • 快速开始 • 配置说明 • API文档

👋 认识辉仔

辉仔是一个功能完整的智能语音助手，将先进的 AI 技术与可爱的 Live2D 数字人形象完美结合。他不仅能听懂你说的话，还能记住你的习惯，帮你找资料，完成各种任务。

辉仔能做什么？

💬 自然对话 - 用流畅的语音和你聊天，像朋友一样交流
🧠 智能记忆 - 记住对话上下文和你的偏好，越聊越懂你
📚 知识问答 - 搜索本地文档库，快速找到你需要的答案
🎭 生动展示 - 以精美的 Live2D 数字人形象陪伴你
🔧 助手工具 - 查天气、搜索网络、设置提醒等实用功能
⚡ 即时响应 - 流式处理技术，边生成边播放，响应超快

辉仔集成了语音识别、自然语言处理、文档检索、语音合成等多项技术，提供流畅自然的人机交互体验。

✨ 核心亮点

🎭 Live2D 数字人 - 精美的虚拟形象展示，支持多种模型和表情动作
🧠 RAG 检索增强 - 基于 LangChain 的文档检索系统，智能问答更准确
🎤 全双工语音交互 - 实时 VAD 检测，支持打断和连续对话
⚡ 流式响应 - 边生成边播放，极致的响应速度
🔧 插件系统 - 灵活的工具调用框架，轻松扩展功能
💾 对话记忆 - 智能记忆管理，理解上下文和用户偏好
🌐 Web 界面 - 基于 FastAPI 的现代化 Web 应用

🎯 功能特性

核心功能

功能模块	说明	技术栈
语音识别 (ASR)	实时语音转文字	FunASR / Sherpa-ONNX
语音活动检测 (VAD)	精准检测语音开始/结束	Silero VAD
大语言模型 (LLM)	智能对话生成	DeepSeek / Ollama
文本转语音 (TTS)	多引擎语音合成	Edge TTS / ChatTTS / Kokoro
文档检索 (RAG)	本地文档智能问答	LangChain + Chroma
对话记忆	上下文理解和摘要	自研 Memory 系统
Live2D 展示	虚拟形象交互	Live2D SDK
插件系统	功能扩展框架	自研插件管理器

支持的 TTS 引擎

✅ Edge TTS - 微软 Edge 浏览器 TTS（推荐）
✅ ChatTTS - 开源高质量中文 TTS
✅ Kokoro TTS - 多语言 TTS 引擎
✅ gTTS - Google Text-to-Speech
✅ MacTTS - macOS 系统原生 TTS

支持的 LLM 模型

✅ DeepSeek - 高性能中文大模型（推荐）
✅ Ollama - 本地部署各类开源模型
✅ OpenAI 兼容 API - 支持所有兼容 OpenAI 格式的模型

内置插件功能

插件名称	功能描述
`search_local_documents`	搜索本地文档库
`get_weather`	查询天气信息
`get_day_of_week`	获取日期时间
`web_search`	网络搜索
`schedule_task`	定时任务提醒
`open_application`	打开本地应用
`aigc_manus`	AIGC 内容生成
`ielts_speaking_practice`	雅思口语练习

🚀 快速开始

系统要求

Python: 3.8 或更高版本
Node.js: 14+ (用于 Live2D 资源)
操作系统: Windows / macOS / Linux
内存: 建议 8GB 以上
GPU: 可选，用于加速模型推理

安装步骤

1. 克隆项目

git clone https://github.com/yourusername/rag_vtuber.git
cd rag_vtuber

2. 创建虚拟环境（推荐）

python -m venv venv

# Windows
venv\Scripts\activate

# macOS/Linux
source venv/bin/activate

3. 安装 Python 依赖

pip install -r requirements.txt

4. 安装 Node.js 依赖

npm install

5. 下载模型文件

ASR 模型 (FunASR SenseVoice):

# 将下载好的模型放到 models/SenseVoiceSmall/ 目录
mkdir -p models/SenseVoiceSmall
# 下载地址: https://www.modelscope.cn/models/iic/SenseVoiceSmall

Embedding 模型 (用于 RAG):

# BGE 小型中文嵌入模型会自动下载
# 或手动下载放到缓存目录

Ollama 模型（可选）:

# 安装 Ollama
curl -fsSL https://ollama.com/install.sh | sh

# 拉取模型
ollama pull qwen2.5:latest
ollama serve

6. 配置系统

编辑 config/config.yaml，配置 API Key 等信息：

LLM:
  OpenAILLM:
    model_name: deepseek-chat
    url: https://api.deepseek.com
    api_key: YOUR_API_KEY_HERE  # 替换为你的 API Key

Rag:
  model_name: deepseek-chat
  api_key: YOUR_API_KEY_HERE  # 替换为你的 API Key

7. 准备文档库（可选）

将你的文档放到 documents/ 目录：

# 支持的文档格式
documents/
├── example.md      # Markdown 文档
├── guide.pdf       # PDF 文档
└── notes.txt       # 文本文档

8. 启动服务

方式 1: 使用 Robot API 服务器（推荐）

python robot_server_launcher.py

访问: http://localhost:8001/robot_chat

方式 2: 使用 FastAPI 主服务

python main.py

访问: http://localhost:3000

方式 3: 命令行模式

python -m bailing.robot config/config.yaml

📁 项目结构

huizai/
├── src/                    # 核心模块目录
│   ├── robot.py               # Robot 主控制器
│   ├── asr.py                 # 语音识别模块
│   ├── vad.py                 # 语音活动检测
│   ├── llm.py                 # 大语言模型接口
│   ├── tts.py                 # 文本转语音
│   ├── rag.py                 # RAG 检索系统
│   ├── memory.py              # 对话记忆管理
│   ├── dialogue.py            # 对话历史管理
│   ├── recorder.py            # 音频录制
│   ├── player.py              # 音频播放
│   ├── streaming_tts.py       # 流式 TTS 处理
│   ├── robot_api_server.py    # Robot API 服务器
│   └── utils.py               # 工具函数
│
├── plugins/                    # 插件系统
│   ├── registry.py            # 插件注册表
│   ├── task_manager.py        # 任务管理器
│   ├── function_manager.py    # 函数管理器
│   ├── function_calls_config.json  # 工具配置
│   └── functions/             # 内置插件
│       ├── search_local_documents.py
│       ├── get_weather.py
│       ├── web_search.py
│       └── ...
│
├── config/                     # 配置文件
│   └── config.yaml            # 主配置文件
│
├── documents/                  # 文档库（RAG）
│   ├── README.md
│   └── test_doc.md
│
├── models/                     # Live2D 模型和 AI 模型
│   ├── Haru/                  # Live2D 模型
│   ├── EVA RIN normal/
│   ├── SenseVoiceSmall/       # ASR 模型
│   └── ...
│
├── tmp/                        # 临时文件
│   ├── memory.json            # 对话记忆
│   └── *.wav                  # 音频缓存
│
├── uploads/                    # 文件上传
├── js/                         # JavaScript 库
├── chroma_db/                  # 向量数据库
│
├── main.py                     # FastAPI 主应用
├── robot_server_launcher.py   # Robot 服务启动器
├── robot_live2d.html          # Live2D 界面
├── index.html                 # 主页
├── live2d.html                # Live2D 演示页
├── requirements.txt           # Python 依赖
├── package.json               # Node.js 依赖
└── README.md                  # 本文件

⚙️ 配置说明

核心配置文件: `config/config.yaml`

# 项目信息
name: 辉仔（huitu）
version: 1.0

# 日志级别
logging:
  level: debug

# 唤醒词（保留字段，暂未启用）
WakeWord: 辉仔

# 是否支持打断
interrupt: false

# 是否开启工具调用
StartTaskMode: true

# 前端音频播放模式
frontend_audio_mode: true

# 模块选择
selected_module:
  Recorder: RecorderPyAudio    # 音频录制
  ASR: FunASR                  # 语音识别
  VAD: SileroVAD               # 语音检测
  LLM: OpenAILLM               # 语言模型
  TTS: EdgeTTS                 # 语音合成
  Player: PygameSoundPlayer    # 音频播放

# ASR 配置
ASR:
  FunASR:
    model_dir: models/SenseVoiceSmall
    output_file: tmp/

# VAD 配置
VAD:
  SileroVAD:
    sampling_rate: 16000
    threshold: 0.7               # 阈值越高越不敏感
    min_silence_duration_ms: 500 # 静音持续时间

# LLM 配置
LLM:
  OpenAILLM:
    model_name: deepseek-chat
    url: https://api.deepseek.com
    api_key: sk-xxxxxxxxxxxx    # 你的 API Key

  OllamaLLM:
    model_name: qwen2.5:latest
    url: http://localhost:11434
    temperature: 0.7

# TTS 配置
TTS:
  EdgeTTS:
    voice: zh-CN-XiaoxiaoNeural  # 语音角色
    output_file: tmp/

  CHATTTS:
    output_file: tmp/

  KOKOROTTS:
    output_file: tmp/
    lang: z
    voice: zm_yunyang

# RAG 配置
Rag:
  doc_path: documents/
  emb_model: BAAI/bge-small-zh
  model_name: deepseek-chat
  url: https://api.deepseek.com
  api_key: sk-xxxxxxxxxxxx

# 记忆配置
Memory:
  dialogue_history_path: tmp/
  memory_file: tmp/memory.json
  model_name: deepseek-chat
  url: https://api.deepseek.com
  api_key: sk-xxxxxxxxxxxx

# 任务管理器配置
TaskManager:
  functions_call_name: plugins/function_calls_config.json
  aigc_manus_enabled: false

TTS 语音角色列表

中文女声推荐:

zh-CN-XiaoxiaoNeural - 晓晓（温柔）
zh-CN-XiaoyiNeural - 晓伊（亲切）
zh-CN-YunyangNeural - 云扬（成熟）

中文男声推荐:

zh-CN-YunxiNeural - 云希（年轻）
zh-CN-YunyeNeural - 云野（沉稳）

更多语音角色: Edge TTS 语音列表

🌐 API 文档

Robot API 服务器

基础信息:

Base URL: http://localhost:8001
WebSocket: ws://localhost:8001/ws/{client_id}

主要端点

方法	路径	说明
GET	`/`	主页
GET	`/robot_chat`	Robot 聊天界面
WebSocket	`/ws/{client_id}`	WebSocket 连接
GET	`/api/robot/status`	Robot 状态查询
POST	`/upload`	文件上传
GET	`/edge_tts`	Edge TTS 接口

WebSocket 消息格式

客户端发送:

// 用户文本输入
{
  "type": "user_input",
  "text": "你好"
}

// 工具调用
{
  "type": "tool_call",
  "tool_name": "get_weather",
  "arguments": {"city": "北京"}
}

// 音频播放完成通知
{
  "type": "audio_finished"
}

// 状态查询
{
  "type": "status_request"
}

服务器返回:

// 对话消息（流式）
{
  "type": "dialogue",
  "data": {
    "role": "assistant",
    "content": "你好！有什么可以帮助你的吗？",
    "type": "streaming",
    "message_id": "uuid",
    "is_complete": false,
    "tts_segments_generated": 1
  }
}

// TTS 音频
{
  "type": "tts_audio",
  "data": {
    "audio": "base64_encoded_audio",
    "text": "对应的文本",
    "sequence": 0
  }
}

// 工具调用开始
{
  "type": "tool_calling",
  "data": {
    "tool_name": "search_local_documents",
    "arguments": {"keyword": "API"}
  }
}

// 工具调用结果
{
  "type": "tool_result",
  "data": {
    "tool_name": "search_local_documents",
    "success": true,
    "result": "找到相关文档..."
  }
}

// VAD 状态
{
  "type": "vad_status",
  "data": {
    "status": "listening",
    "display": "🎤 语音检测活跃"
  }
}

FastAPI 主服务

基础信息:

Base URL: http://localhost:3000

主要端点

方法	路径	说明
GET	`/`	主页
GET	`/llm_edge_tts`	LLM + TTS 界面
POST	`/api/chat`	Ollama 代理接口
GET	`/edge_tts`	Edge TTS 合成
POST	`/upload`	文件上传
POST	`/asr`	语音识别接口

🔧 插件开发

创建自定义插件

1. 创建插件文件

在 plugins/functions/ 目录下创建新的 Python 文件：

# plugins/functions/my_custom_plugin.py

from plugins.registry import PluginRegistry, Action, Response

@PluginRegistry.register(
    name="my_custom_function",
    description="这是一个自定义插件示例",
    parameters={
        "type": "object",
        "properties": {
            "input_text": {
                "type": "string",
                "description": "输入参数说明"
            }
        },
        "required": ["input_text"]
    }
)
def my_custom_function(input_text: str) -> Response:
    """
    自定义插件功能实现

    Args:
        input_text: 输入文本

    Returns:
        Response: 插件响应对象
    """
    # 你的插件逻辑
    result = f"处理结果: {input_text}"

    # 返回响应
    return Response(
        action=Action.RESPONSE,  # 直接回复
        response=result
    )

2. 注册到配置文件

编辑 plugins/function_calls_config.json：

{
  "my_custom_function": {
    "type": "function",
    "function": {
      "name": "my_custom_function",
      "description": "这是一个自定义插件示例",
      "parameters": {
        "type": "object",
        "properties": {
          "input_text": {
            "type": "string",
            "description": "输入参数说明"
          }
        },
        "required": ["input_text"]
      }
    }
  }
}

3. Action 类型说明

Action.NOTFOUND      # 未找到函数
Action.NONE          # 执行完成，无需响应
Action.RESPONSE      # 直接回复用户
Action.REQLLM        # 调用 LLM 生成回复（用于 RAG）
Action.ADDSYSTEM     # 添加系统提示词
Action.ADDSYSTEMSPEAK # 添加系统提示词并主动说话

🎨 Live2D 模型

添加新模型

将 Live2D 模型文件放到 models/ 目录
确保包含以下文件：
- *.model3.json - 模型配置文件
- *.moc3 - 模型数据文件
- *.physics3.json - 物理配置（可选）
- 纹理文件和表情文件
在前端页面选择新模型

支持的模型格式

Live2D Cubism 3.0+
Live2D Cubism 4.0+

模型来源

🛠️ 故障排除

常见问题

1. ASR 模型加载失败

症状: 启动时报错 "Failed to load ASR model"

解决方案:

# 检查模型路径
ls models/SenseVoiceSmall/

# 确保包含必要文件
# 重新下载: https://www.modelscope.cn/models/iic/SenseVoiceSmall

2. VAD 过于敏感/不敏感

症状: 说话时频繁中断 / 说完话后需要等很久

解决方案:

# 编辑 config/config.yaml
VAD:
  SileroVAD:
    threshold: 0.5              # 降低阈值使其更敏感（0.3-0.9）
    min_silence_duration_ms: 300 # 缩短静音时间（100-1000）

3. TTS 无声音

症状: 对话正常但听不到声音

解决方案:

# 检查 Edge TTS 网络连接
curl -I https://speech.microsoft.com

# 或切换到离线 TTS
# 编辑 config/config.yaml
selected_module:
  TTS: CHATTTS  # 或 KOKOROTTS

4. RAG 检索无结果

症状: 文档搜索返回"未找到相关内容"

解决方案:

# 检查文档目录
ls documents/

# 删除旧的向量数据库重新索引
rm -rf chroma_db/
# 重启服务会自动重建索引

📈 性能优化

响应速度优化

使用本地 LLM
```
LLM:
  selected_module: OllamaLLM
```

调整 VAD 参数

VAD:
  min_silence_duration_ms: 300  # 更快响应

启用流式 TTS

frontend_audio_mode: true  # 边生成边播放

内存优化

定期清理缓存
```
rm -rf tmp/*.wav
rm -rf __pycache__
```
使用小模型
- 选择 7B 参数的模型而不是 70B
- 使用量化模型 (Q4, Q8)

📝 开发路线图

已完成 ✅

进行中 🚧

语音唤醒功能
多语言支持
移动端适配

计划中 📋

🤝 贡献指南

欢迎贡献代码、报告问题或提出建议！

如何贡献

Fork 本项目
创建特性分支 (git checkout -b feature/AmazingFeature)
提交更改 (git commit -m 'Add some AmazingFeature')
推送到分支 (git push origin feature/AmazingFeature)
开启 Pull Request

📄 许可证

本项目采用 MIT 许可证

🙏 致谢

本项目使用了以下开源项目：

pixi-live2d-display - Live2D 展示框架
bailing - 百聆语音对话机器人
FunASR - 阿里达摩院语音识别
Silero VAD - 语音活动检测
Edge TTS - 微软 Edge TTS
ChatTTS - 开源 TTS 引擎
LangChain - LLM 应用框架
Ollama - 本地 LLM 运行
FastAPI - 现代 Web 框架
Live2D Cubism SDK - 数字人展示

感谢所有贡献者和开源社区！

⬆ 回到顶部

Made with ❤️ by HuiZai Team

Name		Name	Last commit message	Last commit date
Latest commit History 5 Commits
config		config
doc/sample_conf		doc/sample_conf
documents		documents
js		js
plugins		plugins
src		src
third_party/OpenManus		third_party/OpenManus
.gitignore		.gitignore
README.md		README.md
app.js		app.js
asr_config.py		asr_config.py
config.json		config.json
index.html		index.html
live2d.html		live2d.html
main.py		main.py
package-lock.json		package-lock.json
package.json		package.json
requirements.txt		requirements.txt
robot_live2d.html		robot_live2d.html
robot_server_launcher.py		robot_server_launcher.py
timing_analysis.py		timing_analysis.py

Folders and files

Latest commit

History

Repository files navigation

🌟 辉仔 (HuiZai AI) - 你的智能语音伙伴

👋 认识辉仔

✨ 核心亮点

🎯 功能特性

核心功能

支持的 TTS 引擎

支持的 LLM 模型

内置插件功能

🚀 快速开始

系统要求

安装步骤

1. 克隆项目

2. 创建虚拟环境（推荐）

3. 安装 Python 依赖

4. 安装 Node.js 依赖

5. 下载模型文件

6. 配置系统

7. 准备文档库（可选）

8. 启动服务

📁 项目结构

⚙️ 配置说明

核心配置文件: config/config.yaml

TTS 语音角色列表

🌐 API 文档

Robot API 服务器

主要端点

WebSocket 消息格式

FastAPI 主服务

主要端点

🔧 插件开发

创建自定义插件

1. 创建插件文件

2. 注册到配置文件

3. Action 类型说明

🎨 Live2D 模型

添加新模型

支持的模型格式

模型来源

🛠️ 故障排除

常见问题

1. ASR 模型加载失败

2. VAD 过于敏感/不敏感

3. TTS 无声音

4. RAG 检索无结果

📈 性能优化

响应速度优化

内存优化

📝 开发路线图

已完成 ✅

进行中 🚧

计划中 📋

🤝 贡献指南

如何贡献

📄 许可证

🙏 致谢

本项目使用了以下开源项目：

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

核心配置文件: `config/config.yaml`

Packages