ESP-AI 用户文档---极速上手指南

《ESP-AI开发套件》极速上手指南

🌐 项目定位

开箱即用的AI硬件开发平台，基于MIT协议开源，助力开发者：

• 🚀 零门槛体验大模型与硬件融合开发
• 🎛️ 支持多模态交互与智能设备控制
• 🌍 快速构建商业化AIoT解决方案

📢 开发者交流群：QQ 952051286
📦 开源仓库：立即访问

🧭 核心特性

交互体系

✅ 三重唤醒方式：
语音 | 按钮 | 触摸

✅ 全链路流式交互：
🎤 语音输入 → 🧠 智能处理 → 💬 语音输出

✅ 情绪可视化：
💡 RGB灯光 + 😃 表情UI实时反馈AI状态

开发支持

🔌 插件化架构：自由接入任意LLM/TTS/IAT引擎
🔧 可视化配置中心：网页端实时调整设备参数
🛡️ 企业级功能：C/S架构 + 鉴权体系 + 负载均衡支持

🧰 准备工作

硬件连接

第一步：硬件准备

拿到一个ESP-AI开发板或者准备好一套diy套件，见：物料准备。

第二步：注册用户

点击开放平台，注册并登录上去，首次登录需要使用手机号码验证。
创建一个超体，不用更改任何配置，官方默认已经配备完成。

第三步：观看官方视频资料

开放平台使用教程：固件烧录、配网、基本对话教程。 视频教程

ESP-AI 用户使用手册

🧠什么是 LLM？为什么 ESP-AI 离不开它？

LLM（Large Language Model，大语言模型） 是一种具备强大自然语言理解与生成能力的人工智能模型，能够理解人类语言，生成流畅对话，执行各种智能任务。常见的 LLM 包括 ChatGPT、DeepSeek、豆包等。

ESP-AI 通过连接这些 LLM，让嵌入式设备具备“理解语言、进行交互”的能力，实现从“只能做”到“能听懂、会说话”的跨越。

❓在 ESP-AI 中，LLM 可以做到什么？

1. 自然对话：用户可以和设备对话，像和真人交流一样自然。
2. 语音指令理解：识别“打开灯”、“播放音乐”等命令词，理解用户意图。
3. 个性化角色互动：通过不同的提示词，赋予设备不同“性格”，打造智能助手、虚拟人物等。

❓ESP-AI 如何使用 LLM？

ESP-AI 内置多种对接 LLM 的方式：

1. OpenAPI 接入支持：支持直接连接第三方大模型接口，完成聊天、问答等。
2. 本地模型桥接：可对接自部署的 Ollama、FastChat 等服务，降低使用成本。
3. 流式接口处理：内置对话流控制能力，可实时处理语音转文字、文字转语音等任务。

💡ESP-AI 官方 LLM 介绍

ESP-AI 内置官方大语言模型（LLM）服务，用户无需额外配置即可使用。平台支持免费版本与超快版本，适配不同的开发场景与性能需求。

🌐 模型服务版本

• 免费版本：开箱即用，适合个人开发、快速原型验证。
• 超快版本：响应更快、稳定性更高，适合语音连续对话或商业部署场景。

所有版本均可与 ESP-AI 的本地语音功能结合使用，实现真正的“云边协同”体验。

---

📚 免费版本支持的大模型列表

模型名称	参数规模	特点描述	推荐用途
千问 32B	32B	通用能力强，支持复杂问答	智能助手、泛用问答
OpenChat 7B	7B	多轮对话表现优异	问答、对话
WizardLM2 7B	7B	指令理解优化，指令执行能力强	指令型对话
千问 7B	7B	微调适配角色设定	角色聊天推荐
DeepSeek-R1 14B	14B	检索能力与知识问答能力优秀	知识问答系统
千问 72B	72B	超大模型，逻辑推理与思考能力强	专业级对话
角色扮演通用模型	-	轻量级模型，响应速度快	快速交互场景

---

⚡ 超快版本支持的大模型列表

模型名称	参数规模	特点描述	推荐用途
Doubao-lite-4k	-	响应超快，低延迟对话优化	聊天推荐
DeepSeek-R1	671B	热门通用模型，理解力优秀	多轮问答
Doubao-pro-32k	-	上下文增强，逻辑表达更清晰	智能助手
Doubao-1.5-pro-256k	-	超长上下文支持，推理能力出色	专业知识问答
Doubao-1.5-vision-pro-32k	-	具备图文理解能力的视觉模型	多模态场景

---

✅ 模型选择建议

使用场景	推荐版本	推荐模型
快速体验	免费版本	千问 7B / OpenChat 7B
虚拟角色互动	免费版本	千问 7B / 角色扮演通用模型
高频语音交互	超快/免费版本	Doubao-lite-4k / 角色扮演通用模型
专业问答 / 多轮任务	超快/免费版本	Doubao-pro-32 /256k/ DeepSeek-R1/千问 32/72B
图文理解	超快版本	Doubao-1.5-vision-pro-32k

---

ESP-AI 正在不断接入更多 LLM 模型，满足用户多样化的应用需求。你也可以通过配置自定义 API 接入自己的模型服务。

👩提示词（Prompt）定义与设置建议

📘 什么是提示词？

提示词（Prompt） 是指用于引导 大语言模型（LLM） 行为的一段文字，通常用于设定模型的角色、语气、背景知识或任务目标。一个设计良好的提示词可以显著提升模型输出的准确性和一致性。

在 ESP-AI 中，提示词主要用于设定系统角色（如：老师、助手、虚拟角色等），并结合用户输入，为对话提供语义引导。提示词的精度越高，模型理解和回答的质量越好。

🎯 提示词设置建议

系统提示词优先：建议只设置一个系统提示词，说明 LLM 的身份与行为边界。例如：“你是一位幽默风趣的百科问答助手，善于用简短语言解释复杂问题。”

一键设置预设角色：ESP-AI 提供丰富的角色模板，点击即可应用，无需手动输入提示语。

支持高级自定义：对于高级用户，可扩展上下文信息，如添加规则、数据约束、风格等，进一步提升 LLM 的准确性与个性。

🧩 对话结构规范

为了让模型正确理解上下文，对话应遵循以下结构：

系统消息（system）必须放在最前面；

用户消息（user）与助手消息（assistant）需成对出现，顺序固定为“用户-助手”；

每轮对话必须完整闭环，避免缺失角色；

示例：

{ 系统: “你是一位百科问答助手，善于用简洁的语言解释复杂知识。” },
{ 用户: “黑洞为什么无法逃逸光？” },
{ 助手（LLM）: “assistant”, “content”: “因为黑洞的引力极强，逃逸速度超过光速，而光是宇宙速度的极限，因此无法逃脱。” }

---

合理使用提示词，将大大提升模型的回答质量和互动体验。ESP-AI 支持预设角色与自定义提示词，灵活适配各类应用场景。

官方 TTS（Text-To-Speech）语音合成功能介绍

🔊 什么是 TTS？

TTS（Text-To-Speech），即文本转语音技术，是将输入的文字内容实时合成为自然语音的能力。它使设备“开口说话”成为可能，是语音交互系统不可或缺的一环。

在 ESP-AI 中，TTS 负责将模型生成的文本输出转化为自然、可听的语音，实现完整的“语音对话闭环”。

---

🎯 ESP-AI 的 TTS 特性

ESP-AI 内置了官方高品质 TTS 服务，具备以下优势：

1. ✅ 即用即合成：无需模型部署，即调用即返回语音流，适合低延迟场景。
2. 🎙️ 多种声音选择：支持多位男女声、童声、角色声线，适配不同设备与使用情境。
3. 🔁 连续朗读能力：支持长文本分段朗读与语义间断优化，提升听觉体验。
4. 🌐 支持中英混读：内置中英文自动识别与切换机制，适配多语混合内容。

---

🚀 使用场景示例

应用场景	TTS 用法说明
智能语音助手	将模型输出的回答内容直接转换为语音播放
虚拟角色对话	结合角色语音模型，赋予角色情绪与语调差异化表达
播报通知提醒	用于报警播报、日程提醒、状态提示等信息的语音输出
儿童故事机	批量朗读绘本、儿童故事等内容，增强亲和力与互动性

---

官方 ASR（Automatic Speech Recognition）语音识别功能介绍

🎙️ 什么是 ASR？

ASR（Automatic Speech Recognition，自动语音识别） 是将人类语音实时转换为文本的技术，是语音交互系统的核心之一。

在 ESP-AI 中，ASR 模块负责将用户说出的话转换为文字，并传递给大语言模型（LLM）进行语义理解与响应生成，从而实现完整的语音对话闭环。

---

🎯 ESP-AI 的 ASR 特性

ESP-AI 提供开箱即用的官方 ASR 服务，并支持本地与云端混合部署，具备以下优势：

1. ✅ 低延迟识别：官方服务部署在国内服务器，响应快，适合语音交互场景。
2. 🧠 端云协同：支持边缘设备录音上传、实时识别、节省设备算力。
3. 🔁 流式识别支持：可边说边识别，适合长句连续对话，体验更自然。
4. 🌐 中英混读支持：可识别中英混合语音，适用于多语种交流需求。
5. 🎯 关键词唤醒联动：可配合本地唤醒词模型使用，仅在唤醒后上传识别，节省带宽与请求次数。
6. 🔒 数据私有可控：支持接入私有部署的 OpenASR/Whisper API，保护隐私数据。

---

🧪 官方 ASR 服务说明

ESP-AI 提供的官方 ASR 支持两种接入方式：

接入方式	特点说明
云端官方服务	使用 ESP-AI 官方服务器完成语音识别，延迟低、体验流畅
私有部署 API	支持对接 FastWhisper / OpenASR 等服务，自主控制、便于企业定制部署

---

🚀 应用场景示例

场景名称	ASR 用法说明
智能语音助手	用户讲话后自动转文字交给 LLM 回答
控制命令识别	用于语音控制设备，如“打开空调”、“调低音量”等
多语言助手	可识别中英混合内容，如“播放 some relaxing music”
唤醒词联动	配合本地唤醒模块，仅在触发关键词（如“小明同学”）后启用远程识别

---

官方知识库功能介绍

📚 什么是知识库？

知识库（Knowledge Base） 是指一组结构化或非结构化文本内容，用于为大语言模型（LLM）提供外部补充知识，从而实现更准确、更专业、更可控的智能回答。

在 ESP-AI 中，知识库通过与本地或云端 LLM 结合，使设备不仅能“听懂”和“会说”，更能“知道”并“讲明白”。

---

🎯 ESP-AI 的知识库特性

1. ✅ 快速上传：支持上传 TXT、PDF、Markdown、网页、Word 等格式文档，一键构建知识库。
2. 🧠 智能分片与嵌入：自动将文本切片，生成语义向量用于相似度匹配，提升问答准确率。
3. 🔍 语义检索：通过语义向量匹配提取相关内容再交由 LLM 回答，避免“胡编”。
4. 🔐 支持私有部署：支持对接 Chroma / Weaviate / Qdrant 等开源向量数据库，数据安全可控。
5. ⚡ 高性能向量搜索引擎：官方服务基于高性能索引优化，响应速度快，适用于多轮问答和长内容提取。

---

🧪 官方知识库服务说明

模式类型	功能说明
官方托管模式	直接上传文本，使用 ESP-AI 内置知识库系统自动管理、分片、检索
私有部署模式	用户可选择部署 Chroma / FAISS / Milvus 等向量数据库，自主控制存储与接口访问

---

🚀 应用场景示例

场景名称	知识库应用说明
专业客服系统	将产品手册、FAQ 文档上传为知识库，辅助 LLM 回答用户提问，提高准确率
企业培训助手	上传企业规章制度、操作流程文档，构建企业知识助手，支持员工自助问答
私人 AI 管家	上传个人笔记、收藏资料、日记等内容，打造贴身记忆型 AI 助手
教育答疑机器人	上传课程教材、题库解析等内容，为学生提供实时解答服务
虚拟 IP 对话系统	给角色添加背景世界观文档或人物小传，结合 LLM 构建“有记忆”的虚拟角色互动体验

---

知识库构建流程

📤 如何上传知识内容？

1. 登录 ESP-AI 控制台，进入「知识库管理」页面；
2. 点击「新建知识库」，填写名称和描述；
3. 支持上传 .txt, .md, .pdf, .docx, 网页链接 等格式文件；
4. 系统将自动完成分片、嵌入并构建向量索引，无需手动处理。

---

🔍 如何使用知识库进行问答？

1. 在系统提示词或对话上下文中启用知识库，例如：

   “请仅根据知识库中的内容作答。”

2. 使用 ESP-AI 对话 API 时，自动携带知识库上下文进行问答增强（RAG）；
3. 可开启「只答知识库内信息」模式，避免模型编造内容。

---

🧹 如何清理或更新知识库？

1. 重新上传新版本内容即可；
2. 系统将自动重新分片与更新向量，不影响现有接口调用；
3. 支持按文件、知识库、关键词等条件搜索并管理数据。

---

通过上述构建流程，你可以快速为设备加载专属知识，实现“定制型问答”。ESP-AI 让知识不再是死板的 FAQ，而是可理解、可联想、可对话的活性资源。

官方额度卡（计费与充值）说明

💳 什么是官方额度卡？

额度卡是 ESP-AI 官方推出的统一计费方式，用于支付平台所提供的各类服务，包括：

1. LLM 对话调用（官方模型、角色模型、流式接口等）
2. TTS 语音合成（标准音色、克隆音色、超快通道）
3. ASR 语音识别（普通识别、流式识别）
4. 知识库调用（语义检索 + LLM 回答）
5. API 接口调用等其他增值功能

额度卡相当于一个“通用余额账户”，所有功能统一从中扣除，使用灵活、无需重复充值多个模块。

---

💰 ESP-AI 的计费模型

ESP-AI 使用“预付费 + 统一结算”方式：

1. 额度卡充值后将实时到账并绑定至当前账号；
2. 每次调用 API 或触发语音/识别等动作时，将根据调用类型自动按比例扣除额度；
3. 无需额外配置订阅套餐，额度用多少算多少，透明清晰；
4. 不设月结，余额不足将自动停止服务，避免过度消费；

---

🧾 示例服务单价（参考值）

功能模块	计费方式	扣费比例（示例）
基础调度费用	单次调度消耗1点额度	15000次调度 ≈ 118 元
未标明额外扣费服务	免费	免费
第三方api引用	免费	免费
官方LLM（超快）	单次调度消耗1点额度	15000次使用 ≈ 118 元
TTS 合成（超快）	单次调度消耗1点额度	15000次使用 ≈ 118 元
ASR 识别（超快）	单次调度消耗1点额度	15000次使用 ≈ 118 元
知识库上传检索	单次上传消耗1点额度	15000次上传 ≈ 118 元
歌曲创作（赠送额度）	免费赠送白虎卡单次消耗120点额度	免费
歌曲创作（充值额度）	单次创作歌曲消耗35点额度	430首歌 ≈ 118 元
官方免费音色克隆（解析音频）	单次解析音频扣除1点额度	15000次解析 ≈ 118 元

实际价格请以控制台展示为准，上述为常规折算示意。

---

🎯 充值说明与权益

1. 支持在线充值（微信 / 支付宝 / 企业对公转账）
2. 充值额度越高，享受越多赠送比例与专属服务
3. 可开具电子发票，支持企业用户长期计费管理

单笔充值金额	赠送比例	适合人群
¥8.8	无赠送	测试体验、个人开发
¥18.8 - ¥118	+3%~10%	中小型项目
¥1000+	+10%~20%	企业 / 高频使用

---

🔐 消耗明细查看

用户可在「ESP-AI 控制台 → 额度卡」页面查看：

• 当前余额
• 每笔调用消耗详情
• 模块分类消费统计
• 余额不足预警

---

🧠 额度卡适用建议

使用场景	推荐策略
Demo/原型验证	充值 ¥20~¥50，体验主要能力
高频语音互动	建议使用超快通道并充值 ¥200 以上
智能客服类系统	建议配置 ¥1000 起步 + 赠送额度
知识库问答机器人	可设置预算 + 查看消耗明细分布优化

---

如何充值额度卡？

🧾 充值流程

1. 登录 ESP-AI 控制台；
2. 点击额度卡 → 「我的额度」；
3. 点击「购买兽卡」按钮；
4. 选择充值金额（可选 ¥8.8、¥18.8、¥38.8、¥118、自定义）；
5. 选择支付方式（支持：微信 / 支付宝 / 企业转账）；
6. 支付完成后额度将自动到账，可立即使用。

---

💡 补充说明

• 若使用企业对公转账，请联系官方客服获取发票与支付确认；
• 支付后请刷新额度页查看是否到账，若有延迟请耐心等待或联系客服；
• 支持开具电子发票，单笔满 ¥100 可申请开票。

若你是企业客户或有批量接入需求，可联系官方进行专属充值通道配置。

离线语音唤醒模块 ASPRO 使用说明

🛎️ 什么是 ASPRO 唤醒模块？

ASPRO 是 ESP-AI 提供的本地语音唤醒解决方案模块，专为 ESP32-S3 等边缘设备优化设计，支持无需联网即可在设备上实现稳定、高效的唤醒词识别。

与传统的云端唤醒方式相比，ASPRO 模块具备以下显著优势：

1. 🚫 完全离线运行，不依赖网络，保障隐私
2. ⚡ 响应快速，平均唤醒延迟小于 150ms
3. 🎯 可自定义唤醒词，支持烧录任意关键词（如“小明同学”、“你好助手”等）
4. 🧠 高准确率，内置降噪、回声消除、前端预处理
5. 🛠️ 即插即用，提供标准 API 及工具链支持，适配 Arduino / ESP-IDF 等开发环境

ASPRO 模块适合构建需要本地识别能力的设备，如语音遥控器、智能语音盒子、玩具手办、语音控制家居等场景。

---

🔧 ASPRO 的核心作用

在 ESP-AI 的整体语音交互架构中，ASPRO 主要用于 “前置唤醒”阶段，即在用户说话前判断是否“叫醒”设备，流程如下：
（用户说“唤醒词”）→ ASPRO 在本地监听并识别 → 唤醒成功 → 开始录音上传 / LLM 交互

这不仅减少了后台算力浪费，也极大地降低了云端识别成本，是高频场景中节省资源、提升体验的重要手段。

---

自定义唤醒词烧录教程

🔨 支持的唤醒词模型格式

ASPRO 使用的是 离线二进制模型（.bin 格式），由官方或工具链训练生成，格式要求如下：

1. 代码文件类型：*.hd
2. 支持汉字编译
3. 支持常见关键词拼音+语义训练方式

---

🧰 准备工作

在开始烧录前，请确保你具备以下环境：

1. 购买ASPRO开发版
2. 安装ASPRO 渠道二:语雀平台下载(推荐、不限速下载)；
3. USB 数据线，连接开发板至电脑;核心板需要额外购买ASRPRO烧录器
4. 下载并打开代码（代码保存在社群文件：qq群：952051286 ）

---

🚀 烧录步骤（以 Arduino 为例）

1. 将社群下载好的代码保存在桌面上；
2. 保证天问编译平台下载安装完毕；
3. 双击打开代码；
4. 注册并登录天问Block；
5. 讲想要的唤醒词输入准确位置，点击生成模型；
6. 点击2M编译下载。

✅ 唤醒后建议集成操作

延迟录音：为避免截断唤醒词，建议唤醒后延迟 200~300ms 开始录音；

搭配灯光、声音提示反馈用户唤醒成功，提高体验感；

标准 OTA 升级功能说明

🔄 什么是 OTA 升级？

OTA（Over-The-Air）升级 是指通过无线网络将固件或配置文件远程推送到设备，从而实现系统功能更新、Bug 修复、安全补丁部署等目的的升级方式。

相比传统的“手动刷固件”方式，OTA 拥有以下明显优势：

1. ✅ 远程触发，无需物理接线或靠近设备
2. ⚙️ 自动下载并验证，保障版本安全与完整性
3. 🚀 最小中断升级体验，多数情况下无需重配或用户干预
4. 📦 差分升级节省流量，支持仅下载变化部分，适合窄带物联网设备

在 ESP-AI 中，标准 OTA 被作为系统默认推荐升级方式，适用于所有基于 ESP32 系列的终端设备。

---

📦 ESP-AI OTA 的特性

ESP-AI 提供完整的 OTA 解决方案，包含固件升级与配置升级两个维度：

类型	描述
固件 OTA	升级 .bin 固件，更新程序逻辑和内核
配置 OTA	推送 json/yaml 等配置文件

所有 OTA 操作均可通过 ESP-AI 控制台或 API 进行统一管理，适配不同产品形态。

---

🧠 OTA 的典型应用场景

应用场景	升级内容示例
固件修复或安全加固	修复逻辑崩溃、补充漏洞、协议变更等
更改引脚控制	修改麦克风、扬声器、屏幕等引脚配置
OTA 批量部署	对全量设备或指定 SN 批次进行统一升级控制

---

如何使用 ESP-AI 进行 OTA 升级

🧾 OTA 控制台操作流程

1. 登录 ESP-AI 控制台
2. 点击「设备管理」→「选择设备」
3. 点击「固件升级」，后台将推送 OTA 请求至目标设备

📌 任务发布后，设备将在下次联网时自动检测升级指令，并下载执行。

---

其他功能与辅助特性说明

ESP-AI 除了核心功能（LLM 对话、TTS、ASR、知识库、OTA 等），还为开发者和终端设备提供了丰富的辅助能力，进一步提升开发效率、交互体验和运维便利性。

---

🔌 设备连接与固件烧录功能

ESP-AI 提供便捷的固件烧录工具，支持：

1. 即插即烧：自动识别设备端口
2. 内置驱动适配：无需手动安装驱动
3. 支持一键烧录 ESP32/ESP32-S3 等主流模组
4. 可配置自动烧录启动参数（波特率、FLASH 分区）

🔧 工具推荐使用官方提供的固件烧录（支持 Win / Mac / Linux）

---

🧪 调试与日志查询功能

调试模块帮助开发者快速定位问题并理解设备状态：

• 实时串口日志读取（支持过滤关键词）
• 设备运行状态可视化（连接状态 / 唤醒状态 / 休眠状态）
• 一键查看设备 Token / SN / 网络信息
• 异常记录自动归档，方便云端技术支持复现问题

---

🗣️ 自由配置系统提示语

支持在设备被激活的不同阶段播放自定义提示语音，增强用户反馈感与个性化：

触发场景	可配置提示语
连接服务成功后	“连接成功，欢迎使用 ESP-AI 语音助手”
被唤醒后	“我在呢，有什么可以帮你？”
进入休眠状态	“我休息一会儿，有事叫我哦～”
唤醒失败 / 网络中断等	“当前网络不可用，请检查连接”

---

🧠 指令功能开放平台支持（内置命令）

ESP-AI 平台已内置开放指令集，便于开发者一键调用常用交互命令。例如：

• 音量调到 50%
• 大点声
• 小点声
• 退下吧
• 帮我写一首歌，主题我不想去上班

✅ 所有指令以开放平台配置页面为准，支持自定义扩展。

---

📊 可视化调用调度与数据统计

控制台内置可视化数据分析模块：

1. 展示今日调用量、TTS 播放量、LLM 消耗 Token 等
2. 支持筛选按时间 / 设备 / 指令类型查看
3. 接口状态监控，支持 webhook 异常告警

---

🌈 TLED 状态灯说明（用于用户可视提示）

ESP-AI 支持内置状态灯控制规范，标准如下：

状态	TLED 表现方式
无网络	闪烁红色（slow blink）
配网状态	闪烁黄色（快速闪烁）
设备待机/聆听状态	常亮蓝色
正在 AI 回答中	闪烁彩虹色（渐变呼吸灯效果）

📎 可根据产品外观和 LED 颗粒数，自定义状态灯逻辑控制。

---

通过上述辅助功能，ESP-AI 可帮助开发者快速部署稳定、高交互体验的语音设备，并具备完善的可视运维能力。

如需扩展自定义行为（如长按按钮触发 OTA、滑动触摸调音量等），可在控制台指令映射页进行配置或使用 SDK 实现。