DreamSoul研究
源码与架构 /

小智语音底座 源码研究

固定源码 · 研究快照 2026-10-27Markdown 下载 ↓
本页为正式研究文档的网页阅读版。固定 GitHub 证据保留;本机研究底稿未发布,相关链接已改为文字说明。原文中的历史发布状态对应研究当时。

一、结论与范围

小智适合作为桌面智能硬件的语音与设备工具底座候选。最有复用价值的是 ESP32 固件的音频状态机、传输协议与 MCP 工具注册,以及第三方服务端的 provider 接口和流式编排。服务端需要安全、数据治理和可复现构建改造后再评估产品接入。仓库当前仍明确要求不要用于生产环境,见 服务端生产警告。

它不是新发布的独立桌面整机。固件始于2024年,服务端始于2025年,两者在2026年10月仍持续维护。与 StackChan 共用小智协议、音频或模型接入时,这部分只计一次基础资产,不能把三个候选当成三套独立语音技术栈。小智专门解决语音链路与设备工具,桌面机构、运动安全、角色设计和整机生产不在这两个仓库的完整交付范围内。

研究访问日期为 2026-10-27(Asia/Shanghai)。首次固定版本的真实时间为 2026-10-26 18:26:56 UTC。采用默认分支 main 当时的精确 commit,保留 GitHub API 元数据和官方 codeload ZIP。最新主线与最新 release 分开记录,未把主线检查称作 release 实测。

仓库与创建时间(UTC) 本次固定主线 最近 release 与对应提交
78/xiaozhi-esp32,2024-08-31 10:08:16 c435f99a88066029ec2dbd2d758c8cc9d051565b,提交时间2026-10-25 20:37:57 v2.5.2,发布2026-10-11 20:49:36,tag → 49b4380b3faa0ceadd28a3e78aaf0f311c46c57e
xinnan-tech/xiaozhi-esp32-server,2025-02-02 14:25:16 a377d89dcd58e6e18417a57e9357c0dd23657746,提交时间2026-10-26 14:47:47 v0.9.8,发布2026-10-23 10:54:47,tag → 8f2dda09cf18f1c1ece0f906eee4cc2fabb7fb58

既有广泛调研使用固件 f443114fe7c3fa26b10d3630090119891cd1c4fd 和服务端 9bd668aebc733d77c95d8aa5fb1d25090a772509。本报告以新快照重新读代码,旧版本结论不自动继承。创建与 release 元数据位于临时目录的 firmware-meta.json、server-meta.json、firmware-release.json、server-release.json。

二、源码链路与实现边界

(一)固件启动、唤醒、音频与打断

小智语音底座 源码研究 图示
小智语音底座 源码研究 图示 · 点击查看原图
查看 Mermaid 图源
flowchart LR
  A[app_main / NVS] --> B[Application.Initialize / Board]
  B --> C[AudioService + AFE 或 Lite engine]
  B --> D[网络与 OTA 配置]
  D --> E[MQTT 或 WebSocket]
  C --> F[唤醒事件 / connecting / listening]
  F --> G[16 kHz 单声道 PCM → Opus]
  G --> E
  E --> H[服务端 VAD → ASR → LLM → TTS]
  H --> I[Opus 解码队列 → 播放队列 → 扬声器]
  E --> J[MCP JSON-RPC → 主任务执行板级工具]
检查点 代码实际实现 复用边界与直接证据
启动 app_main 初始化 NVS 后调用 Application::Initialize/Run。Initialize 取得板卡 display/codec、启动 AudioService,注册音频回调和 MCP,再异步启动网络 可沿用板级接口和事件驱动框架,换板需适配 codec、GPIO、屏幕和电源。app_main、Application::Initialize
状态转换 DeviceStateMachine 显式允许启动、联网、激活、idle、connecting、listening、speaking、升级等转换,非法转换返回 false 这是具体状态机,不是 README 能力列表。可复用状态与回调,但要为自己的掉线/关机/执行器状态补测试。IsValidTransition / TransitionTo
前处理 AFE 输入格式区分麦克风 M 与参考信号 R,AEC 初始化取决于 codec 的 input_reference(),WakeNet/自定义唤醒模型从资源模型中选择 有 AEC 代码不等于所有硬件全双工有效,必须有参考音频链路并校准音量、延迟和麦克风布局。AfeAudioEngine::Initialize
音频队列 采集、输出、Opus 编解码分任务。上行16 kHz、mono、60 ms。编码队列2项,播放队列2项,解码包20项(1.2 s),发送包40项(2.4 s) 后两项是配置容量,不是测得端到端时延。编码饱和有丢帧计数,适合接入量化监测。音频链路和队列配置、PushTaskToEncodeQueue
唤醒 idle → connecting → 打开音频通道 → listening。失败返回 idle;唤醒音频是否上送由 CONFIG_SEND_WAKE_WORD_DATA 控制 唤醒可以本地完成,后续对话仍依赖服务器。HandleWakeWordDetectedEvent / ContinueWakeWordInvoke
打断 speaking/listening 时的唤醒会发 abort,清空待发送音频并切回监听。speaking 非 realtime 模式关闭语音处理,仅保留 AFE 唤醒能力。AEC off 默认 auto,AEC on 默认 realtime 打断有唤醒词、手动与服务端 VAD 不同路径,不能一概称“全场景自然插话”。实际残留音频和误打断未测。状态驱动音频开关、AbortSpeaking / GetDefaultListeningMode、abort / listen 消息

(二)协议与设备工具

模块 实现与接口 需要保留或改造的边界
WebSocket OTA 配置提供 URL/token/version,header 携带 Authorization、Protocol-Version、Device-Id、Client-Id。hello 宣告 Opus、16 kHz、mono、60 ms 和 MCP。二进制 v1 为裸 Opus,v2/v3 加不同头 先选 v1 完成自建服务互通。服务端普通 WS 分支直接把完整二进制交 Opus 解码,没有在该分支处理 v2/v3 头;不能把固件支持3种格式推成该服务端全部兼容。SendAudio、OpenAudioChannel、_route_message / MQTT audio
协商 服务端 handleHelloMessage 将客户端 audio_params 回填 welcome,再发送 hello,随后异步初始化 MCP 默认配置的24 kHz不等于当前固件握手后必然使用24 kHz。本次隔离函数执行已验证16 kHz被回传;未编码/播放音频。handleHelloMessage
MQTT + UDP MQTT 传控制 JSON、UDP 传带16字节头和 AES-CTR 加密的音频,头含长度/时间戳/序号,接收检查短包、长度和旧序号 Python 服务端的 MQTT 路线需额外网关转接 WebSocket,网关是第三个仓库,未包含在本次两个仓库审查内。AES-CTR 本身不提供消息认证,不能据“加密”推断完整性已保证。SendAudio、UDP OnMessage、网关部署边界
设备 MCP McpServer 实现 JSON-RPC 2.0、initialize、tools/list、tools/call,协议版本2024-11-05。工具参数按声明校验类型、范围、必填值,再排入 Application 主任务 可直接复用工具注册和参数声明模式,不能替代业务授权。user_only 在工具列表中过滤,DoToolCall 按名称查找全部工具,未见同层用户授权判断。应在受信服务端与设备执行入口添加动作白名单和能力授权。ParseMessage、GetToolsList、DoToolCall
工具示例 音量、亮度、主题、拍照等通用工具,reboot、固件升级等列入 user-only。服务端 DeviceMCPExecutor 把模型工具参数发送设备,结果回入 LLM 屏幕/舵机适配可复用该模式,摄像头、重启、升级需要明确用户权限。模型看不见某工具不等于对端无法调用它。AddCommonTools、AddUserOnlyTools、DeviceMCPExecutor.execute

(三)服务端 ASR、LLM、TTS 与记忆

环节 当前默认/源码路径 本地与外部服务边界
Provider 选择 initialize_modules 按 selected_module 的名称、type 创建 VAD/ASR/LLM/TTS/Memory/Intent。默认 SileroVAD + FunASR + ChatGLMLLM + EdgeTTS + nomem 替换 provider 是明确扩展点。接入智控台后配置从 manager-api 拉取,不能只改本地 config.yaml 就声称完成替换。initialize_modules、默认模块、load_config
VAD Silero ONNX 在 CPU 本地推理,512 samples 窗口、连接独立状态、双阈值、静默结束判断。默认高0.5/低0.3、静默200 ms;manual 模式直接返回有声 200 ms 是配置,不是实测响应时间。嘈杂环境和长停顿应调参。VADProvider、VAD 默认阈值
ASR fun_local.ASRProvider 用 AutoModel 加载 models/SenseVoiceSmall,speech_to_text 调 model.generate。非流式基类在 VAD stop 后识别,要求累计 PCM 字节数大于 1920*15 属于句段触发,不是逐字实时 ASR。16 kHz/16-bit 下该门槛约0.9 s累计音频,短指令要专项测。默认模型文件不由两个主仓库 MIT 自动授权。AutoModel / speech_to_text、receive_audio
LLM 默认 ChatGLMLLM 经 openai provider 请求 open.bigmodel.cn。流式 response 与 response_with_functions 返回文本/工具调用,chat 将摘要与对话装配到模型输入,工具递归上限5 配置 API key 才能工作,默认不是本地 LLM。Ollama provider 是调用本地 HTTP OpenAI 兼容接口,不在本进程内运行权重。LLM 默认端点、OpenAI provider、Ollama provider、chat
TTS 默认 EdgeTTS 调 edge_tts.Communicate.stream(),TTS 队列经音频发送控制再给设备。GPT-SoVITS 等本地选项也是对另一个服务发 HTTP 请求 只部署此 Python 服务不能得到离线 TTS。需要自备服务、模型权重和音色授权。text_to_speak、GPT-SoVITS 服务地址与参考音色
服务端打断 AEC 开启且 VAD 有声时可立即 abort;普通 startToChat 在非 manual 模式也会停止既有播报。abort 设置 client_abort、清队列、发送 tts stop LLM 循环检查 abort,TTS 发送也检查该标记。但上游云请求是否即时停止计费、播放尾音多长,需服务实测。handleAudioMessage、startToChat、handleAbortMessage
默认无跨会话记忆 nomem 的 save 返回 None、query 返回空字符串;连接仍有 dialogue,会写日志,智控台模式还可上报聊天记录 “关闭记忆”不等于不保存聊天或不向外发数据。nomem、用户消息 INFO 日志、聊天及音频上报
本地摘要记忆 mem_local_short 将对话和历史摘要拼接,用 self.llm.response_no_stream 总结,按 device_id 保存到 data/.memory.yaml;智控台模式转 Java 总结接口。query 直接返回整份短摘要 配置注释“不会上传到外部服务器”不能作为隐私保证,默认专用总结模型仍是 ChatGLMLLM。它不是事件溯源、结构化关系库或可验证长期记忆;未见同一 YAML 的原子更新/跨设备文件锁。MemoryProvider、_initialize_memory、本地记忆配置
Mem0 使用 MemoryClient(api_key) 向 mem0 服务 add/search,按 role_id 查询 该实现是外部记忆服务路径,不能按库名推成完全本地向量库。mem0ai MemoryProvider

三、认证、存储与生产采用边界

以下属于已读代码及默认配置的风险线索,不是完整安全审计、漏洞复现或公网渗透结论。

事实与触发条件 对复用的实际影响 处理与直接证据
默认监听0.0.0.0,auth.enabled=false。启用 auth 后,allowed_devices 中的 Device-Id 可直接跳过 token 按示例暴露服务时不能假定每台设备已有可靠身份校验;MAC/Device-Id 是声明的标识 隔离实验网络,去除免 token 白名单,为每台设备建立可撤销凭据和 TLS。默认服务和认证配置、_handle_auth
实际 WS 认证使用 core/auth.py::AuthManager 的 HMAC-SHA256,绑定 client_id/device_id/时间戳,并用 constant-time digest compare 可以复用协议逻辑;另一个 core/utils/auth.py::AuthToken 的 JWT/AES 类不是此 WS 入口实际使用的类,不能混写 本次执行7项正反例及期限边界。部署仍需密钥生成、轮换、OTA签发和撤销策略。AuthManager
全模块 compose 含示例数据库密码、Redis无密码、seccomp:unconfined、latest 镜像标签 默认文件是学习部署配置,不能当已加固的生产清单;MySQL/Redis为容器网络 expose,并非该文件直接发布到宿主公网 自建锁 digest 镜像、最小权限、网络隔离、外置秘密与备份。全模块部署配置
manager-api 有 Shiro oauth2、server secret 与 anon 路由 控制台具备认证结构,但各资源授权仍需逐路由验证。不能因 download 路由 anon 就断言任意下载,它还查 Redis UUID 并使用后删除 先复用设备管理数据模型,接入前审资源归属、下载令牌和管理权限。Shiro 路由、一次性下载 UUID
ASR 文本、LLM 用户输入会进 INFO 日志;智控台模式有文本、音频、工具报告,数据库和 uploadfile volume 持久化 删除临时音频或 nomem 无法覆盖日志、数据库、音频报告的保留与删除 建立采集同意、脱敏、保留期限、跨设备隔离及删除测试。ASR 日志与报告、report、持久化目录
固件 WS v2/v3 接收分支直接按结构和 payload_size 读二进制数据,在该回调中未见与 len 比较的完整帧长检查 属于信任边界审查点,异常服务端或畸形帧影响需专门验证,未在硬件复现 自建协议采用 v1 先互通,随后在接收边界补长度/上限/版本校验及 fuzz。二进制接收回调
MCP user-only 控制枚举可见性,执行函数仍按名称调用 不能把“LLM看不到”当权限;升级和重启有较大设备影响 服务端与设备共用白名单,用户动作走明确授权路径,执行器加入本地限位。工具枚举过滤、执行入口

四、许可与可交付资产

(一)逐层许可检查

两仓库根 LICENSE 都为 MIT,均要求保留版权和许可声明。该结论只覆盖其授予范围,不把第三方包、权重、音色、品牌和硬件设计一起归为 MIT。下表是已打开正文的重点依赖核查,不是完整 SBOM 或法务批准。

层次 核查结果与实际边界 直接依据
两个主仓库 MIT,可按条件复制修改和分发,保留声明。服务端含第三方来源文件时仍需保留原头部/NOTICE 固件 LICENSE、服务端 LICENSE
ESP-IDF manifest 要求 >=6.0.1,核查 v6.0.1 根许可 Apache-2.0;未展开全部组件许可 IDF 要求、ESP-IDF v6.0.1 LICENSE
ESP-SR 固件固定2.4.7。ESPRESSIF MIT 的授权限定 Espressif 产品,不能按普通 MIT 理解为任意芯片可迁移 esp-sr 版本、ESP-SR 2.4.7 许可正文
ESP 音频 codec manifest 为 ~2.5.0。2.5.0 是 Espressif Modified MIT,明确只能与 Espressif 产品结合,禁止为非 Espressif 产品再分发 音频 codec 依赖、esp_audio_codec 2.5.0 许可
LVGL manifest ~9.5.0,v9.5.0 MIT。字体、表情包和其他下载资产仍需各自核查 LVGL v9.5.0 LICENSE、显示与资源依赖
FunASR代码 requirements 固定1.4.16,其 v1.4.16 LICENSE 为 MIT 固定 Python 依赖、FunASR v1.4.16 LICENSE
SenseVoiceSmall权重 默认 model_dir 指向该模型。当前官方模型卡标为 other,链接 FunASR 自定义 MODEL_LICENSE v1.1,包括署名、保留模型名及其他条件,不能归为代码 MIT 默认模型路径、官方模型卡、模型许可正文。两者滚动访问于2026-10-27,尚未下载并固定实际权重 hash
Silero VAD requirements 固定6.2.3,官方 v6.2.3 LICENSE 为 MIT;当前 provider 实际加载本地 ONNX,须对打包的模型文件补 hash 和来源链 Silero VAD v6.2.3 LICENSE、实际 ONNX 路径
edge-tts requirements 固定7.3.1,该版本主体 LGPLv3,只有 srt_composer.py 为 MIT;包装库许可不授予 Microsoft 音色权重或服务经营权 edge-tts 7.3.1 LICENSE、edge-tts 固定版本
默认音色与可选克隆音色 默认 zh-CN-XiaoxiaoNeural 由 Edge 服务生成,仓库没有把音色模型权重授权给集成方。GPT-SoVITS provider 的 ref_audio/ref_text 只是输入接口,没有证明参考说话人授权 默认 Edge 音色、参考音色输入。商业音色和参考录音权利未确认,不直接打包为自有资产
Opus 与唤醒词 Opus 官方 COPYING 包含 BSD式版权条款及专利许可入口,固件实际封装依赖还受 ESP codec 条款约束。ESP-SR 当前 README另明确商业使用唤醒词需相应权利 Opus COPYING、ESP-SR 唤醒词说明。这两份为访问时滚动版本,未声称与所有传递依赖逐字一致

非固定范围依赖、容器镜像、模型下载和 MCU 资源尚未形成可重建物料清单。固件清单存在 ^、~、*,服务端存在 transformers<5、powermem>=0.3.1 等范围。复用前需锁定实际解析版本及制品 hash,而不是只保存两个仓库 commit。见 固件依赖声明、服务端依赖声明。

(二)资产取舍

分类 具体资产 采用方式与不能遗漏的工作
可直接作为开发起点 Application 状态机、AudioService 队列、Board/AudioCodec 接口 在 Espressif 板卡上保留原有分层,选择一个已支持板型建立基线,再替换硬件适配。直接复用是源码起点,不代表已验证本项目硬件
可直接作为开发起点 v1 WebSocket hello/listen/abort/Opus 协议、MCP 参数声明和设备工具注册 独立固定协议契约,先接只读状态与受限音量工具。保留错误处理、必填/范围校验和主任务调度
需要改造 服务端 provider 接口、连接编排、流式 TTS 和队列 裁剪实际需要的 provider,锁定模型/依赖,增加超时、取消、可观测性及并发负载验证。无需引入所有云厂商适配器
需要改造 记忆、智控台、认证、部署文件 记忆改为有来源与删除机制的存储;明确用户/设备隔离;替换示例部署参数,管理台按产品需求决定是否保留
不直接采用 原默认配置作为生产部署、默认角色/音色/唤醒词作为自有商业资产、将小智作为独立桌面整机复制 原配置仍含外部服务依赖与未确认内容授权;不包含完整整机交付。只借鉴接口与结构,不将 README 演示等同于交付

逐项路径、符号、许可边界与固定证据见 xiaozhi-assets.json。

五、替换路径与最小复用验证

(一)保持接口的替换方案

目标 最小替换 必须同时验证
自建语音服务 保留固件 v1 WebSocket,服务端只启用一种 ASR、一种 LLM、一种 TTS hello 音频参数、Opus帧时长、listen/abort/tts顺序、断线回 idle 和重连
局域网离线试验 保留本地 Silero/FunASR,LLM改 Ollama 或本地 OpenAI兼容端点,TTS改已有本地 HTTP provider;关闭外网天气/搜索等工具 模型制品提前准备并锁hash,主LLM及记忆LLM都指向本地,停掉公网网络验证实际出站请求为0。已有接口见 Ollama、本地TTS适配器
最小数据保留 初期选 nomem,关闭不必要上报,日志脱敏并设置保留周期 确认日志、上传目录、MySQL、备份四条路径,不只检查 memory 文件
桌面动作工具 复用 MCP 参数声明,增加一个有限幅度/有限速度的动作工具 设备本地限位与紧急停止不依赖 LLM;未授权工具0次执行,错误参数0次驱动硬件

离线方案是后续验证建议。未安装 Ollama、ASR/TTS服务、依赖或模型,不作“已离线跑通”结论。

(二)本次完成的局部验证

实际执行时间 2026-10-26 18:31:05 UTC,Windows 11,既有 Python 3.13.9。未安装依赖。上游服务推荐 Python 3.10,因此该结果只证明被测纯标准库模块在当前解释器下行为,不证明整服务兼容 Python 3.13。

验证 方法与结果 不能证明的内容
AuthManager 直接 import 下载的 core/auth.py,以固定时间测试正确身份、错误client、错误device、篡改签名、畸形token、期限恰好边界与边界后,7项通过 未测 OTA签发、管理台认证、TLS、吊销或攻击者能力
hello协商与顺序 从原始 helloHandle.py AST 提取未修改函数,替换 transport/MCP/logger协作者执行,确认客户端音频参数原样回传、hello先于MCP初始化、AEC标志生效,3项通过 不是完整 WebSocket 集成测试,也未测试不同采样率音频质量
固件契约 静态 assert 上行Opus/16k/mono、60ms帧、显式队列容量,3项通过 未编译 C++、未验证编解码正确性或硬件实时行为

共 13项通过,是局部函数执行与静态契约核验,不是语法检查冒称端到端。脚本、输出及被测文件 SHA-256保存在 研究底稿(未随网页发布) 与 verification-results.json。

(三)下一轮最小实测与量化观察项

下列样本量是建议验证方案,不是已取得性能数据。先用最新 release 建稳定基线,再对本报告 main 快照做相同测试,以区分版本变化。

  1. 无硬件协议回放:启动隔离服务,固定 v1、一个provider组合,使用授权录音回放30轮短句与30轮长句,记录有效ASR比例、空结果、首个LLM token、首个TTS包和完整回复时间,报告P50/P95与失败数。重点加入小于1秒短指令,核对ASR门槛影响。
  2. 一块硬件闭环:在固定板卡、麦克风、参考音频和扬声器条件下运行,记录唤醒漏检/误检、上行编码丢帧、播放欠载、堆内存低水位、重连次数。每个AEC模式独立记录,不跨硬件宣称通用效果。
  3. 打断与断网:30次播报中插话和30次唤醒词打断,记录用户声音开始至扬声器停声的P50/P95、旧回复尾音和误打断;关闭网络20次,核对idle恢复、重复工具执行、残留队列和资源回收。
  4. 工具与数据边界:覆盖缺参、错类型、越界值、未知工具、未授权用户、重放请求;观察被拒次数、实际执行次数、MCP错误码。两设备并发修改记忆并模拟进程中断,核对串档、丢失和可恢复性。
  5. 离线与保留:在预装模型后封锁公网,完成同一回放,记录全部DNS/HTTP目的地与失败项;删除一个测试用户数据后核对日志、音频、摘要、数据库和备份残留。只在出站为0并完成核心对话后才称该配置离线。

六、证据与未核验范围

正文表格中的永久 GitHub commit 链接是实现证据,许可证表标注版本或滚动访问。正式资产清单维护路径、符号和许可边界。临时目录保留两个固定源码 ZIP、解压源码、GitHub元数据、重点许可原文、局部验证脚本与JSON输出。

已深入阅读启动/音频状态转换、WS/MQTT协议、MCP注册与调用、VAD/ASR/LLM/TTS代表实现、记忆和认证入口,针对性阅读控制台路由及部署配置。未读完所有板型、全部provider、Java业务和前端页面,未运行模型服务、硬件、完整控制台、性能压测或安全审计。没有修改上游源码、公司仓库、发布网站或上传飞书。