Assistant vocal Xiaozhi sur SF32¶

Qu'est-ce que Xiaozhi ?¶

Xiaozhi est un chatbot vocal open source fondé sur MCP, largement connu depuis son implémentation ESP32 en 2025. Il associe un appareil d'interaction vocale à des services cloud de grands modèles et à des extensions MCP côté appareil ou côté cloud. C'est donc un point de départ concret pour du matériel d'IA conversationnelle, et pas seulement une application de chat textuel.

Pourquoi l'implémentation SF32 ?¶

78/xiaozhi-sf32 est l'implémentation SF32, mais elle utilise volontairement un autre schéma de connectivité. Alors que le projet ESP32 d'origine prend en charge le Wi-Fi et d'autres connexions réseau directes, la version SF32 accède à Internet via le Bluetooth PAN classique, fourni par un téléphone appairé. Le téléphone prend ainsi en charge la connexion à Internet, ce qui peut réduire sensiblement la consommation électrique liée au réseau côté appareil dans une conception dépendante du téléphone. L'économie réelle dépend toutefois du téléphone, des conditions radio, du rapport cyclique des dialogues et de la politique d'alimentation. Cette approche convient particulièrement aux appareils personnels portables sur batterie, comme les pendentifs, badges, assistants compacts et petits appareils connectés portés sur soi.

Cette référence produit est particulièrement utile, car elle réunit des aspects souvent traités séparément : matériel d'affichage et audio, réseau fourni par le téléphone, service vocal cloud, parcours d'activation utilisateur, commandes de l'appareil et capacité de mise à jour sur le terrain.

Résultat, portée et critères d'entrée¶

Cette page décrit un parcours d'ingénierie complet pour faire évoluer cette référence vers un produit. Elle n'affirme pas que Xiaozhi est un LLM hors ligne exécuté sur l'appareil, que toutes les fonctions amont sont qualifiées pour la production, ni qu'une carte de développement prise en charge équivaut à un produit fini certifié. L'appareil utilise Bluetooth PAN pour accéder à Internet par l'intermédiaire d'un téléphone appairé et s'appuie sur les services cloud Xiaozhi pour le dialogue. Avant tout engagement produit, vérifiez les conditions du service, la propriété du compte, la confidentialité, la sécurité, les coûts, la disponibilité et l'adéquation régionale.

Résultat : obtenir un assistant vocal avec affichage reproductible, configurable via un téléphone, capable de mener un dialogue appuyé par le cloud, de contrôler une fonction sûre de l'appareil, de récupérer après la perte de la connexion PAN et de produire les preuves nécessaires à une décision de matériel personnalisé.

Public visé : ingénieurs firmware, matériel et produit déjà capables de compiler et flasher une base SF32, et prêts à travailler avec C/C++, les schémas de carte, la configuration Bluetooth et l'intégration de services cloud.

Spécifications matérielles et logicielles¶

Le manifeste ci-dessous définit une référence concrète de compilation depuis les sources : SF32LB52-DevKit-Nano-R16N16 V1.0.0, avec l'écran externe et le circuit audio documentés par SiFli. Il ne constitue pas une nomenclature universelle pour toutes les cartes Xiaozhi prises en charge. Si vous choisissez DevKit-ULP, DevKit-LCD ou Xiaotangyuan, remplacez l'ensemble de ce manifeste matériel par l'assemblage documenté de cette carte et conservez les références exactes des fournisseurs et la révision de la carte.

Spécification matérielle¶

Les URL de composants tiers ci-dessus pointent vers des places de marché citées par le guide officiel SiFli Nano ; elles ne garantissent pas des références fabricant pérennes. Conservez captures d'écran ou justificatifs d'achat des pièces évaluées, puis remplacez chaque dépendance à une place de marché par une référence fournisseur qualifiée et sa fiche technique avant la conception du produit.

Spécification logicielle¶

Choisir une configuration de référence prise en charge¶

La documentation de démarrage rapide SiFli pour Xiaozhi répertorie quatre cibles avec firmware précompilé : SF32LB52-DevKit-ULP (Huangshan), SF32LB52-DevKit-LCD, SF32LB52-DevKit-Nano et la carte d'extension Xiaotangyuan. La documentation de compilation depuis les sources répertorie actuellement DevKit-ULP, DevKit-LCD et DevKit-Nano. Si la personnalisation des sources est une exigence du projet, choisissez une carte figurant dans cette dernière liste ; la présence d'une image précompilée ne garantit pas l'existence d'une cible de compilation documentée.

Étapes du projet¶

Considérez les étapes comme des points de décision, et non comme une liste de fonctionnalités. Chacune produit un élément vérifiable qui permet d'examiner et de reproduire la décision suivante.

Architecture système et dépendances¶

flowchart LR
    U["Utilisateur : mot d'activation ou touche de dialogue"] --> D["Appareil SF32LB52\nmicrophone, interface, commandes locales"]
    D --> E["Chaîne audio\nOPUS / AEC / VAD si activés"]
    D <-->|"Bluetooth classique PAN\nBNEP + IP"| P["Téléphone appairé\nPartage Internet par Bluetooth"]
    P <-->|"WebSocket ; certaines API HTTP"| S["Services cloud Xiaozhi\nASR / LLM / TTS en streaming"]
    S --> P --> D
    D --> O["Haut-parleur, écran\net actions MCP côté appareil"]

Le guide d'architecture officiel décrit le Bluetooth PAN sur Bluetooth classique comme chemin réseau, avec une pile IP légère sur l'appareil. WebSocket est le principal canal applicatif temps réel ; HTTP sert à certaines interactions avec les API. La présentation de SiFli cite parmi les fonctions implémentées le réveil par mot-clé (KWS), le dialogue continu, l'AEC/VAD, les expressions dynamiques, les polices vectorielles et le MCP local. D'autres documents officiels décrivent aussi l'interface à l'écran, la gestion de la batterie et de l'alimentation, les extensions MCP côté cloud et la mise à jour OTA via PAN ; vérifiez la prise en charge concrète avec la carte et le firmware choisis.

Ce flux comporte quatre domaines de défaillance à diagnostiquer séparément : matériel et audio locaux, appairage Bluetooth et PAN, accès à Internet et au service cloud, configuration de l'application et du service. Un appairage BLE réussi ne prouve ni que la carte accède à Internet ni que le service vocal est activé.

Étape 1 — Établir la référence intacte¶

1. Effectuez le montage matériel propre à la carte selon la procédure officielle. Pour le DevKit-LCD, cela comprend l'ensemble AMOLED/FPC spécifié, un haut-parleur connecté à SPK, KEY1 pour le réveil et le dialogue, ainsi qu'un appui long sur KEY2 pour éteindre l'appareil.
2. Flashez le firmware précompilé pris en charge en suivant la procédure officielle Xiaozhi. Le guide de démarrage rapide recommande l'outil graphique de flashage ; à la date de publication du guide, il précise que le flashage depuis le terminal n'est pas pris en charge pour les firmwares à partir de la version 1.4.0.
3. Sur le téléphone, activez le partage Internet Bluetooth avant l'appairage. Appairez-le avec sifli-pan, puis vérifiez dans l'interface de la carte et l'état de partage du téléphone que PAN est bien actif, et qu'il ne s'agit pas d'un simple appairage Bluetooth. Pour iOS, le guide officiel indique qu'un redémarrage du téléphone peut être nécessaire si sifli-pan n'apparaît pas.
4. Suivez la procédure d'activation officielle dans la console Xiaozhi sur xiaozhi.me : créez et configurez un agent, puis ajoutez le code d'appareil affiché par la carte.
5. Lancez un dialogue à l'aide de la touche prévue ou du mécanisme d'activation configuré. Consignez dans le dossier projet la version du firmware, la carte, le modèle et le système du téléphone, ainsi que les identifiants du compte et de l'agent.

Critère de sortie du point de contrôle 1 : après un démarrage à froid, l'appareil établit PAN, indique qu'il est activé, accepte une requête de dialogue, restitue une réponse et affiche l'état attendu de l'interface.

Étape 2 — Prouver la récupération et le comportement critique du produit¶

Effectuez ces essais avant toute modification des sources. Ils transforment la démonstration en une base fiable :

Le guide officiel avertit que la courbe battery_table.c fournie pour une carte peut être inexacte avec une autre batterie. Pour la batterie du produit, obtenez les données de charge et de décharge du fournisseur ou mesurez-les. Mettez à jour charging_curve_table et discharge_curve_table, recompilez, puis répétez les essais de batterie.

Critère de sortie du point de contrôle 2 : chaque essai a un résultat consigné, les défaillances sont attribuables à leur domaine respectif et chaque procédure de reprise documentée fonctionne sans nouveau flashage ni correction manuelle de l'état.

Étape 3 — Établir une base de code reproductible¶

Le dépôt intègre SiFli-SDK sous forme de sous-module. Clonez-le récursivement et consignez le commit Xiaozhi ainsi que celui du sous-module 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

Pour l'exemple officiel de compilation par script du DevKit-ULP, lancez la compilation depuis app/project en utilisant le chemin documenté vers les cartes externes :

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

Consultez la page de compilation officielle propre à la carte pour connaître la cible exacte et le script de flashage ; ne réutilisez ni le nom de cible ULP ni le chemin de l'artefact généré pour une autre carte. Un dossier de compilation reproductible doit contenir le système d'exploitation hôte, le résultat de l'installation des outils, l'environnement exporté, l'argument de carte, les révisions amont et du SDK, le journal de compilation, l'image flashée et le journal série.

Critère de sortie du point de contrôle 3 : un clone propre sur une seconde machine — ou après suppression du répertoire de compilation — produit une image qui passe tous les contrôles de l'étape 2.

Étape 4 — Adapter délibérément¶

Ne modifiez qu'un élément à la fois et conservez l'image de référence validée. La documentation officielle de personnalisation traite du nom Bluetooth, des images statiques et animées, des polices, du DFU via PAN et de MCP.

Pour MCP côté appareil, le guide officiel utilise McpServer::AddCommonTools() dans app/src/mcp/mcp_server.cc. Considérez toute action demandée par le LLM comme une requête non fiable : vérifiez les plages de valeurs et l'état dans le callback, placez les sorties dans un état sûr par défaut et n'exposez aucune commande irréversible, dangereuse ou sensible pour la sécurité sans autorisation propre au produit.

Pour l'OTA via PAN, la documentation officielle distingue trois catégories d'images déployables séparément : le code, les ressources graphiques et les polices. L'adresse et la taille des images doivent être déterminées à partir de la table de partitions. Avant d'activer l'OTA en production, définissez une politique de version, contrôlez l'accès au serveur, vérifiez l'intégrité, testez une interruption et prévoyez une procédure de reprise locale ou filaire.

Critère de sortie du point de contrôle 4 : la modification choisie, sa procédure de retour arrière ou de reprise et les résultats de non-régression applicables sont consignés. Le parcours de dialogue initial et les limites de sécurité de chaque action sur l'appareil restent validés.

Étape 5 — Revue de préparation produit¶

Ne passez pas à une conception matérielle personnalisée avant que l'équipe puisse répondre aux questions suivantes :

• Quelles versions de téléphone et de système d'exploitation prennent en charge exactement le parcours d'appairage PAN, et quelle solution de repli prévoir sinon ?
• Quels points de terminaison cloud, compte, agent, point de terminaison MCP et identifiants sont utilisés, et qui en est responsable et en assure la rotation ?
• Quelles données audio, d'appareil et d'utilisateur quittent l'appareil ? Comment le consentement est-il obtenu ? Quelles exigences s'appliquent à la conservation des données et aux régions ?
• Quels courants sont mesurés pendant un dialogue, au repos connecté, en veille, en charge et au réveil avec la batterie et le boîtier prévus ?
• Comment l'appareil récupère-t-il après une mise à jour échouée, la perte du téléphone, une panne cloud, une ressource corrompue ou une mauvaise configuration ?
• Quels éléments du code amont, du service, du comportement du modèle et de l'infrastructure OTA sont maîtrisés par votre équipe produit, et lesquels dépendent de fournisseurs externes ?

Critère de sortie du point de contrôle 5 : les réponses, les responsables désignés et les risques résiduels sont consignés et acceptés par l'équipe produit. Chaque point restant comporte une mesure d'atténuation, un report explicite ou une décision d'arrêt.

Passage à la conception du produit¶

Intégrez le composant SF32 choisi, l'architecture d'alimentation, la conception de l'écran et de l'audio, la stratégie RF, le plan de stockage et de partitions, les essais de production et les hypothèses de reprise à la conception pour la production. Suivez le parcours d'intégration SF32LB52 pour choisir le composant, le module, la carte, le guide et la liste de contrôle adaptés.

Définition de l'achèvement du projet : cette référence a rempli son rôle lorsqu'un nouveau membre de l'équipe peut reproduire la base choisie, relier chaque défaillance observée à son responsable ou à sa procédure de reprise, reconstruire l'image personnalisée et examiner les éléments nécessaires à la décision de concevoir un matériel spécifique. Elle devient alors une référence de développement produit, et non une démonstration non évaluée à transposer en production.

Sources de référence¶

• Dépôt 78/xiaozhi-esp32
• Dépôt 78/xiaozhi-sf32
• Wiki SiFli : présentation d'AI Xiaozhi (en chinois)
• Démarrage rapide officiel SiFli pour Xiaozhi
• Compilation officielle de Xiaozhi depuis les sources
• Architecture officielle SiFli de Xiaozhi
• Personnalisation officielle de Xiaozhi par SiFli
• Guide officiel SiFli DFU_PAN de Xiaozhi
• Guide officiel SiFli MCP de Xiaozhi

Dernière mise à jour: 2026-10-21