《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 可以做到什么？
- 自然对话：用户可以和设备对话，像和真人交流一样自然。语音指令理解：识别“打开灯”、“播放音乐”等命令词，理解用户意图。个性化角色互动：通过不同的提示词，赋予设备不同“性格”，打造智能助手、虚拟人物等。
❓ESP-AI 如何使用 LLM？
ESP-AI 内置多种对接 LLM 的方式：
- OpenAPI 接入支持：支持直接连接第三方大模型接口，完成聊天、问答等。本地模型桥接：可对接自部署的 Ollama、FastChat 等服务，降低使用成本。流式接口处理：内置对话流控制能力，可实时处理语音转文字、文字转语音等任务。
💡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 服务，具备以下优势：
- ✅ 即用即合成：无需模型部署，即调用即返回语音流，适合低延迟场景。🎙️ 多种声音选择：支持多位男女声、童声、角色声线，适配不同设备与使用情境。🔁 连续朗读能力：支持长文本分段朗读与语义间断优化，提升听觉体验。🌐 支持中英混读：内置中英文自动识别与切换机制，适配多语混合内容。
🚀 使用场景示例
| 应用场景 | TTS 用法说明 |
|---|---|
| 智能语音助手 | 将模型输出的回答内容直接转换为语音播放 |
| 虚拟角色对话 | 结合角色语音模型，赋予角色情绪与语调差异化表达 |
| 播报通知提醒 | 用于报警播报、日程提醒、状态提示等信息的语音输出 |
| 儿童故事机 | 批量朗读绘本、儿童故事等内容，增强亲和力与互动性 |
官方 ASR（Automatic Speech Recognition）语音识别功能介绍
🎙️ 什么是 ASR？
ASR（Automatic Speech Recognition，自动语音识别） 是将人类语音实时转换为文本的技术，是语音交互系统的核心之一。
在 ESP-AI 中，ASR 模块负责将用户说出的话转换为文字，并传递给大语言模型（LLM）进行语义理解与响应生成，从而实现完整的语音对话闭环。
🎯 ESP-AI 的 ASR 特性
ESP-AI 提供开箱即用的官方 ASR 服务，并支持本地与云端混合部署，具备以下优势：
- ✅ 低延迟识别：官方服务部署在国内服务器，响应快，适合语音交互场景。🧠 端云协同：支持边缘设备录音上传、实时识别、节省设备算力。🔁 流式识别支持：可边说边识别，适合长句连续对话，体验更自然。🌐 中英混读支持：可识别中英混合语音，适用于多语种交流需求。🎯 关键词唤醒联动：可配合本地唤醒词模型使用，仅在唤醒后上传识别，节省带宽与请求次数。🔒 数据私有可控：支持接入私有部署的 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 的知识库特性
- ✅ 快速上传：支持上传 TXT、PDF、Markdown、网页、Word 等格式文档，一键构建知识库。🧠 智能分片与嵌入：自动将文本切片，生成语义向量用于相似度匹配，提升问答准确率。🔍 语义检索：通过语义向量匹配提取相关内容再交由 LLM 回答，避免“胡编”。🔐 支持私有部署：支持对接 Chroma / Weaviate / Qdrant 等开源向量数据库，数据安全可控。⚡ 高性能向量搜索引擎：官方服务基于高性能索引优化，响应速度快，适用于多轮问答和长内容提取。
🧪 官方知识库服务说明
| 模式类型 | 功能说明 |
|---|---|
| 官方托管模式 | 直接上传文本，使用 ESP-AI 内置知识库系统自动管理、分片、检索 |
| 私有部署模式 | 用户可选择部署 Chroma / FAISS / Milvus 等向量数据库，自主控制存储与接口访问 |
🚀 应用场景示例
| 场景名称 | 知识库应用说明 |
|---|---|
| 专业客服系统 | 将产品手册、FAQ 文档上传为知识库，辅助 LLM 回答用户提问，提高准确率 |
| 企业培训助手 | 上传企业规章制度、操作流程文档，构建企业知识助手，支持员工自助问答 |
| 私人 AI 管家 | 上传个人笔记、收藏资料、日记等内容，打造贴身记忆型 AI 助手 |
| 教育答疑机器人 | 上传课程教材、题库解析等内容，为学生提供实时解答服务 |
| 虚拟 IP 对话系统 | 给角色添加背景世界观文档或人物小传，结合 LLM 构建“有记忆”的虚拟角色互动体验 |
知识库构建流程
📤 如何上传知识内容？
- 登录 ESP-AI 控制台，进入「知识库管理」页面；点击「新建知识库」，填写名称和描述；支持上传
.txt, .md, .pdf, .docx, 网页链接 等格式文件；系统将自动完成分片、嵌入并构建向量索引，无需手动处理。🔍 如何使用知识库进行问答？
- 在系统提示词或对话上下文中启用知识库，例如：
使用 ESP-AI 对话 API 时，自动携带知识库上下文进行问答增强（RAG）；可开启「只答知识库内信息」模式，避免模型编造内容。“请仅根据知识库中的内容作答。”
🧹 如何清理或更新知识库？
- 重新上传新版本内容即可；系统将自动重新分片与更新向量，不影响现有接口调用；支持按文件、知识库、关键词等条件搜索并管理数据。
通过上述构建流程，你可以快速为设备加载专属知识，实现“定制型问答”。ESP-AI 让知识不再是死板的 FAQ，而是可理解、可联想、可对话的活性资源。
官方额度卡（计费与充值）说明
💳 什么是官方额度卡？
额度卡是 ESP-AI 官方推出的统一计费方式，用于支付平台所提供的各类服务，包括：
- LLM 对话调用（官方模型、角色模型、流式接口等）TTS 语音合成（标准音色、克隆音色、超快通道）ASR 语音识别（普通识别、流式识别）知识库调用（语义检索 + LLM 回答）API 接口调用等其他增值功能
额度卡相当于一个“通用余额账户”，所有功能统一从中扣除，使用灵活、无需重复充值多个模块。
💰 ESP-AI 的计费模型
ESP-AI 使用“预付费 + 统一结算”方式：
- 额度卡充值后将实时到账并绑定至当前账号；每次调用 API 或触发语音/识别等动作时，将根据调用类型自动按比例扣除额度；无需额外配置订阅套餐，额度用多少算多少，透明清晰；不设月结，余额不足将自动停止服务，避免过度消费；
🧾 示例服务单价（参考值）
| 功能模块 | 计费方式 | 扣费比例（示例） |
|---|---|---|
| 基础调度费用 | 单次调度消耗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 元 |
实际价格请以控制台展示为准，上述为常规折算示意。
🎯 充值说明与权益
- 支持在线充值（微信 / 支付宝 / 企业对公转账）充值额度越高，享受越多赠送比例与专属服务可开具电子发票，支持企业用户长期计费管理
| 单笔充值金额 | 赠送比例 | 适合人群 |
|---|---|---|
| ¥8.8 | 无赠送 | 测试体验、个人开发 |
| ¥18.8 - ¥118 | +3%~10% | 中小型项目 |
| ¥1000+ | +10%~20% | 企业 / 高频使用 |
🔐 消耗明细查看
用户可在「ESP-AI 控制台 → 额度卡」页面查看：
- 当前余额每笔调用消耗详情模块分类消费统计余额不足预警
🧠 额度卡适用建议
| 使用场景 | 推荐策略 |
|---|---|
| Demo/原型验证 | 充值 ¥20~¥50，体验主要能力 |
| 高频语音互动 | 建议使用超快通道并充值 ¥200 以上 |
| 智能客服类系统 | 建议配置 ¥1000 起步 + 赠送额度 |
| 知识库问答机器人 | 可设置预算 + 查看消耗明细分布优化 |
如何充值额度卡？
🧾 充值流程
- 登录 ESP-AI 控制台；点击额度卡 → 「我的额度」；点击「购买兽卡」按钮；选择充值金额（可选 ¥8.8、¥18.8、¥38.8、¥118、自定义）；选择支付方式（支持：微信 / 支付宝 / 企业转账）；支付完成后额度将自动到账，可立即使用。
💡 补充说明
- 若使用企业对公转账，请联系官方客服获取发票与支付确认；支付后请刷新额度页查看是否到账，若有延迟请耐心等待或联系客服；支持开具电子发票，单笔满 ¥100 可申请开票。
若你是企业客户或有批量接入需求，可联系官方进行专属充值通道配置。
离线语音唤醒模块 ASPRO 使用说明
🛎️ 什么是 ASPRO 唤醒模块？
ASPRO 是 ESP-AI 提供的本地语音唤醒解决方案模块，专为 ESP32-S3 等边缘设备优化设计，支持无需联网即可在设备上实现稳定、高效的唤醒词识别。
与传统的云端唤醒方式相比，ASPRO 模块具备以下显著优势：
- 🚫 完全离线运行，不依赖网络，保障隐私⚡ 响应快速，平均唤醒延迟小于 150ms🎯 可自定义唤醒词，支持烧录任意关键词（如“小明同学”、“你好助手”等）🧠 高准确率，内置降噪、回声消除、前端预处理🛠️ 即插即用，提供标准 API 及工具链支持，适配 Arduino / ESP-IDF 等开发环境
ASPRO 模块适合构建需要本地识别能力的设备，如语音遥控器、智能语音盒子、玩具手办、语音控制家居等场景。
🔧 ASPRO 的核心作用
在 ESP-AI 的整体语音交互架构中，ASPRO 主要用于 “前置唤醒”阶段，即在用户说话前判断是否“叫醒”设备，流程如下：（用户说“唤醒词”）→ ASPRO 在本地监听并识别 → 唤醒成功 → 开始录音上传 / LLM 交互
这不仅减少了后台算力浪费，也极大地降低了云端识别成本，是高频场景中节省资源、提升体验的重要手段。
自定义唤醒词烧录教程
🔨 支持的唤醒词模型格式
ASPRO 使用的是 离线二进制模型（.bin 格式），由官方或工具链训练生成，格式要求如下：
- 代码文件类型：
*.hd支持汉字编译支持常见关键词拼音+语义训练方式🧰 准备工作
在开始烧录前，请确保你具备以下环境：
- 购买ASPRO开发版安装ASPRO 渠道二:语雀平台下载(推荐、不限速下载)；USB 数据线，连接开发板至电脑;核心板需要额外购买ASRPRO烧录器下载并打开代码（代码保存在社群文件：qq群：952051286 ）
🚀 烧录步骤（以 Arduino 为例）
- 将社群下载好的代码保存在桌面上；保证天问编译平台下载安装完毕；双击打开代码；注册并登录天问Block；讲想要的唤醒词输入准确位置，点击生成模型；点击2M编译下载。
✅ 唤醒后建议集成操作
延迟录音：为避免截断唤醒词，建议唤醒后延迟 200~300ms 开始录音；
搭配灯光、声音提示反馈用户唤醒成功，提高体验感；
标准 OTA 升级功能说明
🔄 什么是 OTA 升级？
OTA（Over-The-Air）升级 是指通过无线网络将固件或配置文件远程推送到设备，从而实现系统功能更新、Bug 修复、安全补丁部署等目的的升级方式。
相比传统的“手动刷固件”方式，OTA 拥有以下明显优势：
- ✅ 远程触发，无需物理接线或靠近设备⚙️ 自动下载并验证，保障版本安全与完整性🚀 最小中断升级体验，多数情况下无需重配或用户干预📦 差分升级节省流量，支持仅下载变化部分，适合窄带物联网设备
在 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 控制台操作流程
- 登录 ESP-AI 控制台点击「设备管理」→「选择设备」点击「固件升级」，后台将推送 OTA 请求至目标设备
📌 任务发布后，设备将在下次联网时自动检测升级指令，并下载执行。
其他功能与辅助特性说明
ESP-AI 除了核心功能（LLM 对话、TTS、ASR、知识库、OTA 等），还为开发者和终端设备提供了丰富的辅助能力，进一步提升开发效率、交互体验和运维便利性。
🔌 设备连接与固件烧录功能
ESP-AI 提供便捷的固件烧录工具，支持：
- 即插即烧：自动识别设备端口内置驱动适配：无需手动安装驱动支持一键烧录 ESP32/ESP32-S3 等主流模组可配置自动烧录启动参数（波特率、FLASH 分区）
🔧 工具推荐使用官方提供的固件烧录（支持 Win / Mac / Linux）
🧪 调试与日志查询功能
调试模块帮助开发者快速定位问题并理解设备状态：
- 实时串口日志读取（支持过滤关键词）设备运行状态可视化（连接状态 / 唤醒状态 / 休眠状态）一键查看设备 Token / SN / 网络信息异常记录自动归档，方便云端技术支持复现问题
🗣️ 自由配置系统提示语
支持在设备被激活的不同阶段播放自定义提示语音，增强用户反馈感与个性化：
| 触发场景 | 可配置提示语 |
|---|---|
| 连接服务成功后 | “连接成功，欢迎使用 ESP-AI 语音助手” |
| 被唤醒后 | “我在呢，有什么可以帮你？” |
| 进入休眠状态 | “我休息一会儿，有事叫我哦～” |
| 唤醒失败 / 网络中断等 | “当前网络不可用，请检查连接” |
🧠 指令功能开放平台支持（内置命令）
ESP-AI 平台已内置开放指令集，便于开发者一键调用常用交互命令。例如：
音量调到 50%大点声小点声退下吧帮我写一首歌，主题我不想去上班✅ 所有指令以开放平台配置页面为准，支持自定义扩展。
📊 可视化调用调度与数据统计
控制台内置可视化数据分析模块：
- 展示今日调用量、TTS 播放量、LLM 消耗 Token 等支持筛选按时间 / 设备 / 指令类型查看接口状态监控，支持 webhook 异常告警
🌈 TLED 状态灯说明（用于用户可视提示）
ESP-AI 支持内置状态灯控制规范，标准如下：
| 状态 | TLED 表现方式 |
|---|---|
| 无网络 | 闪烁红色（slow blink） |
| 配网状态 | 闪烁黄色（快速闪烁） |
| 设备待机/聆听状态 | 常亮蓝色 |
| 正在 AI 回答中 | 闪烁彩虹色（渐变呼吸灯效果） |
📎 可根据产品外观和 LED 颗粒数，自定义状态灯逻辑控制。
通过上述辅助功能，ESP-AI 可帮助开发者快速部署稳定、高交互体验的语音设备，并具备完善的可视运维能力。
如需扩展自定义行为（如长按按钮触发 OTA、滑动触摸调音量等），可在控制台指令映射页进行配置或使用 SDK 实现。
