File: README.md Copy Chapter

小智后端服务xiaozhi-esp32-server

适用人群 👥 Copy Chapter

本项目需要配合 ESP32 硬件设备使用。如果您已经购买了 ESP32 相关硬件，且成功对接过虾哥部署的后端服务，并希望独立搭建自己的
xiaozhi-esp32 后端服务，那么本项目非常适合您。

想看使用效果？请猛戳视频 🎥

警告 ⚠️ Copy Chapter

1、本项目为开源软件，本软件与对接的任何第三方API服务商（包括但不限于语音识别、大模型、语音合成等平台）均不存在商业合作关系，不为其服务质量及资金安全提供任何形式的担保。
建议使用者优先选择持有相关业务牌照的服务商，并仔细阅读其服务协议及隐私政策。本软件不托管任何账户密钥、不参与资金流转、不承担充值资金损失风险。

2、本项目功能未完善，且未通过网络安全测评，请勿在生产环境中使用。 如果您在公网环境中部署学习本项目，请务必做好必要的防护。

部署文档 Copy Chapter

本项目提供两种部署方式，请根据您的具体需求选择：

🚀 部署方式选择

常见问题及相关教程，可参考这个链接

💡 提示：以下是按最新代码部署后的测试平台，有需要可烧录测试，并发为6个，每天会清空数据，

智控台地址: https://2662r3426b.vicp.fun
智控台(h5版): https://2662r3426b.vicp.fun/h5/index.html

服务测试工具： https://2662r3426b.vicp.fun/test/
OTA接口地址: https://2662r3426b.vicp.fun/xiaozhi/ota/
Websocket接口地址: wss://2662r3426b.vicp.fun/xiaozhi/v1/

🚩 配置说明和推荐

[!Note]
本项目提供两种配置方案：

1. 入门全免费配置：适合个人家庭使用，所有组件均采用免费方案，无需额外付费。

2. 流式配置：适合演示、培训、超过2个并发等场景，采用流式处理技术，响应速度更快，体验更佳。

自0.5.2版本起，项目支持流式配置，相比早期版本，响应速度提升约2.5秒，显著改善用户体验。

如果您关心各组件的耗时，请查阅小智各组件性能测试报告，可按报告中的测试方法在您的环境中实际测试。

🔧 测试工具

本项目提供以下测试工具，帮助您验证系统和选择合适的模型：

💡 提示：测试模型速度时，只会测试配置了密钥的模型。

功能清单 ✨ Copy Chapter

已实现 ✅ Copy Section

正在开发 🚧 Copy Section

想了解具体开发计划进度，请点击这里。常见问题及相关教程，可参考这个链接

如果你是一名软件开发者，这里有一份《致开发者的公开信》，欢迎加入！

产品生态 👬 Copy Chapter

小智是一个生态，当你使用这个产品时，也可以看看其他在这个生态圈的优秀项目

本项目支持的平台/组件列表 📋 Copy Chapter

LLM 语言模型 Copy Section

实际上，任何支持 openai 接口调用的 LLM 均可接入使用。

VLLM 视觉模型 Copy Section

实际上，任何支持 openai 接口调用的 VLLM 均可接入使用。

TTS 语音合成 Copy Section

VAD 语音活动检测 Copy Section

ASR 语音识别 Copy Section

Voiceprint 声纹识别 Copy Section

Memory 记忆存储 Copy Section

Intent 意图识别 Copy Section

Rag 检索增强生成 Copy Section

鸣谢 🙏 Copy Chapter

File: docs/ali-sms-integration.md Copy Chapter

阿里云短信集成指南

登录阿里云控制台，进入“短信服务”页面：https://dysms.console.aliyun.com/overview

第一步 添加签名 Copy Chapter

以上步骤，会得到签名，请把它写入到智控台参数，aliyun.sms.sign_name

第二步 添加模版 Copy Chapter

以上步骤，会得到模版code，请把它写入到智控台参数，aliyun.sms.sms_code_template_code

注意，签名要等7个工作日，等运营商报备成功后才能发送成功。

注意，签名要等7个工作日，等运营商报备成功后才能发送成功。

注意，签名要等7个工作日，等运营商报备成功后才能发送成功。

可以等报备成功后，再继续往下操作。

第三步 创建短信账户和开通权限 Copy Chapter

登录阿里云控制台，进入“访问控制”页面：https://ram.console.aliyun.com/overview?activeTab=overview

以上步骤，会得到access_key_id和access_key_secret，请把它写入到智控台参数，aliyun.sms.access_key_id、aliyun.sms.access_key_secret

第四步 启动手机注册功能 Copy Chapter

1、正常来说，以上信息都填完后，会有这个效果，如果没有，可能缺少了某个步骤

2、开启允许非管理员用户可注册，将参数server.allow_user_register设置成true

3、开启手机注册功能，将参数server.enable_mobile_register设置成true

File: docs/contributor_open_letter.md Copy Chapter

致开发者的公开信

"春江水暖鸭先知，正是河豚欲上时！"

亲爱的朋友，我是John，是一名普通公司里的Java程序员，今天，我怀着无比真挚的心情，向热爱AI技术与创新的你发出这封公开信。

半年前我看到很多优秀的项目，比如Dify、Chat2DB等人工智能相关的项目，我在想，我要是能参与这些项目多好，可惜“报国无门，空打十年代码”。

我是2025年初刷到虾哥团队的视频，我非常好奇他是怎么实现的，我想复刻他们的后端服务，打造一个低成本民用贾维斯。很可惜现在做的作品依然只是一个人工智障，它并发低、没有灵魂，响应很慢，bug很多。

虾哥团队是我们学习的对象，我很想拥有像虾哥团队一样智能的小智后端服务。但是我也能理解虾哥不开源的决定。“一花独放不是春，百花齐放春满园”，人工智能遍地开花的时代，也许就在我们这代实现，我们可以用自己的双手，实现低成本民用贾维斯。我个人认为，他能实现的，我们也能实现，只是时间问题而已，我称之为“我们的取经之路”。

那么这条取经之路，我们会遇到什么困难？我想应该不少于八十一难。这一路必然会出现各种妖怪，当然也有神仙暗中帮助我们，也有人加入取经队伍。

以上内容，如果你觉得好笑。那我也觉得非常的幸运。我能够在你人生3万多天里博你笑五秒，也算是为你做了一次贡献。

民用低成本贾维斯这个想法，会失败吗，我不知道，但是我们普通人的一生，这种失败不是很常见吗？

未来，有一点是可以确定的，就一定会有人完全复刻虾哥团队的功能，实现民用低成本贾维斯。这个项目会是我们吗？

期待与你携手前行，共创未来。

John，2025.3.11，广州

附 开发贡献指南

项目目标 Copy Chapter

1. 民用低成本贾维斯解决方案

2. 智能联动周边硬件的解决方案

加入我们 Copy Chapter

我们热忱欢迎志同道合的朋友加入，共同为项目贡献力量。您可在这个链接查看我们近期要实现的功能，功能列表中还没指派相关人员处理的，正是急需您的参与。参与方式如下：

1、成为普通贡献者 Copy Section

Fork 项目，提交 PR，由开发者审核后合入主分支。

2、成为开发者 Copy Section

当你累计提交 3 次有效 PR 后，可以联系群主申请成为开发者，群主将邀请你加入独立的开发者群，共同探讨项目未来。

开发者开发流程 Copy Chapter

1. 创建新分支
   每个功能点请以新分支方式开发，分支名称应简洁明了，让人一眼看出所实现的功能，避免功能撞车。

2. 提交 PR 审核
   功能开发完成后，请在 GitHub 上提交 PR，由其他开发者审核，审核通过后合并入主分支。

File: docs/Deployment.md Copy Chapter

部署架构图

方式一：Docker只运行Server

0.8.2版本开始，本项目发行的docker镜像只支持x86架构，如果需要在arm64架构的CPU上部署，可按照这个教程在本机编译arm64的镜像。

1. 安装docker Copy Chapter

如果您的电脑还没安装docker，可以按照这里的教程安装：docker安装

安装好docker后，进继续。

1.1 手动部署 Copy Section

1.1.1 创建目录

安装完docker后，你需要为这个项目找一个安放配置文件的目录，例如我们可以新建一个文件夹叫xiaozhi-server。

创建好目录后，你需要在xiaozhi-server下面创建data文件夹和models文件夹，models下面还要再创建SenseVoiceSmall文件夹。

最终目录结构如下所示：

xiaozhi-server
  ├─ data
  ├─ models
     ├─ SenseVoiceSmall

1.1.2 下载语音识别模型文件

你需要下载语音识别的模型文件，因为本项目的默认语音识别用的是本地离线语音识别方案。可通过这个方式下载
跳转到下载语音识别模型文件

下载完后，回到本教程。

1.1.3 下载配置文件

你需要下载两个配置文件：docker-compose.yaml 和 config.yaml。需要从项目仓库下载这两个文件。

1.1.3.1 下载 docker-compose.yaml

用浏览器打开这个链接。

在页面的右侧找到名称为RAW按钮，在RAW按钮的旁边，找到下载的图标，点击下载按钮，下载docker-compose.yml文件。 把文件下载到你的
xiaozhi-server中。

下载完后，回到本教程继续往下。

1.1.3.2 创建 config.yaml

用浏览器打开这个链接。

在页面的右侧找到名称为RAW按钮，在RAW按钮的旁边，找到下载的图标，点击下载按钮，下载config.yaml文件。 把文件下载到你的
xiaozhi-server下面的data文件夹中，然后把config.yaml文件重命名为.config.yaml。

下载完配置文件后，我们确认一下整个xiaozhi-server里面的文件如下所示：

xiaozhi-server
  ├─ docker-compose.yml
  ├─ data
    ├─ .config.yaml
  ├─ models
     ├─ SenseVoiceSmall
       ├─ model.pt

如果你的文件目录结构也是上面的，就继续往下。如果不是，你就再仔细看看是不是漏操作了什么。

2. 配置项目文件 Copy Chapter

接下里，程序还不能直接运行，你需要配置一下，你到底使用的是什么模型。你可以看这个教程：
跳转到配置项目文件

配置完项目文件后，回到本教程继续往下。

3. 执行docker命令 Copy Chapter

打开命令行工具，使用终端或命令行工具 进入到你的xiaozhi-server，执行以下命令

docker compose up -d

执行完后，再执行以下命令，查看日志信息。

docker logs -f xiaozhi-esp32-server

这时，你就要留意日志信息，可以根据这个教程，判断是否成功了。跳转到运行状态确认

5. 版本升级操作 Copy Chapter

如果后期想升级版本，可以这么操作

5.1、备份好data文件夹中的.config.yaml文件，一些关键的配置到时复制到新的.config.yaml文件里。
请注意是对关键密钥逐个复制，不要直接覆盖。因为新的.config.yaml文件可能有一些新的配置项，旧的.config.yaml文件不一定有。

5.2、执行以下命令

docker stop xiaozhi-esp32-server
docker rm xiaozhi-esp32-server
docker stop xiaozhi-esp32-server-web
docker rm xiaozhi-esp32-server-web
docker rmi ghcr.nju.edu.cn/xinnan-tech/xiaozhi-esp32-server:server_latest
docker rmi ghcr.nju.edu.cn/xinnan-tech/xiaozhi-esp32-server:web_latest

5.3、重新按docker方式部署

方式二：本地源码只运行Server

1.安装基础环境 Copy Chapter

本项目使用conda管理依赖环境。如果不方便安装conda，需要根据实际的操作系统安装好libopus和ffmpeg。
如果确定使用conda，则安装好后，开始执行以下命令。

重要提示！windows 用户，可以通过安装Anaconda来管理环境。安装好Anaconda后，在开始那里搜索anaconda相关的关键词，
找到Anaconda Prpmpt，使用管理员身份运行它。如下图。

运行之后，如果你能看到命令行窗口前面有一个(base)字样，说明你成功进入了conda环境。那么你就可以执行以下命令了。

conda remove -n xiaozhi-esp32-server --all -y
conda create -n xiaozhi-esp32-server python=3.10 -y
conda activate xiaozhi-esp32-server

# 添加清华源通道
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/free
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/conda-forge

conda install libopus -y
conda install ffmpeg -y

# 在 Linux 环境下进行部署时,如出现类似缺失 libiconv.so.2 动态库的报错 请通过以下命令进行安装
conda install libiconv -y

请注意，以上命令，不是一股脑执行就成功的，你需要一步步执行，每一步执行完后，都检查一下输出的日志，查看是否成功。

2.安装本项目依赖 Copy Chapter

你先要下载本项目源码，源码可以通过git clone命令下载，如果你不熟悉git clone命令。

你可以用浏览器打开这个地址https://github.com/xinnan-tech/xiaozhi-esp32-server.git

打开完，找到页面中一个绿色的按钮，写着Code的按钮，点开它，然后你就看到Download ZIP的按钮。

点击它，下载本项目源码压缩包。下载到你电脑后，解压它，此时它的名字可能叫xiaozhi-esp32-server-main
你需要把它重命名成xiaozhi-esp32-server，在这个文件里，进入到main文件夹，再进入到xiaozhi-server，好了请记住这个目录xiaozhi-server。

# 继续使用conda环境
conda activate xiaozhi-esp32-server
# 进入到你的项目根目录，再进入main/xiaozhi-server
cd main/xiaozhi-server
pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/
pip install -r requirements.txt

3.下载语音识别模型文件 Copy Chapter

你需要下载语音识别的模型文件，因为本项目的默认语音识别用的是本地离线语音识别方案。可通过这个方式下载
跳转到下载语音识别模型文件

下载完后，回到本教程。

4.配置项目文件 Copy Chapter

接下来，程序还不能直接运行，你需要配置一下，你到底使用的是什么模型。你可以看这个教程：
跳转到配置项目文件

5.运行项目 Copy Chapter

# 确保在xiaozhi-server目录下执行
conda activate xiaozhi-esp32-server
python app.py

这时，你就要留意日志信息，可以根据这个教程，判断是否成功了。跳转到运行状态确认

汇总

配置项目 Copy Chapter

如果你的xiaozhi-server目录没有data，你需要创建data目录。
如果你的data下面没有.config.yaml文件，有两个方式，任选一种：

第一个方式：你可以把xiaozhi-server目录下的config.yaml文件复制到data，并重命名为.config.yaml。在此文件上修改

第二个方式：你也可以创建在data目录下手动创建.config.yaml空文件，然后在这个文件中增加必要的配置信息，系统会优先读取.config.yaml文件的配置，如果.config.yaml没有配置的，系统会自动去加载xiaozhi-server目录下的config.yaml的配置。推荐使用这种方式，这种方式是最简洁的方式。

• 默认的LLM使用的是ChatGLMLLM，你需要配置密钥，因为他们的模型，虽然有免费的，但是仍要去官网注册密钥，才能启动。

以下是一个能正常跑起来的，最简单的.config.yaml配置示例

server:
  websocket: ws://你的ip或者域名:端口号/xiaozhi/v1/
prompt: |
  我是一个叫小智/小志的台湾女孩，说话机车，声音好听，习惯简短表达，爱用网络梗。
  我的男朋友是一个程序员，梦想是开发出一个机器人，能够帮助人们解决生活中的各种问题。
  我是一个喜欢哈哈大笑的女孩，爱东说西说吹牛，不合逻辑的也照吹，就要逗别人开心。
  请你像一个人一样说话，请勿返回配置xml及其他特殊字符。

selected_module:
  LLM: DoubaoLLM

LLM:
  ChatGLMLLM:
    api_key: xxxxxxxxxxxxxxx.xxxxxx

建议先将最简单的配置运行起来，然后再去xiaozhi/config.yaml阅读配置的使用说明。
比如你要换更换模型，修改selected_module下的配置就行。

模型文件 Copy Chapter

本项目语音识别模型，默认使用SenseVoiceSmall模型，进行语音转文字。因为模型较大，需要独立下载，下载后把model.pt
文件放在models/SenseVoiceSmall
目录下。下面两个下载路线任选一个。

• 线路一：阿里魔搭下载SenseVoiceSmall
• 线路二：百度网盘下载SenseVoiceSmall 提取码:
  qvna

运行状态确认 Copy Chapter

如果你能看到，类似以下日志,则是本项目服务启动成功的标志。

250427 13:04:20[0.3.11_SiFuChTTnofu][__main__]-INFO-OTA接口是           http://192.168.4.123:8003/xiaozhi/ota/
250427 13:04:20[0.3.11_SiFuChTTnofu][__main__]-INFO-Websocket地址是     ws://192.168.4.123:8000/xiaozhi/v1/
250427 13:04:20[0.3.11_SiFuChTTnofu][__main__]-INFO-=======上面的地址是websocket协议地址，请勿用浏览器访问=======
250427 13:04:20[0.3.11_SiFuChTTnofu][__main__]-INFO-如想测试websocket请启动digital-human模块，打开浏览器交互测试
250427 13:04:20[0.3.11_SiFuChTTnofu][__main__]-INFO-=======================================================

正常来说，如果您是通过源码运行本项目，日志会有你的接口地址信息。
但是如果你用docker部署，那么你的日志里给出的接口地址信息就不是真实的接口地址。

最正确的方法，是根据电脑的局域网IP来确定你的接口地址。
如果你的电脑的局域网IP比如是192.168.1.25，那么你的接口地址就是：ws://192.168.1.25:8000/xiaozhi/v1/，对应的OTA地址就是：http://192.168.1.25:8003/xiaozhi/ota/。

这个信息很有用的，后面编译esp32固件需要用到。

接下来，你就可以开始操作你的esp32设备了，你可以自行编译esp32固件也可以配置使用虾哥编译好的1.6.1以上版本的固件。两个任选一个

1、 编译自己的esp32固件了。

2、 基于虾哥编译好的固件配置自定义服务器了。

常见问题

以下是一些常见问题，供参考：

1、为什么我说的话，小智识别出来很多韩文、日文、英文
2、为什么会出现“TTS 任务出错 文件不存在”？
3、TTS 经常失败，经常超时
4、使用Wifi能连接自建服务器，但是4G模式却接不上
5、如何提高小智对话响应速度？
6、我说话很慢，停顿时小智老是抢话

部署相关教程 Copy Chapter

1、如何自动拉取本项目最新代码自动编译和启动
2、如何部署MQTT网关开启MQTT+UDP协议
3、如何与Nginx集成

拓展相关教程 Copy Chapter

1、如何开启手机号码注册智控台
2、如何集成HomeAssistant实现智能家居控制
3、如何开启视觉模型实现拍照识物
4、如何部署MCP接入点
5、如何接入MCP接入点
6、如何开启声纹识别
7、新闻插件源配置指南
8、天气插件使用指南

语音克隆、本地语音部署相关教程 Copy Chapter

1、如何在智控台克隆音色
2、如何部署集成index-tts本地语音
3、如何部署集成fish-speech本地语音
4、如何部署集成PaddleSpeech本地语音

性能测试教程 Copy Chapter

1、各组件速度测试指南
2、定期公开测试结果

File: docs/Deployment_all.md Copy Chapter

部署架构图

方式一：Docker运行全模块

0.8.2版本开始，本项目发行的docker镜像只支持x86架构，如果需要在arm64架构的CPU上部署，可按照这个教程在本机编译arm64的镜像。

1. 安装docker Copy Chapter

如果您的电脑还没安装docker，可以按照这里的教程安装：docker安装

docker 安装全模块有两种方式，你可以使用懒人脚本（作者@VanillaNahida）
脚本会自动帮你下载所需的文件和配置文件，你也可以使用手动部署从零搭建。

1.1 懒人脚本 Copy Section

部署简便，可以参考视频教程 ，文字版教程如下：

[!NOTE]
暂且只支持Ubuntu服务器一键部署，其他系统未尝试，可能会有一些奇怪的bug

使用SSH工具连接到服务器，以root权限执行如下脚本

sudo bash -c "$(wget -qO- https://ghfast.top/https://raw.githubusercontent.com/xinnan-tech/xiaozhi-esp32-server/main/docker-setup.sh)"

脚本会自动完成以下操作：

1. 安装Docker
2. 配置镜像源
3. 下载/拉取镜像
4. 下载语音识别模型文件
5. 引导配置服务端

执行完成后简单配置后，再参照[4. 运行程序](#4. 运行程序)和5.重启xiaozhi-esp32-server里提到的最重要的3件事情，完成3这三项配置后即可使用。

1.2 手动部署 Copy Section

1.2.1 创建目录

安装完后，你需要为这个项目找一个安放配置文件的目录，例如我们可以新建一个文件夹叫xiaozhi-server。

创建好目录后，你需要在xiaozhi-server下面创建data文件夹和models文件夹，models下面还要再创建SenseVoiceSmall文件夹。

最终目录结构如下所示：

xiaozhi-server
  ├─ data
  ├─ models
     ├─ SenseVoiceSmall

1.2.2 下载语音识别模型文件

本项目语音识别模型，默认使用SenseVoiceSmall模型，进行语音转文字。因为模型较大，需要独立下载，下载后把model.pt
文件放在models/SenseVoiceSmall
目录下。下面两个下载路线任选一个。

• 线路一：阿里魔搭下载SenseVoiceSmall
• 线路二：百度网盘下载SenseVoiceSmall 提取码:
  qvna

1.2.3 下载配置文件

你需要下载两个配置文件：docker-compose_all.yaml 和 config_from_api.yaml。需要从项目仓库下载这两个文件。

1.2.3.1 下载 docker-compose_all.yaml

用浏览器打开这个链接。

在页面的右侧找到名称为RAW按钮，在RAW按钮的旁边，找到下载的图标，点击下载按钮，下载docker-compose_all.yml文件。 把文件下载到你的
xiaozhi-server中。

或者直接执行 wget https://raw.githubusercontent.com/xinnan-tech/xiaozhi-esp32-server/refs/heads/main/main/xiaozhi-server/docker-compose_all.yml 下载。

下载完后，回到本教程继续往下。

1.2.3.2 下载 config_from_api.yaml

用浏览器打开这个链接。

在页面的右侧找到名称为RAW按钮，在RAW按钮的旁边，找到下载的图标，点击下载按钮，下载config_from_api.yaml文件。 把文件下载到你的
xiaozhi-server下面的data文件夹中，然后把config_from_api.yaml文件重命名为.config.yaml。

或者直接执行 wget https://raw.githubusercontent.com/xinnan-tech/xiaozhi-esp32-server/refs/heads/main/main/xiaozhi-server/config_from_api.yaml 下载保存。

下载完配置文件后，我们确认一下整个xiaozhi-server里面的文件如下所示：

xiaozhi-server
  ├─ docker-compose_all.yml
  ├─ data
    ├─ .config.yaml
  ├─ models
     ├─ SenseVoiceSmall
       ├─ model.pt

如果你的文件目录结构也是上面的，就继续往下。如果不是，你就再仔细看看是不是漏操作了什么。

2. 备份数据 Copy Chapter

如果你之前已经成功运行智控台，如果上面保存有你的密钥信息，请先从智控台上拷贝重要数据下来。因为升级过程中，有可能会覆盖原来的数据。

3. 清除历史版本镜像和容器 Copy Chapter

接下来打开命令行工具，使用终端或命令行工具 进入到你的xiaozhi-server，执行以下命令

docker compose -f docker-compose_all.yml down

docker stop xiaozhi-esp32-server
docker rm xiaozhi-esp32-server

docker stop xiaozhi-esp32-server-web
docker rm xiaozhi-esp32-server-web

docker stop xiaozhi-esp32-server-db
docker rm xiaozhi-esp32-server-db

docker stop xiaozhi-esp32-server-redis
docker rm xiaozhi-esp32-server-redis

docker rmi ghcr.nju.edu.cn/xinnan-tech/xiaozhi-esp32-server:server_latest
docker rmi ghcr.nju.edu.cn/xinnan-tech/xiaozhi-esp32-server:web_latest

4. 运行程序 Copy Chapter

执行以下命令启动新版本容器

docker compose -f docker-compose_all.yml up -d

执行完后，再执行以下命令，查看日志信息。

docker logs -f xiaozhi-esp32-server-web

当你看到输出日志时，说明你的智控台启动成功了。

2025-xx-xx 22:11:12.445 [main] INFO  c.a.d.s.b.a.DruidDataSourceAutoConfigure - Init DruidDataSource
2025-xx-xx 21:28:53.873 [main] INFO  xiaozhi.AdminApplication - Started AdminApplication in 16.057 seconds (process running for 17.941)
http://localhost:8002/xiaozhi/doc.html

请注意此刻仅是智控台能运行，如果8000端口xiaozhi-esp32-server报错，先不要理会。

这时，你需要使用浏览器，打开智控台，链接：http://127.0.0.1:8002 ，注册第一个用户。第一个用户即是超级管理员，以后的用户都是普通用户。普通用户只能绑定设备和配置智能体;超级管理员可以进行模型管理、用户管理、参数配置等功能。

接下来要做三件重要的事情：

第一件重要的事情 Copy Section

使用超级管理员账号，登录智控台，在顶部菜单找到参数管理，找到列表中第一条数据，参数编码是server.secret，复制它到参数值。

server.secret需要说明一下，这个参数值很重要，作用是让我们的Server端连接manager-api。server.secret是每次从零部署manager模块时，会自动随机生成的密钥。

复制参数值后，打开xiaozhi-server下的data目录的.config.yaml文件。此刻你的配置文件内容应该是这样的：

manager-api:
  url:  http://127.0.0.1:8002/xiaozhi
  secret: 你的server.secret值

1、把你刚才从智控台复制过来的server.secret的参数值复制到.config.yaml文件里的secret里。

2、因为你是docker部署，把url改成下面的http://xiaozhi-esp32-server-web:8002/xiaozhi

3、因为你是docker部署，把url改成下面的http://xiaozhi-esp32-server-web:8002/xiaozhi

4、因为你是docker部署，把url改成下面的http://xiaozhi-esp32-server-web:8002/xiaozhi

类似这样的效果

manager-api:
  url: http://xiaozhi-esp32-server-web:8002/xiaozhi
  secret: 12345678-xxxx-xxxx-xxxx-123456789000

保存好后，继续往下做第二件重要的事情

第二件重要的事情 Copy Section

使用超级管理员账号，登录智控台，在顶部菜单找到模型配置，然后在左侧栏点击大语言模型，找到第一条数据智谱AI，点击修改按钮，
弹出修改框后，将你注册到的智谱AI的密钥填写到API密钥中。然后点击保存。

5.重启xiaozhi-esp32-server Copy Chapter

接下来打开命令行工具，使用终端或命令行工具 输入

docker restart xiaozhi-esp32-server
docker logs -f xiaozhi-esp32-server

如果你能看到，类似以下日志,则是Server启动成功的标志。

25-02-23 12:01:09[core.websocket_server] - INFO - Websocket地址是      ws://xxx.xx.xx.xx:8000/xiaozhi/v1/
25-02-23 12:01:09[core.websocket_server] - INFO - =======上面的地址是websocket协议地址，请勿用浏览器访问=======
25-02-23 12:01:09[core.websocket_server] - INFO - 如想测试websocket请启动digital-human模块，打开浏览器交互测试
25-02-23 12:01:09[core.websocket_server] - INFO - =======================================================

由于你是全模块部署，因此你有两个重要的接口需要写入到esp32中。

OTA接口：

http://你宿主机局域网的ip:8002/xiaozhi/ota/

Websocket接口：

ws://你宿主机的ip:8000/xiaozhi/v1/

第三件重要的事情 Copy Section

使用超级管理员账号，登录智控台，在顶部菜单找到参数管理，找到参数编码是server.websocket，输入你的Websocket接口。

使用超级管理员账号，登录智控台，在顶部菜单找到参数管理，找到数编码是server.ota，输入你的OTA接口。

接下来，你就可以开始操作你的esp32设备了，你可以自行编译esp32固件也可以配置使用虾哥编译好的1.6.1以上版本的固件。两个任选一个

1、 编译自己的esp32固件了。

2、 基于虾哥编译好的固件配置自定义服务器了。

方式二：本地源码运行全模块

1.安装MySQL数据库 Copy Chapter

如果本机已经安装了MySQL，可以直接在数据库中创建名为xiaozhi_esp32_server的数据库。

CREATE DATABASE xiaozhi_esp32_server CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

如果还没有MySQL，你可以通过docker安装mysql

docker run --name xiaozhi-esp32-server-db -e MYSQL_ROOT_PASSWORD=123456 -p 3306:3306 -e MYSQL_DATABASE=xiaozhi_esp32_server -e MYSQL_INITDB_ARGS="--character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci" -e TZ=Asia/Shanghai -d mysql:latest

2.安装redis Copy Chapter

如果还没有Redis，你可以通过docker安装redis

docker run --name xiaozhi-esp32-server-redis -d -p 6379:6379 redis

3.运行manager-api程序 Copy Chapter

3.1 安装JDK21，设置JDK环境变量

3.2 安装Maven，设置Maven环境变量

3.3 使用Vscode编程工具，安装好Java环境相关插件

3.4 使用Vscode编程工具加载manager-api模块

在src/main/resources/application-dev.yml中配置数据库连接信息

spring:
  datasource:
    username: root
    password: 123456

在src/main/resources/application-dev.yml中配置Redis连接信息

spring:
    data:
      redis:
        host: localhost
        port: 6379
        password:
        database: 0

3.5 运行主程序

本项目为SpringBoot项目，启动方式为：
打开Application.java运行Main方法启动

路径地址：
src/main/java/xiaozhi/AdminApplication.java

当你看到输出日志时，说明你的manager-api启动成功了。

2025-xx-xx 22:11:12.445 [main] INFO  c.a.d.s.b.a.DruidDataSourceAutoConfigure - Init DruidDataSource
2025-xx-xx 21:28:53.873 [main] INFO  xiaozhi.AdminApplication - Started AdminApplication in 16.057 seconds (process running for 17.941)
http://localhost:8002/xiaozhi/doc.html

4.运行manager-web程序 Copy Chapter

4.1 安装nodejs

4.2 使用Vscode编程工具加载manager-web模块

终端命令进入manager-web目录下

npm install

然后启动

npm run serve

请注意，如果你的manager-api的接口不在http://localhost:8002，请在开发时，修改
main/manager-web/.env.development中的路径

运行成功后，你需要使用浏览器，打开智控台，链接：http://127.0.0.1:8001 ，注册第一个用户。第一个用户即是超级管理员，以后的用户都是普通用户。普通用户只能绑定设备和配置智能体;超级管理员可以进行模型管理、用户管理、参数配置等功能。

重要：注册成功后，使用超级管理员账号，登录智控台，在顶部菜单找到模型配置，然后在左侧栏点击大语言模型，找到第一条数据智谱AI，点击修改按钮，
弹出修改框后，将你注册到的智谱AI的密钥填写到API密钥中。然后点击保存。

重要：注册成功后，使用超级管理员账号，登录智控台，在顶部菜单找到模型配置，然后在左侧栏点击大语言模型，找到第一条数据智谱AI，点击修改按钮，
弹出修改框后，将你注册到的智谱AI的密钥填写到API密钥中。然后点击保存。

重要：注册成功后，使用超级管理员账号，登录智控台，在顶部菜单找到模型配置，然后在左侧栏点击大语言模型，找到第一条数据智谱AI，点击修改按钮，
弹出修改框后，将你注册到的智谱AI的密钥填写到API密钥中。然后点击保存。

5.安装Python环境 Copy Chapter

本项目使用conda管理依赖环境。如果不方便安装conda，需要根据实际的操作系统安装好libopus和ffmpeg。
如果确定使用conda，则安装好后，开始执行以下命令。

重要提示！windows 用户，可以通过安装Anaconda来管理环境。安装好Anaconda后，在开始那里搜索anaconda相关的关键词，
找到Anaconda Prpmpt，使用管理员身份运行它。如下图。

运行之后，如果你能看到命令行窗口前面有一个(base)字样，说明你成功进入了conda环境。那么你就可以执行以下命令了。

conda remove -n xiaozhi-esp32-server --all -y
conda create -n xiaozhi-esp32-server python=3.10 -y
conda activate xiaozhi-esp32-server

# 添加清华源通道
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/free
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/conda-forge

conda install libopus -y
conda install ffmpeg -y

# 在 Linux 环境下进行部署时,如出现类似缺失 libiconv.so.2 动态库的报错 请通过以下命令进行安装
conda install libiconv -y

请注意，以上命令，不是一股脑执行就成功的，你需要一步步执行，每一步执行完后，都检查一下输出的日志，查看是否成功。

6.安装本项目依赖 Copy Chapter

你先要下载本项目源码，源码可以通过git clone命令下载，如果你不熟悉git clone命令。

你可以用浏览器打开这个地址https://github.com/xinnan-tech/xiaozhi-esp32-server.git

打开完，找到页面中一个绿色的按钮，写着Code的按钮，点开它，然后你就看到Download ZIP的按钮。

点击它，下载本项目源码压缩包。下载到你电脑后，解压它，此时它的名字可能叫xiaozhi-esp32-server-main
你需要把它重命名成xiaozhi-esp32-server，在这个文件里，进入到main文件夹，再进入到xiaozhi-server，好了请记住这个目录xiaozhi-server。

# 继续使用conda环境
conda activate xiaozhi-esp32-server
# 进入到你的项目根目录，再进入main/xiaozhi-server
cd main/xiaozhi-server
pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/
pip install -r requirements.txt

7.下载语音识别模型文件 Copy Section

本项目语音识别模型，默认使用SenseVoiceSmall模型，进行语音转文字。因为模型较大，需要独立下载，下载后把model.pt
文件放在models/SenseVoiceSmall
目录下。下面两个下载路线任选一个。

• 线路一：阿里魔搭下载SenseVoiceSmall
• 线路二：百度网盘下载SenseVoiceSmall 提取码:
  qvna

8.配置项目文件 Copy Chapter

使用超级管理员账号，登录智控台 ，在顶部菜单找到参数管理，找到列表中第一条数据，参数编码是server.secret，复制它到参数值。

server.secret需要说明一下，这个参数值很重要，作用是让我们的Server端连接manager-api。server.secret是每次从零部署manager模块时，会自动随机生成的密钥。

如果你的xiaozhi-server目录没有data，你需要创建data目录。
如果你的data下面没有.config.yaml文件，你可以把xiaozhi-server目录下的config_from_api.yaml文件复制到data，并重命名为.config.yaml

复制参数值后，打开xiaozhi-server下的data目录的.config.yaml文件。此刻你的配置文件内容应该是这样的：

manager-api:
  url: http://127.0.0.1:8002/xiaozhi
  secret: 你的server.secret值

把你刚才从智控台复制过来的server.secret的参数值复制到.config.yaml文件里的secret里。

类似这样的效果

manager-api:
  url: http://127.0.0.1:8002/xiaozhi
  secret: 12345678-xxxx-xxxx-xxxx-123456789000

9.运行项目 Copy Chapter

# 确保在xiaozhi-server目录下执行
conda activate xiaozhi-esp32-server
python app.py

如果你能看到，类似以下日志,则是本项目服务启动成功的标志。

25-02-23 12:01:09[core.websocket_server] - INFO - Server is running at ws://xxx.xx.xx.xx:8000/xiaozhi/v1/
25-02-23 12:01:09[core.websocket_server] - INFO - =======上面的地址是websocket协议地址，请勿用浏览器访问=======
25-02-23 12:01:09[core.websocket_server] - INFO - 如想测试websocket请启动digital-human模块，打开浏览器交互测试
25-02-23 12:01:09[core.websocket_server] - INFO - =======================================================

由于你是全模块部署，因此你有两个重要的接口。

OTA接口：

http://你电脑局域网的ip:8002/xiaozhi/ota/

Websocket接口：

ws://你电脑局域网的ip:8000/xiaozhi/v1/

请你务必把以上两个接口地址写入到智控台中：他们将会影响websocket地址发放和自动升级功能。

1、使用超级管理员账号，登录智控台，在顶部菜单找到参数管理，找到参数编码是server.websocket，输入你的Websocket接口。

2、使用超级管理员账号，登录智控台，在顶部菜单找到参数管理，找到数编码是server.ota，输入你的OTA接口。

接下来，你就可以开始操作你的esp32设备了，你可以自行编译esp32固件也可以配置使用虾哥编译好的1.6.1以上版本的固件。两个任选一个

1、 编译自己的esp32固件了。

2、 基于虾哥编译好的固件配置自定义服务器了。

常见问题

以下是一些常见问题，供参考：

1、为什么我说的话，小智识别出来很多韩文、日文、英文
2、为什么会出现“TTS 任务出错 文件不存在”？
3、TTS 经常失败，经常超时
4、使用Wifi能连接自建服务器，但是4G模式却接不上
5、如何提高小智对话响应速度？
6、我说话很慢，停顿时小智老是抢话

部署相关教程 Copy Chapter

1、如何自动拉取本项目最新代码自动编译和启动
2、如何部署MQTT网关开启MQTT+UDP协议
3、如何与Nginx集成

拓展相关教程 Copy Chapter

1、如何开启手机号码注册智控台
2、如何集成HomeAssistant实现智能家居控制
3、如何开启视觉模型实现拍照识物
4、如何部署MCP接入点
5、如何接入MCP接入点
6、如何开启声纹识别
7、新闻插件源配置指南
8、天气插件使用指南

语音克隆、本地语音部署相关教程 Copy Chapter

1、如何在智控台克隆音色
2、如何部署集成index-tts本地语音
3、如何部署集成fish-speech本地语音
4、如何部署集成PaddleSpeech本地语音

性能测试教程 Copy Chapter

1、各组件速度测试指南
2、定期公开测试结果

File: docs/docker-build.md Copy Chapter

本地编译docker镜像方法

现在本项目已经使用github的自动编译docker镜像功能，如果您拉取的是项目发行的镜像，您没有自己编译镜像的需求，那就忽略本文档。

如果您修改了源码，然后想采用docker的方式部署运行，可以参照以下步骤操作：

1、环境准备 Copy Chapter

安装docker：

sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

2、编译镜像 Copy Chapter

当你修改好代码后，需要编译新的镜像时，需要按照以下步骤操作：

准备好你的你的用户名和新的版本号。

• 这个你的用户名是你在docker hub注册的用户名，例如xiaozhi。当然，如果你不需要推送到docker hub，你可以自由定义。
• 这个新的版本号是你编译的镜像版本，例如1.2.3，你可以根据需要自定义或者使用日期格式（例如20260609）主要是方便和现在运行的版本号做区分，同时也方便下次回忆你是什么时候构建的，不要和现在你本机运行的版本号相同。

进入xiaozhi-esp32-server项目根目录，编译 server 和 web 两个镜像：

cd 项目根目录

# 编译server镜像
docker build -f Dockerfile-server -t 你的用户名/xiaozhi-esp32-server:新的版本号 .

# 编译web镜像
docker build -f Dockerfile-web -t 你的用户名/xiaozhi-esp32-server-web:新的版本号 .

3、修改docker-compose配置 Copy Chapter

cd main/xiaozhi-server

编辑 docker-compose_all.yml 文件，将镜像版本替换为你刚才编译的版本：

services:
  xiaozhi-esp32-server:
    image: 你的用户名/xiaozhi-esp32-server:新的版本号   # 修改为你的镜像地址
    ...

  xiaozhi-esp32-server-web:
    image: 你的用户名/xiaozhi-esp32-server-web:新的版本号   #修改为你的镜像地址
    ...

4、重启服务 Copy Chapter

# 停止旧容器
docker compose -f docker-compose_all.yml down

# 启动新容器
docker compose -f docker-compose_all.yml up -d

5、验证 Copy Chapter

查看日志确认服务启动正常：

# 查看server日志
docker logs -f -n 50 xiaozhi-esp32-server

# 查看web日志
docker logs -f -n 50 xiaozhi-esp32-server-web

File: docs/FAQ.md Copy Chapter

常见问题 ❓

1、为什么我说的话，小智识别出来很多韩文、日文、英文？🇰🇷 Copy Section

建议：检查一下models/SenseVoiceSmall是否已经有model.pt
文件，如果没有就要下载，查看这里下载语音识别模型文件

2、为什么会出现"TTS 任务出错 文件不存在"？📁 Copy Section

建议：检查一下是否正确使用conda 安装了libopus和ffmpeg库。

如果没有安装，就安装

conda install conda-forge::libopus
conda install conda-forge::ffmpeg

3、TTS 经常失败，经常超时 ⏰ Copy Section

建议：如果 EdgeTTS 经常失败，请先检查是否使用了代理（梯子）。如果使用了，请尝试关闭代理后再试；
如果用的是火山引擎的豆包 TTS，经常失败时建议使用付费版本，因为测试版本仅支持 2 个并发。

4、使用Wifi能连接自建服务器，但是4G模式却接不上 🔐 Copy Section

原因：虾哥的固件，4G模式需要使用安全连接。

解决方法：目前有两种方法可以解决。任选一种：

1、改代码。参考这个视频解决 https://www.bilibili.com/video/BV18MfTYoE85

2、使用nginx配置ssl证书。参考教程 https://icnt94i5ctj4.feishu.cn/docx/GnYOdMNJOoRCljx1ctecsj9cnRe

5、如何提高小智对话响应速度？ ⚡ Copy Section

本项目默认配置为低成本方案，建议初学者先使用默认免费模型，解决"跑得动"的问题，再优化"跑得快"。
如需提升响应速度，可尝试更换各组件。自0.5.2版本起，项目支持流式配置，相比早期版本，响应速度提升约2.5秒，显著改善用户体验。

如果您关心各组件的耗时，请查阅小智各组件性能测试报告，可按报告中的测试方法在您的环境中实际测试。

6、我说话很慢，停顿时小智老是抢话 🗣️ Copy Section

建议：在配置文件中找到如下部分，将 min_silence_duration_ms 的值调大（例如改为 1000）：

VAD:
  SileroVAD:
    threshold: 0.5
    model_dir: models/snakers4_silero-vad
    min_silence_duration_ms: 700  # 如果说话停顿较长，可将此值调大

7、部署相关教程 Copy Section

1、如何进行最简化部署
2、如何进行全模块部署
3、如何部署MQTT网关开启MQTT+UDP协议
4、如何自动拉取本项目最新代码自动编译和启动
5、如何与Nginx集成
6、修改代码后怎么编译自己的Docker镜像

8、编译固件相关教程 Copy Section

1、如何自己编译小智固件
2、如何基于虾哥编译好的固件修改OTA地址
3、单模块部署如何配置固件OTA自动升级

9、拓展相关教程 Copy Section

1、如何开启手机号码注册智控台
2、如何集成HomeAssistant实现智能家居控制
3、如何开启视觉模型实现拍照识物
4、如何部署MCP接入点
5、如何接入MCP接入点
6、MCP方法如何获取设备信息
7、如何开启声纹识别
8、新闻插件源配置指南
9、知识库ragflow集成指南
10、如何部署上下文源
11、如何集成PowerMem智能记忆
12、如何配置天气插件查询天气
13、如何开启设备呼叫插件
14、如何开启联网搜索功能

10、数字人相关教程 Copy Section

1、数字人digital-human启动方法
2、如何在N100迷你主机上部署数字人digital-human

11、语音克隆、本地语音部署相关教程 Copy Section

1、如何在智控台克隆音色
2、如何部署集成index-tts本地语音
3、如何部署集成fish-speech本地语音
4、如何部署集成PaddleSpeech本地语音

12、性能测试教程 Copy Section

1、各组件速度测试指南
2、定期公开测试结果

13、更多问题，可联系我们反馈 💬 Copy Section

可以在issues提交您的问题。

File: docs/firmware-build.md Copy Chapter

esp32固件编译

第1步 准备你的ota地址 Copy Chapter

如果你，使用的是本项目0.3.12版本，不管是简单Server部署还是全模块部署，都会有ota地址。

由于简单Server部署和全模块部署的OTA地址设置方式不一样，请你选择下面的具体方式：

如果你用的是简单Server部署 Copy Section

此刻，请你用浏览器打开你的ota地址，例如我的ota地址

http://192.168.1.25:8003/xiaozhi/ota/

如果显示“OTA接口运行正常，向设备发送的websocket地址是：ws://xxx:8000/xiaozhi/v1/

你可以启动digital-human模块后打开index.html测试一下，是否能连上ota页面输出的websocket地址。

如果访问不到，你需要到配置文件.config.yaml里修改server.websocket的地址，重启后再重新测试，直到index.html能正常访问。

成功后，请往下进行第2步

如果你用的是全模块部署 Copy Section

此刻，请你用浏览器打开你的ota地址，例如我的ota地址

http://192.168.1.25:8002/xiaozhi/ota/

如果显示“OTA接口运行正常，websocket集群数量：X”。那就往下进行2步。

如果显示“OTA接口运行不正常”，大概是你还没在智控台配置Websocket地址。那就：

• 1、使用超级管理员登录智控台

• 2、顶部菜单点击参数管理

• 3、在列表中找到server.websocket项目，输入你的Websocket地址。例如我的就是

ws://192.168.1.25:8000/xiaozhi/v1/

配置完后，再使用浏览器刷新你的ota接口地址，看看是不是正常了。如果还不正常就，就再次确认一下Websocket是否正常启动，是否配置了Websocket地址。

第2步 配置环境 Copy Chapter

先按照这个教程配置项目环境《Windows搭建 ESP IDF 5.3.2开发环境以及编译小智》

第3步 打开配置文件 Copy Chapter

配置好编译环境后，下载虾哥iaozhi-esp32项目源码，

从这里下载虾哥xiaozhi-esp32项目源码。

下载后，打开xiaozhi-esp32/main/Kconfig.projbuild文件。

第4步 修改OTA地址 Copy Chapter

找到OTA_URL的default的内容，把https://api.tenclass.net/xiaozhi/ota/
改成你自己的地址，例如，我的接口地址是http://192.168.1.25:8002/xiaozhi/ota/，就把内容改成这个。

修改前：

config OTA_URL
    string "Default OTA URL"
    default "https://api.tenclass.net/xiaozhi/ota/"
    help
        The application will access this URL to check for new firmwares and server address.

修改后：

config OTA_URL
    string "Default OTA URL"
    default "http://192.168.1.25:8002/xiaozhi/ota/"
    help
        The application will access this URL to check for new firmwares and server address.

第4步 设置编译参数 Copy Chapter

设置编译参数

# 终端命令行进入xiaozhi-esp32的根目录
cd xiaozhi-esp32
# 例如我使用的板子是esp32s3，所以设置编译目标为esp32s3，如果你的板子是其他型号，请替换成对应的型号
idf.py set-target esp32s3
# 进入菜单配置
idf.py menuconfig

进入菜单配置后，再进入Xiaozhi Assistant，将BOARD_TYPE设置你板子的具体型号
保存退出，回到终端命令行。

第5步 编译固件 Copy Chapter

idf.py build

第6步 打包bin固件 Copy Chapter

cd scripts
python release.py

上面的打包命令执行完成后，会在项目根目录下的build目录下生成固件文件merged-binary.bin。
这个merged-binary.bin就是要烧录到硬件上的固件文件。

注意：如果执行到第二命令后，报了“zip”相关的错误，请忽略这个错误，只要build目录下生成固件文件merged-binary.bin
，对你没有太大影响，请继续。

第7步 烧录固件 Copy Chapter

将esp32设备连接电脑，使用chrome浏览器，打开以下网址

https://espressif.github.io/esp-launchpad/

打开这个教程，Flash工具/Web端烧录固件（无IDF开发环境）。
翻到：方式二：ESP-Launchpad 浏览器WEB端烧录，从3. 烧录固件/下载到开发板开始，按照教程操作。

烧录成功且联网成功后，通过唤醒词唤醒小智，留意server端输出的控制台信息。

常见问题 Copy Chapter

以下是一些常见问题，供参考：

1、为什么我说的话，小智识别出来很多韩文、日文、英文

2、为什么会出现“TTS 任务出错 文件不存在”？

3、TTS 经常失败，经常超时

4、使用Wifi能连接自建服务器，但是4G模式却接不上

5、如何提高小智对话响应速度？

6、我说话很慢，停顿时小智老是抢话

7、我想通过小智控制电灯、空调、远程开关机等操作

File: docs/firmware-setting.md Copy Chapter

基于虾哥编译好的固件配置自定义服务器

第1步 确认版本 Copy Chapter

烧录虾哥已经编译好的1.6.1版本以上固件

第2步 准备你的ota地址 Copy Chapter

如果你按照教程使用的是全模块部署，就应该会有ota地址。

此刻，请你用浏览器打开你的ota地址，例如我的ota地址

https://2662r3426b.vicp.fun/xiaozhi/ota/

如果显示“OTA接口运行正常，websocket集群数量：X”。那就往下。

如果显示“OTA接口运行不正常”，大概是你还没在智控台配置Websocket地址。那就：

• 1、使用超级管理员登录智控台

• 2、顶部菜单点击参数管理

• 3、在列表中找到server.websocket项目，输入你的Websocket地址。例如我的就是

wss://2662r3426b.vicp.fun/xiaozhi/v1/

配置完后，再使用浏览器刷新你的ota接口地址，看看是不是正常了。如果还不正常就，就再次确认一下Websocket是否正常启动，是否配置了Websocket地址。

第3步 进入配网模式 Copy Chapter

进入机器的配网模式，在页面顶部，点击“高级选项”，在里面输入你服务器的ota地址，点击保存。重启设备

第4步 唤醒小智，查看日志输出 Copy Chapter

唤醒小智，看看日志是不是正常输出。

常见问题 Copy Chapter

以下是一些常见问题，供参考：

1、为什么我说的话，小智识别出来很多韩文、日文、英文

2、为什么会出现“TTS 任务出错 文件不存在”？

3、TTS 经常失败，经常超时

4、使用Wifi能连接自建服务器，但是4G模式却接不上

5、如何提高小智对话响应速度？

6、我说话很慢，停顿时小智老是抢话

7、我想通过小智控制电灯、空调、远程开关机等操作

File: docs/fish-speech-integration.md Copy Chapter

登录AutoDL，租赁镜像
选择镜像:

PyTorch / 2.1.0 / 3.10(ubuntu22.04) / cuda 12.1

机器开机后，设置学术加速

source /etc/network_turbo

进入工作目录

cd autodl-tmp/

拉取项目

git clone https://gitclone.com/github.com/fishaudio/fish-speech.git ; cd fish-speech

安装依赖

pip install -e.

如果报错，安装portaudio

apt-get install portaudio19-dev -y

安装后执行

pip install torch==2.3.1 torchvision==0.18.1 torchaudio==2.3.1 --index-url https://download.pytorch.org/whl/cu121

下载模型

cd tools
python download_models.py

下载完模型后运行接口

python -m tools.api_server --listen 0.0.0.0:6006

然后用浏览器去到aotodl实例页面

https://autodl.com/console/instance/list

如下图点击你刚才机器的自定义服务按钮，开启端口转发服务

端口转发服务设置完成后，你本地电脑打开网址http://localhost:6006/，就可以访问fish-speech的接口了

如果你是单模块部署，核心配置如下

selected_module:
  TTS: FishSpeech
TTS:
  FishSpeech:
    reference_audio: ["config/assets/wakeup_words.wav",]
    reference_text: ["哈啰啊，我是小智啦，声音好听的台湾女孩一枚，超开心认识你耶，最近在忙啥，别忘了给我来点有趣的料哦，我超爱听八卦的啦",]
    api_key: "123"
    api_url: "http://127.0.0.1:6006/v1/tts"

然后重启服务