Собственный сервер: подключите устройства XiaoZhi к своему серверу

Центр документации XiaoZhi AI чат-бота | 小智AI.Dev

Само устройство XiaoZhi большую языковую модель не запускает: устройство записывает и воспроизводит звук, а диалог обрабатывает сервер. По умолчанию прошивка подключается к официальному серверу. Если вы хотите сами выбрать языковую модель, распознавание и синтез речи или решать, где хранятся данные диалогов, можно запустить собственный сервер.

Страница — только обзор. Она объясняет, как устройство и сервер связаны, какие открытые серверы предлагает сообщество, и на примере xiaozhi-esp32-server показывает, как подключить устройство. Полные руководства сторонних проектов здесь не копируются; за точными шагами обращайтесь к документации выбранного проекта.

Размещение собственного сервера — тема для опытных пользователей. Серверы сообщества — независимые сторонние проекты. Они не относятся ни к этому сайту, ни к репозиторию upstream-прошивки, а сайт не предоставляет сервер и не ручается за сторонние проекты. Прежде чем открывать сервер в интернет, прочтите раздел «Предупреждения по безопасности» в конце страницы.

1. Нужен ли вам собственный сервер

Ваша ситуация	Рекомендация
Нужен просто готовый голосовой помощник	Используйте официальный сервер по умолчанию, см. Первый запуск
Хотите использовать выбранные вами модели языка, распознавания и синтеза речи	Разверните собственный сервер
Хотите сами решать, где хранятся данные диалогов, или добавить собственное управление устройствами и базу знаний	Разверните собственный сервер
Разрабатываете или отлаживаете протокол связи прошивки	Разверните собственный сервер или реализуйте его по протоколу WebSocket

2. Как устройство находит ваш сервер

Подключившись к сети, прошивка отправляет запрос на адрес OTA. Сервер отвечает конфигурацией websocket или mqtt, которую нужно использовать для диалогов, и по ней устройство инициализирует свой протокол связи (описание полей — в разделе Первый запуск). Поэтому у сервера должны быть как минимум две части:

Конечная точка OTA: возвращает версию, сведения об активации и конфигурацию связи;
Канал диалога: WebSocket или MQTT + UDP; по нему выполняются распознавание речи, диалог с языковой моделью и синтез речи.

Заставить устройство использовать ваш адрес OTA можно двумя способами:

Вкладка «Дополнительно» страницы настройки: в режиме настройки введите адрес OTA и сохраните; пересборка не нужна;
Собрать прошивку самостоятельно: измените Default OTA URL (CONFIG_OTA_URL) в menuconfig.

С каждым запросом на адрес OTA устройство отправляет идентификаторы, такие как Device-Id (MAC-адрес) и Client-Id, поэтому вводите только тот сервер, которому доверяете.

3. Открытые серверы сообщества

Таблица составлена по разделу «связанные открытые проекты» в README upstream-прошивки; состояние репозитория и лицензия каждого пункта проверены (2026-10-23). Содержание, возможности и лицензии меняются, поэтому ориентируйтесь на актуальное состояние репозитория.

Проект	Стек	Лицензия	Кратко
xinnan-tech/xiaozhi-esp32-server	Python + Java + Vue	MIT	Поддерживает MQTT + UDP, WebSocket, конечные точки MCP, распознавание по голосовому отпечатку и базу знаний; есть минимальное и полномодульное развёртывание
joey-zhou/xiaozhi-esp32-server-java	Java (Spring Boot)	MIT	Административный бэкенд и сервис диалога работают как два процесса; стек из README зависит от MySQL, Redis и Qdrant
AnimeAIChat/xiaozhi-server-go	Go	Изменённая Apache 2.0 с дополнительными условиями	Рассчитан на личное и домашнее использование, общается по WebSocket, хранит конфигурацию в локальной SQLite; среди дополнительных условий — запрет многопользовательского (multi-tenant) использования без письменного разрешения, поэтому сначала прочтите его `LICENSE`
hackers365/xiaozhi-esp32-server-golang	Go	MIT	Полностью потоковая цепочка ASR → LLM → TTS, поддерживает WebSocket и MQTT + UDP; есть готовый комплект «в один клик» и развёртывание через Docker

О клиентах, портах для встраиваемых систем и других проектах см. Экосистему.

4. Пример: xiaozhi-esp32-server

Приведённые ниже сведения взяты из README и docs/ тега v0.9.7 этого проекта. Для более новых версий ориентируйтесь на документацию ветки main.

Режимы развёртывания

Режим	Что включает	Для чего подходит
Минимальная установка	Интеллектуальный диалог, один агент; конфигурация лежит в файле, база данных не нужна; запускается в Docker или из исходного кода	Среды с невысокой производительностью, первый запуск
Полномодульная установка	Интеллектуальный диалог, несколько пользователей и агентов, консоль управления; данные хранятся в базе данных	Полный набор возможностей

Адреса и порты по умолчанию

Конечные точки минимальной установки по умолчанию:

WebSocket: ws://<IP в локальной сети>:8000/xiaozhi/v1/
OTA: http://<IP в локальной сети>:8003/xiaozhi/ota/

Устройство должно быть способно достучаться до этого адреса, поэтому не используйте localhost и 127.0.0.1. При развёртывании в Docker адрес, выведенный в журнале запуска, не является настоящим; определите его по IP в локальной сети компьютера, на котором работает сервис.

Замечания по конфигурации

Размещайте свою конфигурацию в data/.config.yaml: он имеет приоритет над config.yaml в каталоге xiaozhi-server; сначала запустите минимальную конфигурацию, а затем заменяйте модули по одному;
Нужен как минимум адрес WebSocket, доступный устройству:

server:
  websocket: ws://<your LAN IP>:8000/xiaozhi/v1/

Для языковой модели по умолчанию нужны учётная запись на соответствующей платформе и ключ API, иначе сервис не запустится;
Модель распознавания речи по умолчанию SenseVoiceSmall велика; файл model.pt нужно скачать отдельно и поместить в models/SenseVoiceSmall/.

Подключение устройства

Откройте адрес OTA в браузере. При полномодульном развёртывании должно отображаться «OTA接口运行正常» (конечная точка OTA работает). Если этого нет, войдите в консоль как суперадминистратор, в разделе «参数管理» (управление параметрами) задайте server.websocket равным своему адресу WebSocket и обновите страницу, чтобы проверить.
Переведите устройство в режим настройки (см. Первый запуск), введите адрес OTA на вкладке «Дополнительно» страницы настройки, сохраните и перезапустите устройство.
Разбудите устройство и проверьте, появились ли в журнале сервера записи о диалоге.

Типичные ситуации

Wi-Fi работает, а 4G — нет: в FAQ проекта объясняется, что режиму 4G нужно защищённое соединение; один из вариантов — настроить SSL-сертификат в nginx, см. его FAQ.
Проблемы с развёртыванием сервера: начните с руководства по развёртыванию проекта (минимальный вариант) и руководства по полномодульному развёртыванию, затем сообщите в его Issues.
Проблемы с прошивкой и устройством: см. Часто задаваемые вопросы и Настройку сети.

5. Предупреждения по безопасности

В README xiaozhi-esp32-server в разделе «Warning» сказано:

Это программное обеспечение с открытым исходным кодом. Оно не связано коммерческими отношениями ни с одним из сторонних поставщиков API, к которым подключается (распознавание речи, языковые модели, синтез речи и т. д.), и не гарантирует качество их услуг и сохранность ваших средств. Отдавайте предпочтение поставщикам с соответствующими лицензиями на деятельность и читайте их условия и политику конфиденциальности. Программа не хранит ключи учётных записей и не участвует в денежных потоках.
Проект не завершён и не проходил оценку сетевой безопасности. Не используйте его в production. Если вы развёртываете его в публичной сети для обучения, обеспечьте необходимую защиту.

Исходя из поведения прошивки, добавим несколько общих правил:

Вводите только доверенный адрес OTA: устройство отправляет туда свои идентификаторы и переключает конфигурацию связи по его ответу.
Храните ключи API только в конфигурации сервера: не коммитьте их в публичные репозитории и не показывайте на скриншотах и в журналах.
В интернете используйте TLS: внутри локальной сети подходят ws:// и обычный HTTP; в интернете используйте wss:// и HTTPS и ограничивайте круг тех, кто может обратиться к серверу.

Связанные документы

Первый запуск: настройка, активация и привязка: как устройство обращается по адресу OTA
Протокол связи WebSocket, гибридный протокол MQTT + UDP и протокол MCP: протоколы, которые должен реализовать сервер
Экосистема: серверы, клиенты и порты
Часто задаваемые вопросы

Источники: main/ota.cc и main/Kconfig.projbuild прошивки 78/xiaozhi-esp32 v2.5.2; сторонние сведения взяты из README и документации каждого репозитория (проверено 2026-10-23).

Инструкции по настройке сети Руководство по использованию функций