12 KiB
Executable File
部署架构图
方式一：Docker只运行Server
docker镜像已支持x86架构、arm64架构的CPU，支持在国产操作系统上运行。
1. 安装docker
如果您的电脑还没安装docker，可以按照这里的教程安装：docker安装
如果你已经安装好docker，你可以1.1使用懒人脚本自动帮你下载所需的文件和配置文件，你可以使用docker1.2手动部署。
1.1 懒人脚本
你可以使用以下命令一键下载并执行部署脚本： 请确保你的环境可以正常访问 GitHub 否则无法下载脚本。
curl -L -o docker-setup.sh https://raw.githubusercontent.com/xinnan-tech/xiaozhi-esp32-server/main/docker-setup.sh
如果您的电脑是windows系统，请使用使用 Git Bash、WSL、PowerShell 或 CMD 运行以下命令：
# Git Bash 或 WSL
sh docker-setup.sh
# PowerShell 或 CMD
.\docker-setup.sh
如果您的电脑是linux 或者 macos 系统，请使用终端运行以下命令：
chmod +x docker-setup.sh
./docker-setup.sh
脚本会自动完成以下操作：
- 创建必要的目录结构
- 下载语音识别模型
- 下载配置文件
- 检查文件完整性
执行完成后，请按照提示配置 API 密钥。
当你一切顺利完成以上操作后，继续操作配置项目文件
1.2 手动部署
如果懒人脚本无法正常运行，请按本章节1.2进行手动部署。
1.2.1 创建目录
安装完后，你需要为这个项目找一个安放配置文件的目录，例如我们可以新建一个文件夹叫xiaozhi-server。
创建好目录后，你需要在xiaozhi-server下面创建data文件夹和models文件夹，models下面还要再创建SenseVoiceSmall文件夹。
最终目录结构如下所示：
xiaozhi-server
├─ data
├─ models
├─ SenseVoiceSmall
1.2.2 下载语音识别模型文件
你需要下载语音识别的模型文件，因为本项目的默认语音识别用的是本地离线语音识别方案。可通过这个方式下载 跳转到下载语音识别模型文件
下载完后，回到本教程。
1.2.3 下载配置文件
你需要下载两个配置文件：docker-compose.yaml 和 config.yaml。需要从项目仓库下载这两个文件。
1.2.3.1 下载 docker-compose.yaml
用浏览器打开这个链接。
在页面的右侧找到名称为RAW按钮，在RAW按钮的旁边，找到下载的图标，点击下载按钮，下载docker-compose.yml文件。 把文件下载到你的
xiaozhi-server中。
下载完后，回到本教程继续往下。
1.2.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. 配置项目文件
接下里，程序还不能直接运行，你需要配置一下，你到底使用的是什么模型。你可以看这个教程： 跳转到配置项目文件
配置完项目文件后，回到本教程继续往下。
3. 执行docker命令
打开命令行工具，使用终端或命令行工具 进入到你的xiaozhi-server，执行以下命令
docker-compose up -d
执行完后，再执行以下命令，查看日志信息。
docker logs -f xiaozhi-esp32-server
这时，你就要留意日志信息，可以根据这个教程，判断是否成功了。跳转到运行状态确认
5. 版本升级操作
如果后期想升级版本，可以这么操作
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.安装基础环境
本项目使用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
请注意，以上命令，不是一股脑执行就成功的，你需要一步步执行，每一步执行完后，都检查一下输出的日志，查看是否成功。
2.安装本项目依赖
你先要下载本项目源码，源码可以通过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.下载语音识别模型文件
你需要下载语音识别的模型文件，因为本项目的默认语音识别用的是本地离线语音识别方案。可通过这个方式下载 跳转到下载语音识别模型文件
下载完后，回到本教程。
4.配置项目文件
接下来，程序还不能直接运行，你需要配置一下，你到底使用的是什么模型。你可以看这个教程： 跳转到配置项目文件
5.运行项目
# 确保在xiaozhi-server目录下执行
conda activate xiaozhi-esp32-server
python app.py
这时，你就要留意日志信息，可以根据这个教程，判断是否成功了。跳转到运行状态确认
汇总
配置项目
如果你的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下的配置就行。
模型文件
本项目语音识别模型，默认使用SenseVoiceSmall模型，进行语音转文字。因为模型较大，需要独立下载，下载后把model.pt
文件放在models/SenseVoiceSmall
目录下。下面两个下载路线任选一个。
- 线路一：阿里魔塔下载SenseVoiceSmall
- 线路二：百度网盘下载SenseVoiceSmall 提取码:
qvna
运行状态确认
如果你能看到，类似以下日志,则是本项目服务启动成功的标志。
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请用谷歌浏览器打开test目录下的test_page.html
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、 基于虾哥编译好的固件配置自定义服务器了。
以下是一些常见问题，供参考：