Голосовой помощник Xiaozhi на SF32¶

Что такое Xiaozhi?¶

Xiaozhi — это чат-бот с голосовым управлением на основе MCP с открытым исходным кодом, получивший широкую известность благодаря реализации для ESP32 в 2025 году. Он объединяет устройство голосового взаимодействия с облачными сервисами больших языковых моделей и расширениями MCP на устройстве или в облаке. Поэтому проект служит практической отправной точкой для создания аппаратуры разговорного ИИ, а не только текстового чат-приложения.

Почему реализация на SF32?¶

78/xiaozhi-sf32 — реализация для SF32 с намеренно изменённой схемой подключения. В исходном проекте для ESP32 поддерживаются Wi-Fi и другие варианты прямого доступа к сети, а версия для SF32 использует классический Bluetooth PAN, чтобы выходить в Интернет через сопряжённый телефон. Таким образом, подключение к внешней сети обеспечивает телефон, что в конструкции с привязкой к телефону может заметно снизить энергопотребление сетевых функций самого устройства. Фактическая экономия зависит от телефона, радиосреды, доли времени, приходящейся на диалоги, а также политики управления питанием. Такой подход особенно подходит для персональных портативных устройств с питанием от аккумулятора: кулонов, значков, компактных ассистентов и небольших носимых устройств.

Это особенно полезный пример продукта, поскольку он объединяет задачи, которые часто рассматривают по отдельности: дисплей и аудиотракт, сетевое подключение через телефон, облачный голосовой сервис, активацию устройства пользователем, органы управления устройством и обновление в полевых условиях.

Результат, область применения и условия начала¶

На этой странице описан полный инженерный маршрут превращения этого примера в основу продукта. Здесь не утверждается, что Xiaozhi — это локальная LLM, работающая без сети, что все функции исходного проекта готовы к производству или что поддерживаемая отладочная плата равнозначна сертифицированному готовому изделию. Устройство получает доступ в Интернет через Bluetooth PAN сопряжённого телефона и использует для диалога облачные сервисы Xiaozhi. До принятия решения о продукте проверьте условия сервиса, владельца учётной записи, требования к конфиденциальности и безопасности, стоимость, доступность и пригодность для целевых регионов.

Результат: воспроизводимо работающий голосовой ассистент с дисплеем, который настраивается через телефон, ведёт диалог с использованием облака, управляет одной безопасной функцией устройства, восстанавливается после потери PAN-соединения и позволяет собрать данные для решения о разработке собственной аппаратуры.

Для кого: инженеры по прошивке, аппаратуре и продукту, которые уже умеют собирать и прошивать базовую конфигурацию SF32 и готовы работать с C/C++, схемами платы, настройкой Bluetooth и интеграцией облачных сервисов.

Аппаратные и программные спецификации¶

В перечне ниже задана конкретная конфигурация для сборки из исходного кода: SF32LB52-DevKit-Nano-R16N16 V1.0.0 с внешним дисплеем и аудиосхемой, описанными SiFli. Это не универсальный перечень компонентов (BOM) для всех поддерживаемых плат Xiaozhi. Если выбрана DevKit-ULP, DevKit-LCD или Xiaotangyuan, замените весь перечень на документированную конфигурацию этой платы и зафиксируйте точные компоненты поставщика и ревизию платы.

Аппаратная спецификация¶

Приведённые выше ссылки на сторонние компоненты ведут на торговые площадки и опубликованы в официальном руководстве SiFli Nano; это не гарантированные постоянные номера деталей производителя. Сохраните снимки экрана или записи заказов для проверенных компонентов, а до проектирования изделия замените каждую такую зависимость на номер детали поставщика, прошедшей квалификацию, и паспорт компонента.

Программная спецификация¶

Выбор поддерживаемой базовой конфигурации¶

В документации SiFli по быстрому запуску Xiaozhi перечислены четыре платы с готовой прошивкой: SF32LB52-DevKit-ULP (Huangshan), SF32LB52-DevKit-LCD, SF32LB52-DevKit-Nano и плата расширения Xiaotangyuan. В руководстве по сборке из исходников сейчас указаны DevKit-ULP, DevKit-LCD и DevKit-Nano. Если проекту нужна адаптация исходного кода, выбирайте плату из списка для сборки из исходников: наличие готового образа само по себе не означает, что для платы документирована сборка из исходников.

Этапы проекта¶

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

Архитектура системы и зависимости¶

flowchart LR
    U["Пользователь: ключевое слово или кнопка диалога"] --> D["Устройство SF32LB52\nмикрофон, интерфейс, локальное управление"]
    D --> E["Аудиотракт\nOPUS / AEC / VAD при включении"]
    D <-->|"Classic Bluetooth PAN\nBNEP + IP"| P["Сопряжённый телефон\nраздача Интернета по Bluetooth"]
    P <-->|"WebSocket; отдельные HTTP API"| S["Облачные сервисы Xiaozhi\nпотоковые ASR / LLM / TTS"]
    S --> P --> D
    D --> O["Динамик, дисплей\nи локальные действия MCP"]

В официальном руководстве по архитектуре сетевым каналом указан Bluetooth PAN поверх Classic Bluetooth; на устройстве используется облегчённый IP-стек. Основным каналом обмена данными в реальном времени служит WebSocket, а HTTP используется для отдельных вызовов API. В обзоре SiFli среди реализованных функций перечислены пробуждение по ключевому слову (KWS), непрерывный диалог, AEC/VAD, динамические выражения, векторные шрифты и локальный MCP. В других официальных материалах также описаны экранный интерфейс, управление питанием и аккумулятором, облачные расширения MCP и OTA через PAN; конкретную поддержку следует проверять для выбранной платы и версии прошивки.

В этой схеме есть четыре области отказа, которые нужно диагностировать независимо: локальная аппаратура и аудиотракт; сопряжение Bluetooth и соединение PAN; доступ к Интернету и облачному сервису; конфигурация приложения и сервиса. Успешное сопряжение по BLE само по себе не подтверждает, что плата получила доступ в Интернет или что голосовой сервис активирован.

Этап 1 — Зафиксируйте исходную эталонную конфигурацию¶

1. Соберите аппаратную конфигурацию по официальной инструкции для выбранной платы. Для DevKit-LCD это включает описанное подключение AMOLED-дисплея и FPC, динамика к SPK, использование KEY1 для пробуждения/диалога и длительное нажатие KEY2 для выключения.
2. Загрузите поддерживаемую готовую прошивку по официальной инструкции Xiaozhi. В руководстве быстрого запуска рекомендуется графическая утилита; на момент публикации инструкции для версии прошивки 1.4.0 и новее загрузка из терминала не поддерживалась.
3. На телефоне до сопряжения включите параметр Bluetooth Internet sharing («раздача Интернета по Bluetooth»). Выполните сопряжение с устройством sifli-pan, затем проверьте по интерфейсу платы и статусу телефона, что установлено именно PAN-соединение, а не только сопряжение Bluetooth. В официальном руководстве отмечено: если на iOS устройство sifli-pan не отображается, может потребоваться перезапуск телефона.
4. Выполните официальную процедуру активации в консоли Xiaozhi на xiaozhi.me: создайте или настройте агента и добавьте код устройства, отображаемый платой.
5. Проведите диалог с помощью кнопки платы или настроенного механизма пробуждения. Запишите в карточку проекта версию прошивки, модель платы, модель и ОС телефона, идентификаторы учётной записи и агента.

Критерий выхода из контрольной точки 1: после холодного запуска устройство устанавливает PAN-соединение, отображает статус активации, принимает запрос на диалог, воспроизводит ответ и показывает ожидаемое состояние интерфейса.

Этап 2 — Проверьте восстановление и критичные для продукта функции¶

Проведите эти тесты до любых изменений исходного кода. Они превращают демонстрацию в надёжную базовую конфигурацию:

В официальном руководстве предупреждают, что заданная для конкретной платы кривая в battery_table.c может быть неточной для другого аккумулятора. Для аккумулятора изделия запросите у поставщика данные о заряде и разряде или измерьте их самостоятельно, обновите charging_curve_table и discharge_curve_table, пересоберите прошивку и повторите аккумуляторные тесты.

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

Этап 3 — Подготовьте воспроизводимую исходную конфигурацию¶

В репозитории SiFli-SDK подключён как подмодуль. Клонируйте репозиторий рекурсивно и зафиксируйте коммит Xiaozhi и коммит подмодуля SDK:

git clone --recursive https://github.com/78/xiaozhi-sf32.git
cd xiaozhi-sf32
git checkout 1d3ef641ace47fae68227e9173647fd5db01f6f5
git submodule update --init --recursive
cd sdk
# Windows: .\install.ps1, then .\export.ps1
# macOS/Linux: ./install.sh, then . ./export.sh

Для официального примера сборки DevKit-ULP с помощью скриптов перейдите в app/project и используйте документированный путь к внешним описаниям плат:

scons --board=sf32lb52-lchspi-ulp --board_search_path="../boards" -j8

Точную цель сборки и скрипт загрузки ищите на официальной странице выбранной платы. Не переносите имя платы ULP или путь к собранному файлу на другую плату. В протоколе воспроизводимой сборки укажите ОС хост-компьютера, результат установки инструментов, экспортированную среду, аргумент платы, ревизии исходного проекта и SDK, журнал сборки, загруженный образ и последовательный журнал.

Критерий выхода из контрольной точки 3: чистая копия репозитория на втором компьютере (или после удаления каталога сборки) создаёт образ, проходящий все проверки этапа 2.

Этап 4 — Вносите изменения целенаправленно¶

Вносите по одному изменению, сохраняя прошивку проверенной базовой конфигурации. В официальных материалах по адаптации описаны имя Bluetooth-устройства, статическая и анимированная графика, шрифты, DFU через PAN и MCP.

В примере локального MCP в официальном руководстве используется McpServer::AddCommonTools() из app/src/mcp/mcp_server.cc. Запрос действия от LLM следует считать недоверенным: проверяйте допустимый диапазон и состояние в функции обратного вызова, задавайте безопасные значения выходов по умолчанию и не предоставляйте необратимые, опасные или критичные для безопасности функции без предусмотренной для изделия авторизации.

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

Критерий выхода из контрольной точки 4: зафиксированы выбранное изменение, способ отката или восстановления и результаты всех применимых регрессионных тестов; исходный цикл диалога и ограничения безопасности для действий устройства по-прежнему соблюдаются.

Этап 5 — Оцените готовность к продукту¶

Не переходите к разработке собственной аппаратуры, пока команда не сможет ответить на следующие вопросы:

• Какие версии телефона и ОС поддерживают выбранную процедуру подключения PAN и что делать, если они её не поддерживают?
• Каковы параметры подключения: облачная конечная точка, учётная запись, агент, конечная точка MCP и учётные данные? Кто отвечает за каждый из этих компонентов и за ротацию учётных данных?
• Какие аудиоданные, данные устройства и пользовательские данные передаются за его пределы? Как запрашивается согласие и какие действуют требования к хранению и регионам обработки?
• Каковы измеренные токи во время активного диалога, ожидания с подключением, сна, зарядки и пробуждения при использовании целевого аккумулятора и корпуса?
• Как устройство восстановится после сбоя обновления, потери телефона, недоступности облака, повреждения ресурса или неверной конфигурации?
• Какие части кода исходного проекта, сервиса, поведения модели и OTA-инфраструктуры контролирует команда продукта, а какие зависят от внешних поставщиков?

Критерий выхода из контрольной точки 5: ответы, ответственные лица и остаточные риски зафиксированы и приняты командой продукта; для каждого нерешённого вопроса определены мера снижения риска, явный перенос на более поздний этап или решение остановиться.

Передача материалов для проектирования изделия¶

Передайте выбранный компонент SF32, архитектуру питания, решения для дисплея и аудио, стратегию RF, план хранения данных и разделов, производственные тесты и допущения по восстановлению в раздел «Разработка для серийного производства». Используйте путь интеграции SF32LB52, чтобы выбрать подходящие микросхему, модуль, плату, руководство и контрольный список.

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

Основные источники¶

• Репозиторий 78/xiaozhi-esp32
• Репозиторий 78/xiaozhi-sf32
• SiFli Wiki: описание AI Xiaozhi (на китайском)
• Быстрый запуск Xiaozhi от SiFli
• Сборка Xiaozhi из исходников от SiFli
• Архитектура Xiaozhi от SiFli
• Адаптация Xiaozhi от SiFli
• Руководство SiFli по DFU_PAN для Xiaozhi
• Руководство SiFli по MCP для Xiaozhi

Последнее обновление: 2026-10-21