Skip to content
This repository was archived by the owner on Apr 4, 2026. It is now read-only.

README.md

Latest commit

 

History

History
172 lines (120 loc) · 6.02 KB

README.md

File metadata and controls

172 lines (120 loc) · 6.02 KB
Raw

Open-XiaoAI x 小智 AI

Open-XiaoAI 的 Python 版 Server 端，用来演示小爱音箱接入小智 AI。

Important

本项目只是一个简单的演示程序，抛砖引玉。诸如一些音频压缩、加密传输、多账号管理等功能并未提供，建议只在局域网内测试运行，不推荐部署在公网服务器上（消耗流量 100kb/s），请自行评估相关风险，合理使用。

  • 小爱音箱接入小智 AI
  • 支持连续对话和中途打断
  • 自定义唤醒词（中英文）和提示语
  • 支持自定义消息处理，方便个人定制

快速开始

Note

继续下面的操作之前，你需要先在小爱音箱上启动运行 Rust 补丁程序 👉 教程

首先，克隆仓库代码到本地。

# 克隆代码
git clone https://github.com/idootop/open-xiaoai.git

# 进入当前项目根目录
cd examples/xiaozhi

然后把 config.py 文件里的配置修改成你自己的。

APP_CONFIG = {
    "wakeup": {
        # 自定义唤醒词
        "keywords": [
            "豆包豆包",
            "你好小智",
            "hi siri",
        ],
    },
    "xiaozhi": {
        "OTA_URL": "https://api.tenclass.net/xiaozhi/ota/",
        "WEBSOCKET_URL": "wss://api.tenclass.net/xiaozhi/v1/",
    },
}

Docker 运行

Docker Image Version

推荐使用以下命令，直接 Docker 一键运行。

docker run -it --rm -p 4399:4399 -v $(pwd)/config.py:/app/config.py idootop/open-xiaoai-xiaozhi:latest

编译运行

为了能够正常编译运行该项目，你需要安装以下依赖环境/工具：

# 安装 Python 依赖
uv sync --locked

# 编译运行（GUI 模式，不支持唤醒词唤醒）
uv run main.py

# 或者设置环境变量 CLI=true，开启 CLI 模式（支持自定义唤醒词）
CLI=true uv run main.py

如果你只是想体验一下小智 AI，请使用以下命令启动：

uv run main.py --mode xiaozhi

该模式下使用电脑的麦克风和扬声器作为音频输入输出设备，无需连接小爱音箱。

常见问题

Q：第一次运行提示我输入验证码绑定设备，如何操作？

第一次启动对话时，会有语音提示使用验证码绑定设备。请打开你的小智 AI 管理后台，然后根据提示创建 Agent 绑定设备即可。验证码消息会在终端打印，或者打开你的 config.py 文件查看。

APP_CONFIG = {
    "xiaozhi": {
        "VERIFICATION_CODE": "", # 首次对话时，验证码会在这里更新
        "DEVICE_ID": "", # 如果没有提示绑定设备，则将 DEVICE_ID 清空后，重启应用再次尝试
    },
    # ... 其他配置
}

如果能够正常和小智对话，但是没有收到绑定验证码的提示，说明随机生成的 DEVICE_ID 可能已经被其他设备绑定过了。

此时可以将 config.py 里生成的 DEVICE_ID 改回 "DEVICE_ID": ""，然后重新启动应用进入绑定流程。

PS：绑定设备成功后，可能需要重启应用才会生效。

Q：回答太长了，如何打断小智 AI 的回答？

直接召唤“小爱同学”，即可打断小智 AI 的回答 ;)

Q：有时候话还没说完 AI 就开始回答了，如何优化？

你可以调大 config.py 配置文件里的 min_silence_duration 参数，然后重启应用 / Docker 试试看。

APP_CONFIG = {
    "vad": {
        # 最小静默时长（ms）
        "min_silence_duration": 1000,
    },
    # ... 其他配置
}

Q：对话的时候，文字识别不是很准？

文字识别结果取决于你的小智 AI 服务器端的语音识别方案。

Q：唤醒词一直没有反应？

如果唤醒词还是不敏感，可以先调低 vad.threshold，然后重启应用 / Docker 试试看。

APP_CONFIG = {
    "vad": {
        # 语音检测阈值（0-1，越小越灵敏）
        "threshold": 0.05,
    },
    # ... 其他配置
}

另外，应用 / Docker 刚刚启动时需要加载模型文件，比较耗时一些，可以等 30s 之后再试试看。

如果是英文唤醒词，可以尝试将最小发音用空格分开，比如：比如：'openai' 👉 'open ai'

PS：如果还是不行，建议更换其他更易识别的唤醒词，比如“天猫精灵”。

Q：怎样使用自己部署的 xiaozhi-esp32-server 服务？

如果你想使用自己部署的 xiaozhi-esp32-server，请更新 config.py 文件里的接口地址，然后重启应用。

APP_CONFIG = {
    "xiaozhi": {
        "OTA_URL": "https://2662r3426b.vicp.fun/xiaozhi/ota/",
        "WEBSOCKET_URL": "wss://2662r3426b.vicp.fun/xiaozhi/v1/",
    },
    # ... 其他配置
}

Q: 我想自己编译运行，模型文件在哪里下载？

由于 ASR 相关模型文件体积较大，并未直接提交在 git 仓库中，你可以在 release 中下载 VAD + KWS 相关模型，然后解压到 xiaozhi/models 路径下即可。

相关项目

  • oxa-server: 提供了更强大易用的 config.py 的配置方式

鸣谢

该演示使用的 Python 版小智 AI 客户端基于 py-xiaozhi 项目，特此鸣谢。