AI-XiaoPi 是一个开源的 AI 直播助手项目，旨在为直播间提供智能化的语音互动能力。与市面上昂贵的 SaaS 服务不同，AI-XiaoPi 允许你私有化部署，拥有完全的数据控制权，并且一次性硬件投入，无后续月租。

它不仅仅是一个软件+硬件机器人，更是一套打通了 ESP32 硬件终端、直播弹幕获取、大模型(LLM) 和 语音合成(TTS) 的完整链路。

适用场景： 24小时无人直播、智能客服答疑、游戏主播辅助、娱乐整活。

Windows平台一键启动包 网盘地址：https://pan.baidu.com/s/1p9SkXk7atcDsSb8eEx9SVQ?pwd=xnqb 提取码: xnqb

流程讲解 https://www.bilibili.com/video/BV1sDqEBQESd/?vd_source=12f6d76610175d37664858167b4e567a

我们采用模块化插件架构，支持市面上主流的 AI 服务，你可以像搭积木一样自由组合。

• 多种弹幕采集模式

  • 模拟模式：用于开发测试
  • 代理模式：通过 DouyinBarrageGrab 获取真实弹幕（推荐）
  • 直连模式：直接连接（需自行实现）

• 智能流量控制

  • 串行化处理：一次只处理一条弹幕
  • 自动忽略中间弹幕：只响应最新的弹幕
  • 防止音频堆积和播放混乱

• 灵活的AI配置

  • 支持多种LLM提供商（OpenAI, ChatGLM, Gemini等）
  • 支持多种TTS引擎（Edge TTS, 阿里云等）
  • 可自定义AI角色和回复风格

• 硬件设备支持

  • WebSocket连接管理
  • 设备自动发现和心跳检测
  • OTA固件更新接口

如果你想体验“实体机器人”的乐趣，建议购买以下配件（成本约 ¥100-200）。 注：没有硬件也可以使用“纯软件模式”运行！

1. 主控板： ESP32-S3 开发板 (推荐 N16R8 版本)
2. 音频模块： MAX98357 I2S 功放模块
3. 麦克风： INMP441 全向麦克风
4. 扬声器： 4Ω 3W 小喇叭
5. 外壳： 3D 打印模型 (STL 文件位于 doc/3d_models 目录)

(详细接线图请参考 docs/HARDWARE_SETUP.md)

• Python 3.8+
• (可选) 直播间
• (可选) ESP32硬件设备

1. 克隆项目

git clone <your-repo-url>
cd XiaoPi

2. 安装依赖

pip install -r requirements.txt

3. 配置服务

编辑 danmaku_config.yaml 文件：

danmaku:
  # 填写你的直播间ID（如果使用真实弹幕）
  room_id: your_room_id

  # 工作模式选择
  use_mock: false      # 是否使用模拟数据
  use_proxy: true      # 是否使用 DouyinBarrageGrab 代理
  proxy_ws_url: "ws://127.0.0.1:8888"

# 配置你的LLM（这里使用智谱GLM-4-Flash）
LLM:
  ChatGLMLLM:
    api_key: your_api_key_here

# 配置你的TTS（这里使用免费的Edge TTS）
TTS:
  EdgeTTS:
    voice: zh-CN-XiaoxiaoNeural

4. 启动服务

Linux/macOS:

./run_bot.sh

Windows:

run_bot.bat

或直接运行：

python run_bot.py

如果要获取真实的弹幕，需要先启动 DouyinBarrageGrab：

1. 进入 DouyinBarrageGrab 目录
2. 运行弹幕抓取服务（默认端口 8888）
3. 在浏览器中打开直播间并连接

详细说明请参考 DouyinBarrageGrab 目录下的 README。

┌─────────────┐
│ 直播间   │
└──────┬──────┘
       │ 弹幕消息
       ▼
┌─────────────────────┐
│ DouyinBarrageGrab   │ (可选代理)
└──────┬──────────────┘
       │ WebSocket
       ▼
┌─────────────────────┐
│ Danmaku Collector   │ 弹幕采集器
└──────┬──────────────┘
       │
       ▼
┌─────────────────────┐
│ Danmaku Handler     │ 弹幕处理器
│  - 串行化处理        │
│  - 流量控制          │
└──────┬──────────────┘
       │
       ▼
┌─────────────────────┐
│ LLM                 │ 生成回复
└──────┬──────────────┘
       │
       ▼
┌─────────────────────┐
│ TTS                 │ 转换为语音
└──────┬──────────────┘
       │
       ▼
┌─────────────────────┐
│ Device Manager      │ 设备管理
└──────┬──────────────┘
       │ WebSocket
       ▼
┌─────────────────────┐
│ ESP32 硬件设备       │ 播放语音
└─────────────────────┘

在弹幕密集的直播间，建议启用流量控制：

danmaku:
  flow_control_enabled: true
  flow_control_strategy: skip  # 推荐：跳过模式

• skip: 正在播放时直接丢弃新弹幕（推荐，体验最流畅）
• queue_limit: 限制待处理队列大小

在 danmaku_config.yaml 中自定义AI角色：

prompt: |
  你是一个直播间的AI助手，名叫小皮。
  回复简洁明快，每次回复控制在50字以内。
  语气活泼友好，适合直播间氛围。

支持多种LLM提供商，配置示例：

selected_module:
  LLM: ChatGLMLLM  # 或 OpenAILLM, GeminiLLM 等

LLM:
  ChatGLMLLM:
    type: openai
    model_name: glm-4-flash  # 免费模型
    api_key: your_api_key

支持多种TTS引擎，配置示例：

selected_module:
  TTS: EdgeTTS  # 或 AliyunTTS, DoubaoTTS 等

TTS:
  EdgeTTS:
    type: edge
    voice: zh-CN-XiaoxiaoNeural  # 中文女声

如果硬件设备不播放音频：

1. 检查设备是否正确连接（WebSocket日志）
2. 查看 Rate Controller 是否启动
3. 确认 sentence_id 正确设置（详见 SENTENCE_ID_FIX.md）

如果弹幕处理延迟或堆积：

1. 启用流量控制：flow_control_enabled: true
2. 使用跳过模式：flow_control_strategy: skip
3. 检查 LLM/TTS 响应时间

1. 确认 DouyinBarrageGrab 已启动
2. 检查 WebSocket 地址配置
3. 查看防火墙设置

• 架构说明 - 了解项目架构
• 弹幕接入指南 - 配置弹幕
• 串行化处理方案 - 了解弹幕处理机制
• Sentence ID 修复说明 - 音频播放问题修复

想要接入新的大模型？本项目采用插件化架构，添加新功能非常简单！ 只需在 core/providers/llm 下创建一个新文件，继承 BaseLLMProvider 类即可。

欢迎提交 PR 贡献你的插件！

• 发布 v1.0 核心功能 (LLM+TTS+直播流)
• v1.1: 增加 Web 管理后台 (可视化配置)
• v1.2: 增加硬件适配

本项目基于 MIT License 开源。

• xiaozhi-esp32 - ESP32硬件端开源项目
• xiaozhi-esp32-server - 后端服务基础框架
• DouyinBarrageGrab - 弹幕抓取
• 所有贡献者和用户

• Issue: 有 Bug 或建议请直接提 Issue。
• 微信: px11360
• Email: sysgiven@gmail.com

如果这个项目对你有帮助，请给一个 ⭐️ Star！你的支持是我们更新的动力！