Часто задаваемые вопросы (FAQ)

Для краткости «терминал XiaoZhi AI» ниже означает чат-робота XiaoZhi AI. За исключением вопросов о платах серии ESP32-S3-WROOM-1, большинство ответов относится к сборке на макетной плате; наборы других производителей и самодельные варианты здесь не разбираются. Ответы о прошивке сверены с upstream-проектом 78/xiaozhi-esp32 v2.5.2. Что касается панели управления (консоли), ориентируйтесь на то, что реально показывает официальная консоль.

Начало работы

Q0: Как шаг за шагом собрать робота XiaoZhi AI?

A: На макетной плате, на проводах Dupont или с пайкой собственных проводов — всего 5 шагов:

1. Купите детали и модули по списку. Подробнее: Руководство по сборке оборудования XiaoZhi AI.
2. Подключите провода: выберите схему или таблицу соединений для своей платы (44 или 42 контакта) и соедините провода по буквенным и цифровым меткам.
3. Скачайте и прошейте прошивку:
   • Файлы прошивки называются вида v2.5.2_<вариант>.zip; ориентир — GitHub Releases. Имя варианта ищите на странице Поддерживаемые платы.
   • Макетная плата с Wi-Fi: bread-compact-wifi (OLED 0,91 дюйма, 128×32). Для экрана 128×64 выберите bread-compact-wifi-128x64.
   • Макетная плата с 4G ML307 (необязательно): bread-compact-ml307 (для экрана 128×64 — bread-compact-ml307-128x64).
   • Инструменты прошивки и загрузка: Загрузка прошивки XiaoZhi AI
4. Подключите устройство к сети:
   • Платы ESP32-S3 по умолчанию поддерживают Wi-Fi. Настройте Wi-Fi там, где пользуетесь устройством, или точку доступа телефона (только 2,4 ГГц; сети с дополнительным входом не поддерживаются). См. Инструкции по настройке сети.
   • Версии с ML307R-4G достаточно вставить SIM-карту / карту передачи данных (IoT-карту).
5. Зарегистрируйте устройство: после подключения к сети устройство показывает и произносит код активации; введите его в консоли, чтобы привязать устройство. См. Первый запуск. Затем скажите «你好小智» — и можно пользоваться.
   • Адрес консоли смотрите в README upstream-проекта.

Примечания:

• Настройку Wi-Fi из шагов 3 и 4 можно сделать до подключения модулей проводами.
• Если вы купили плату стороннего производителя или готовое изделие, следуйте его инструкции. Обычно проводить провода не нужно — достаточно прошить подходящую прошивку.

Q1: Я не умею паять. Можно ли всё равно собрать чат-робота XiaoZhi AI?

A: Можно. Следуйте руководству проекта и используйте вариант на макетной плате с Wi-Fi. Покупайте модули с уже припаянными штырьками, подключайте их и прошивайте плату по документации, затем настройте Wi-Fi и зарегистрируйте устройство. Паяльник на всём пути не нужен.

Q2: Где посмотреть список деталей и где их купить?

A:

1. Список материалов и модулей — в разделе со списком деталей и схемой подключения Руководства по сборке оборудования.
2. Как покупать:
   • По отдельности: ищите по названию модуля, например «ESP32 S3 development board», для микрофона — «INMP441», для усилителя звука — «MAX98357».
   • Наборами: ищите «XiaoZhi AI ESP32» или «XiaoZhi AI ESP32S3».
   • Советы по покупке: см. Руководство по сборке оборудования.

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

Q3: Нужно ли покупать модуль ML307R-4G?

A: Модуль ML307R-4G необязателен. Он нужен в основном в таких случаях:

• Там, где вы пользуетесь устройством, нет Wi-Fi или он ограничен (например, кампусные или коммерческие сети с дополнительной авторизацией).
• Wi-Fi нет, а подключаться к точке доступа телефона неудобно, или смартфона нет.

Вывод: если есть обычный Wi-Fi или точка доступа телефона, модуль ML307R-4G покупать не нужно (кроме случая, когда вы не хотите возиться с Wi-Fi и не против платить за мобильный трафик).

Дополнительно: в списке вариантов Cat.1 4G в README upstream-проекта указаны три вида модулей — ML307, EC801E и NT26. Какие платы их поддерживают, см. Поддерживаемые платы.

Прошивка

Q4: Как прошить XiaoZhi AI и что делать при ошибке?

A: См. Загрузка прошивки XiaoZhi AI. Главное:

1. Выберите чип ESP32-S3.
2. Режим загрузки по умолчанию — UART; подключайтесь к USB-порту справа на плате (на обратной стороне надпись COM).
3. Отметьте BIN-файл для прошивки и укажите адрес 0 или 0x0.
4. Выберите COM-порт, который определился на вашем компьютере.

Примечания:

• Используйте кабель USB-C для передачи данных от телефона или из комплекта платы, а не тонкий зарядный кабель.
• В пути к BIN-файлу не должно быть китайских символов, иначе файл не загрузится и прошивка не удастся.

Q5: Что такое IDF и нужно ли настраивать среду IDF?

A:

1. Обычным пользователям устанавливать и настраивать среду IDF не нужно — только разработчикам и тем, кто учится программировать.
2. IDF — это ESP-IDF, официальная платформа разработки от Espressif, производителя чипов ESP32. Она позволяет разрабатывать приложения для ESP32 на C/C++. Для v2.5.2 нужен ESP-IDF 6.0.1 или новее, рекомендуется ветка release/v6.1.
3. Если настройка нужна:
   • В Windows: Настройка среды разработки ESP-IDF и компиляция XiaoZhi
   • Пользователям Linux стоит самостоятельно найти соответствующую документацию.

Оборудование

Q6: Почему из динамика моего терминала нет звука?

A:

1. Проверьте, правильно ли подключён динамик. Обычно красный провод — плюс, чёрный — минус.
2. Проверьте, правильно ли подключён цифровой усилитель и надёжен ли контакт. Сверьтесь с таблицей соединений.
3. Если питание идёт от USB-порта компьютера, а мощность динамика около 3 Вт, питания может не хватать. Используйте USB-зарядку 5 В 2 А или больше либо USB-порт повербанка 5 В 2,1 А.

Если соединения верны, а проблема осталась, проверьте с запасным динамиком и модулем цифрового усилителя.

Q7: Почему динамик хрипит или звук ненормальный?

A:

1. Хрип обычно означает, что вывод GAIN усилителя не подключён к земле (GND) или соединение GND нестабильно.
2. Шипящий электрический шум может быть электромагнитной помехой. Уберите терминал от сильных магнитных устройств и модулей и разделите его с источниками питания для заряда и разряда.

Q8: Как изменить громкость?

A:

1. Голосом: LLM задаёт громкость через MCP-инструмент на стороне устройства self.audio_speaker.set_volume. Просто скажите «установи громкость на …» или «сделай потише / погромче». См. Инструкцию по использованию протокола MCP.
2. Кнопками: в варианте на макетной плате bread-compact-wifi кнопки громкости заданы в config.h: IO40 — громче, IO39 — тише. Для других плат смотрите описание в каталоге платы.

Q9: Почему «你好小智» не будит терминал или нет реакции?

A:

1. Убедитесь, что слово пробуждения верное («你好小智», а не «小智你好» или что-то другое).
2. Проверьте, правильно ли подключены 6 контактов микрофона и надёжен ли контакт.
3. У микрофона INMP441 сторона со значком микрофона, буквами на шелкографии и звуковым отверстием обычно должна смотреть вверх.
4. Если соединения верны, а проблема осталась, проверьте с запасным микрофоном.
5. Вывод платы в последовательном терминале помогает найти причину.

Q10: Терминал просит настроить сеть, но точка доступа Xiaozhi-XXXX не находится.

A: Это значит, что у Wi-Fi платы ESP32-S3 проблема с сигналом. Можно попробовать:

1. Временно прижать пальцем область антенны платы или намотать на неё провод, чтобы усилить сигнал.
2. Посмотреть вывод платы в последовательном терминале, чтобы найти причину.

Q11: Как настроить Wi-Fi заново или переключиться на другую сеть?

A:

1. Заново включите или перезагрузите плату и во время запуска нажмите кнопку настройки сети: на bread-compact-wifi — один раз нажмите кнопку BOOT; для других плат смотрите описание в каталоге платы. Устройство перейдёт в режим настройки сети.
2. Если к сохранённой сети Wi-Fi не удалось подключиться за 60 секунд, устройство тоже само переходит в режим настройки.
3. У некоторых плат есть MCP-инструмент self.disp.network (повторная настройка сети).

Примечание: устройство хранит до 10 сетей Wi-Fi. Если сохранённые сети есть, оно само в режим настройки не перейдёт, поэтому для смены сети нужно перейти в режим настройки способами выше. См. Инструкции по настройке сети.

Q12: Почему не загорается экран?

A:

1. Проверьте, правильно ли подключён экран и надёжен ли контакт.
2. Качество макетных плат бывает разным; при проблемах проверьте целостность цепи мультиметром.
3. Если соединения верны, а проблема осталась, проверьте с запасным экраном.

Функции и использование

Q13: Умеет ли терминал воспроизводить музыку?

A: В исходном коде прошивки v2.5.2 функции воспроизведения музыки нет. Можно ли заказать песню, зависит от сервера, к которому вы подключены, поэтому ориентируйтесь на описание официальной консоли или собственного сервера. Чтобы играть локальную музыку, можно самостоятельно расширить аппаратный интерфейс и код либо подключить сторонний музыкальный сервис на стороне сервера.

Q14: Можно ли переключаться между большими моделями, например DeepSeek?

A: Можно, но решает сервер. На официальном сервере доступные модели и место их переключения указаны в официальной консоли (по умолчанию устройство подключается к официальному серверу, а частные пользователи после регистрации могут бесплатно пользоваться моделью Qwen в режиме реального времени). На собственном сервере модель выбирается в настройках этого сервера; см. Собственный сервер. Сама прошивка устройства не привязана к конкретной модели.

Q15: Поддерживает ли терминал подключение по Bluetooth?

A: Пока нет.

• Чип/модуль ESP32-S3 поддерживает Bluetooth BLE только в режиме периферийного устройства (к нему можно подключиться). Прошивка XiaoZhi по умолчанию этим не пользуется; BLE используется только для передачи данных Wi-Fi при включённой настройке через BluFi, см. руководство по BluFi.
• Поскольку поддерживается только режим периферийного устройства, терминал нельзя подключить к Bluetooth-наушникам или колонкам.

Q16: Можно ли поставить динамик побольше?

A: Можно. Цифровой усилитель терминала по умолчанию, MAX98357, рассчитан на динамики около 3 Вт. Для большей мощности можно взять другой усилитель с поддержкой I2S, но учтите, что питание платы ESP32 по USB обычно не превышает 5 Вт, поэтому для большей мощности нужно отдельное питание.

Q17: Поддерживает ли терминал наушники или выход 3,5 мм?

A: По умолчанию нет; нужно заменить аудиомодуль, например:

• аудиомодуль PCM5102 (стерео ЦАП, около 10 юаней);
• стереодекодер I2S UDA1334A (около 13–15 юаней).

Оба поддерживают выход 3,5 мм и не требуют изменений в коде.

Q18: Можно ли поставить экран побольше?

A: Поддерживаются такие типы экранов:

1. OLED-экраны на драйвере SSD1306:
   • По умолчанию: монохромный 4-контактный OLED 0,91 дюйма (128×32).
   • Можно заменить на 4-контактные экраны на SSD1306, например 0,96, 1,3 и 1,5 дюйма (128×64).
   • В menuconfig в пункте OLED Type выберите SSD1306 12832, SSD1306 12864 или SH1106 128*64 и пересоберите прошивку.
2. SPI-LCD-экраны:
   • Варианты на макетной плате с LCD, например bread-compact-wifi-lcd, поддерживают драйверы ST7789, ST7735, ST7796, ILI9341, GC9A01, NV3030B и другие, с вариантами по разрешению и по наличию IPS.
   • В menuconfig в пункте LCD Type выберите подходящий драйвер и разрешение, затем соберите и прошейте.

Q19: Можно ли поменять слово пробуждения?

A: Можно. В v2.5.2 есть два способа:

1. Своё слово пробуждения: в menuconfig в пункте Wake Word Implementation Type выберите Multinet model (Custom Wake Word). Введите слово пробуждения пинь-инем (через пробел), затем текст, который будет отправлен серверу после пробуждения, и при необходимости измените порог (1–99, чем меньше, тем чувствительнее, по умолчанию 20). Нужен ESP32-S3 / P4 / S31 с PSRAM. Среда сборки описана в Настройке среды разработки ESP-IDF и компиляции XiaoZhi.
2. Генератор Assets: upstream-проект предлагает веб-версию генератора пользовательских Assets, в которой можно онлайн менять слово пробуждения, шрифты, эмодзи и фон чата. См. Руководство по пользовательским Assets.

«你好小智» по умолчанию — встроенная модель слова пробуждения ESP-SR. Какие типы слова пробуждения доступны на чипах, кроме ESP32-S3, см. Поддержка чипов и спецификации хранилища.

Q20: Можно ли переименовать роль XiaoZhi AI?

A: Можно. В консоли управления XiaoZhi AI измените имя ИИ-роли в настройках роли и сохраните; изменение вступит в силу.

Примечание: имя роли — это имя агента, настроенное для большой модели. Оно не связано с офлайн-словом пробуждения «你好小智», между ними нет связи.

Q21: Можно ли сменить голос?

A: Можно. В консоли XiaoZhi AI в настройках роли переключите голос роли. Можно сначала прослушать его, затем отправить и сохранить настройки. В следующем разговоре будет использоваться новый голос.

Q22: Может ли XiaoZhi AI узнавать меня по голосу и запоминать, кто я?

A: Может. Шаги:

1. В консоли XiaoZhi AI откройте «Агенты» и найдите «Распознавание по голосу».
2. В раскрывающемся меню выберите голосовую запись (лучше подлиннее и чёткую).
3. Введите имя и описание (отношение собеседника к роли).
4. Нажмите OK, чтобы добавить говорящего.
5. Снова разбудите XiaoZhi AI и спросите в следующем разговоре — он будет знать, кто вы.

Примечание: из-за технических ограничений точность распознавания не равна 100% и снижается по мере добавления говорящих.

Q23: Можно ли использовать свой собственный голос?

A: Функция проходит внутреннее тестирование. Ей нужна поддержка сервера, а загрузка собственного голоса пока не открыта. Следите за дальнейшими объявлениями.

Q24: Поддерживает ли терминал питание от аккумулятора? Как подключить?

A: Нужен повышающий модуль на 5 В:

1. Плате ESP32-S3 нужно 5 В. Литиевый аккумулятор обычно даёт 3,8 В — этого мало, поэтому рекомендуется добавить плату заряда/разряда на 5 В.
2. Чтобы запитать плату извне: подключите VOUT/5V+ платы заряда/разряда на 5 В к выводу 5Vin платы, а GND — к выводу GND платы.
3. Можно также питать напрямую от повербанка через USB-C; рекомендуется выход 5 В 2,1 А.

Q25: Можно ли управлять моторами или сервоприводами голосом?

A: По умолчанию нет; нужно добавить модуль драйвера сервоприводов или моторов. ESP32-S3 можно расширить через MCP-инструменты на стороне устройства (см. Q26): большая модель вызывает инструмент, и тот подаёт сигналы на плату драйвера.

XiaoZhi AI адаптирован под плату ESP-SparkBot (каталог espressif/esp-sparkbot, гусеничное шасси): инструменты MCP self.chassis.* дают движение вперёд, назад, повороты и танец. Исходный код платы: espressif/esp-sparkbot

Q26: Можно ли управлять другими устройствами голосом?

A: Можно, через MCP. MCP на стороне устройства может управлять громкостью, освещением, моторами, GPIO и другим; облачный MCP добавляет управление умным домом, работу с рабочим столом ПК, поиск по знаниям, почту и другое. Протокол и способы использования см. в документации по MCP; новые инструменты на стороне устройства нужно разрабатывать самостоятельно.

Q27: Какие платы из имеющихся на рынке поддерживаются?

A: В матрице релиза v2.5.2 — 154 каталога плат и 188 вариантов прошивки, охватывающих ESP32, ESP32-C3, ESP32-C5, ESP32-C6, ESP32-S3, ESP32-S31 и ESP32-P4. Полный список — на странице Поддерживаемые платы.

При прошивке выбирайте прошивку нужного варианта. При сборке выберите плату в menuconfig в пункте Target Board. Другие платы нужно адаптировать и пересобрать; см. Руководство по пользовательским платам.

Q28: Какая большая модель используется в XiaoZhi AI? Открыт ли исходный код сервера?

A: Прошивка устройства имеет открытый исходный код (78/xiaozhi-esp32). По умолчанию она подключается к официальному серверу, а частные пользователи после регистрации могут бесплатно пользоваться моделью Qwen в режиме реального времени. На стороне сервера у сообщества есть несколько открытых реализаций, например xinnan-tech/xiaozhi-esp32-server (Python), joey-zhou/xiaozhi-esp32-server-java (Java), AnimeAIChat/xiaozhi-server-go (Golang) и hackers365/xiaozhi-esp32-server-golang (Golang). Шаги подключения и предупреждения о безопасности — в разделе Собственный сервер, полный список — в разделе Экосистема.

Q29: Можно ли подключить XiaoZhi AI к большим моделям вроде GPT?

A: Большие модели подключаются на стороне сервера; прошивка устройства напрямую с ними не соединяется. На официальном сервере доступны те модели, которые предлагает официальная консоль. Чтобы использовать другие большие модели, воспользуйтесь собственным сервером. Например, проект сообщества xiaozhi-esp32-server умеет подключаться к Alibaba Bailian, Volcano Engine, DeepSeek, Zhipu, Gemini и другим через OpenAI-совместимые интерфейсы; см. Собственный сервер.

Подробнее — в README и каталоге docs upstream-проекта 78/xiaozhi-esp32 или в GitHub Issues, где можно сообщить о проблеме.