diff --git a/README.zh.md b/README.zh.md index bb74987..b350a1e 100644 --- a/README.zh.md +++ b/README.zh.md @@ -12,9 +12,7 @@ - - Elato Logo @@ -24,15 +22,17 @@ ## 新闻 -- **2026-03-14：** Elato 刚刚发布了 Local AI Toys。🎉🎉🎉 而且今天还是 Pi Day！现在你的 ESP32 设备可以通过 MLX 支持本地 AI 模型和语音生成，配合 Qwen、Mistral 等前沿本地 LLM 和 TTS 模型。点击[这里](https://www.github.com/akdeb/local-ai-toys)查看。 +- **2026 年 4 月 17 日：** 现在可以用 Cloudflare Voice Agents 和 Durable Objects 构建全球化的设备/玩具语音网络。Cloudflare Workers AI 原生提供 Deepgram STT/TTS，因此你只需要提供一个 LLM API Key，就能搭建可扩展、低延迟的语音 AI 流水线。 +- **2026 年 4 月 15 日：** 现在你可以通过基于 Pipecat 的 FastAPI 服务器部署 100 多种 STT、LLM、TTS 语音流水线系统。 +- **2026 年 3 月 14 日：** Elato 在 Pi Day 发布了 Local AI Toys。你的 ESP32 设备现在可以通过 MLX 运行本地 AI 模型和语音生成，支持 Qwen、Mistral 等本地前沿 LLM 和 TTS 模型。点击[这里](https://www.github.com/akdeb/local-ai-toys)查看。 # 👾 ElatoAI：在 Arduino ESP32 上运行实时语音 AI 模型 -基于先进语音模型的实时 AI 语音系统，可运行在 ESP32 上，并通过安全 WebSocket 与 Deno Edge Functions 实现全球范围内超过 15 分钟的不间断对话。当前支持 OpenAI Realtime API、Gemini Live API、xAI Grok Voice Agents API、Eleven Labs Conversational AI Agents 和 Hume AI EVI-4。 +ElatoAI 让你在 ESP32 上运行由 100 多种语音 AI 模型驱动的实时语音系统，并通过安全 WebSocket 与边缘函数实现全球范围内 20 分钟以上的不间断对话。 - [🚀 快速开始](https://www.elatoai.com/docs/quickstart) - [使用 PlatformIO 构建](https://www.elatoai.com/docs/platformio) -- [在 Arduino IDE 上构建](https://www.elatoai.com/docs/arduino) +- [在 Arduino IDE 中构建](https://www.elatoai.com/docs/arduino) - [全球部署](https://www.elatoai.com/docs/blog/deploying-globally) - [🤖🤖🤖 部署多台设备](https://www.elatoai.com/docs/blog/multiple-devices) @@ -46,6 +46,20 @@ 视频链接：[OpenAI 演示](https://youtu.be/o1eIAwVll5I) | [Gemini 演示](https://youtu.be/_zUBue3pfVI) | [Eleven Labs 演示](https://youtu.be/7LKTIuEW-hg) | [Hume AI EVI-4 演示](https://youtu.be/Gtann5pdV0I) +## 🧠 模型 + +### Deno Edge +1. [OpenAI Realtime API](https://github.com/akdeb/ElatoAI/tree/main/server/deno/models/openai) +2. [Gemini Live API](https://github.com/akdeb/ElatoAI/tree/main/server/deno/models/gemini) +3. [xAI Grok Voice Agent API](https://github.com/akdeb/ElatoAI/tree/main/server/deno/models/grok) +4. [Eleven Labs Conversational AI Agents](https://github.com/akdeb/ElatoAI/tree/main/server/deno/models/elevenlabs) +5. [Hume AI EVI-4](https://github.com/akdeb/ElatoAI/tree/main/server/deno/models/hume) + +### Cloudflare Workers +1. LLM - [80 多种模型](https://developers.cloudflare.com/workers-ai/models/?tasks=Text+Generation)，包括 OpenAI、Gemini、xAI 等。 +2. TTS - [10 多种模型](https://developers.cloudflare.com/workers-ai/models/?tasks=Text-to-Speech)，包括 Deepgram、MeloTTS 等。 +3. STT - [5 种模型](https://developers.cloudflare.com/workers-ai/models/?tasks=Automatic+Speech+Recognition)，包括 Whisper、Deepgram 等。 + ## 👷‍♀️ DIY 硬件设计 Hardware Setup @@ -56,50 +70,48 @@ App Screenshots -## ⭐️ 语音 AI 关键特性 -App Screenshots - ## 🌟 完整功能列表 -1. **实时语音转语音**：基于 OpenAI Realtime API、Gemini Live API、xAI Grok Voice Agent API、Eleven Labs Conversational AI Agents 和 Hume AI EVI4 的即时语音转换。 -2. **创建自定义 AI 智能体**：创建拥有不同个性和声音的自定义智能体。 -3. **可定制语音**：从多种声音和人格中进行选择。 +1. **实时语音转语音**：由 OpenAI Realtime API、Gemini Live API、xAI Grok Voice Agent API、Eleven Labs Conversational AI Agents 和 Hume AI EVI4 驱动的即时语音转换。 +2. **创建自定义 AI 智能体**：创建具有不同人格和声音的 AI 智能体。 +3. **可自定义语音**：从多种声音和人格配置中进行选择。 4. **安全 WebSocket**：可靠且加密的 WebSocket 通信。 -5. **服务端 VAD 轮次检测**：智能处理对话轮次，让交互更流畅。 +5. **服务端 VAD 轮次检测**：智能对话轮次处理，让交互更自然。 6. **Opus 音频压缩**：以极低带宽实现高质量音频流传输。 -7. **全球边缘性能**：低延迟的 Deno Edge Functions 确保全球范围内的流畅对话。 -8. **ESP32 Arduino 框架**：经过优化且易于使用的硬件集成方案。 -9. **对话历史**：查看你的历史对话记录。 +7. **全球边缘性能**：低延迟的 Deno Edge Functions 确保全球范围内的顺畅对话。 +8. **ESP32 Arduino 框架**：经过优化且易于集成的硬件方案。 +9. **对话历史**：查看历史对话记录。 10. **设备管理与认证**：注册并管理你的设备。 -11. **用户认证**：安全的用户认证与授权。 -12. **通过 WebRTC 和 WebSocket 对话**：你可以在 NextJS Web 应用中通过 WebRTC 与 AI 对话，也可以在 ESP32 上通过 WebSocket 对话。 -13. **音量控制**：在 NextJS Web 应用中控制 ESP32 扬声器的音量。 -14. **实时转录**：你的对话实时转录内容会存储在 Supabase 数据库中。 +11. **用户认证**：安全的用户身份认证与授权。 +12. **通过 WebRTC 和 WebSocket 对话**：在 NextJS Web 应用中用 WebRTC 与 AI 对话，在 ESP32 上通过 WebSocket 对话。 +13. **音量控制**：通过 NextJS Web 应用控制 ESP32 扬声器音量。 +14. **实时转录**：对话实时转录结果存储在 Supabase 数据库中。 15. **OTA 更新**：支持 ESP32 固件空中更新。 -16. **通过 Captive Portal 管理 Wi-Fi**：在 ESP32 设备上连接到你的 Wi-Fi 网络或热点。 +16. **通过 captive portal 管理 Wi-Fi**：直接在 ESP32 设备上连接 Wi-Fi 或热点。 17. **恢复出厂设置**：通过 NextJS Web 应用对 ESP32 设备执行恢复出厂设置。 -18. **按钮与触摸支持**：可使用按钮或触摸传感器来控制 ESP32 设备。 -19. **无需 PSRAM**：ESP32 设备无需 PSRAM 即可运行语音转语音 AI。 -20. **Web 客户端 OAuth**：为你的用户提供 OAuth，以管理他们的 AI 角色和设备。 -21. **音高因子**：在 NextJS Web 应用中调节 AI 语音的音高，以创建更卡通化的声音。 -22. **工具调用**：从 ESP32 设备调用 Deno Edge Functions 上的工具和函数，构建完整的语音 AI 智能体。 -23. **轻触唤醒**：轻触触摸板即可从休眠中唤醒设备。 +18. **按钮和触摸支持**：可以通过按钮或触摸传感器控制 ESP32 设备。 +19. **无需 PSRAM**：设备无需 PSRAM 即可运行语音转语音 AI。 +20. **Web 客户端 OAuth**：让用户管理自己的 AI 角色和设备。 +21. **音高控制**：在 NextJS Web 应用中调整 AI 声音音高，做出更卡通化的声音。 +22. **工具调用**：从 ESP32 设备调用边缘函数中的工具和函数，构建完整的语音 AI 智能体。 +23. **轻触唤醒**：轻触触摸板即可从休眠中唤醒。 +24. **部署到 Cloudflare**：借助 Cloudflare Voice Agents 和 Durable Objects 连接任意 LLM、TTS、STT 服务。 ## 项目架构 -ElatoAI 由三个主要组件构成： +ElatoAI 由三个主要组件组成： 1. **前端客户端**（部署在 Vercel 上的 `Next.js`）- 用于创建并与 AI 智能体对话，并将其“发送”到你的 ESP32 设备 -2. **边缘服务函数**（运行在 Deno/Supabase Edge 上的 `Deno`）- 用于处理来自 ESP32 设备的 WebSocket 连接以及对 LLM 提供商 API 的调用 -3. **ESP32 IoT 客户端**（`PlatformIO/Arduino`）- 用于接收来自边缘服务函数的 WebSocket 连接，并通过 Deno 边缘服务把音频发送给 LLM 提供商 +2. **边缘服务函数**（`Deno Edge` 或 `Cloudflare Workers`）- 用于处理来自 ESP32 设备的 WebSocket 连接以及对模型提供商 API 的调用 +3. **ESP32 IoT 客户端**（`PlatformIO/Arduino`）- 接收来自边缘服务函数的 WebSocket 连接，并通过 Deno 边缘服务器或 Cloudflare Durable Objects 把音频发送给模型提供商 ## 🛠 技术栈 -| 组件 | 使用的技术 | +| 组件 | 使用技术 | |-----------------|------------------------------------------| | 前端 | Next.js, Vercel | | 后端 | Supabase DB | -| 边缘函数 | 运行于 Deno/Supabase 的 Deno Edge Functions | +| 边缘函数 | Deno Edge 或 Cloudflare Workers | | IoT 客户端 | PlatformIO, Arduino Framework, ESP32-S3 | | 音频编解码 | Opus | | 通信 | 安全 WebSockets | @@ -115,7 +127,7 @@ flowchart TD end UserInput --> ESP32 - ESP32[ESP32 设备] -->|WebSocket| Edge[Deno Edge Function] + ESP32[ESP32 设备] -->|WebSocket| Edge[Deno Edge / Cloudflare Workers] Edge -->|OpenAI API| OpenAI[OpenAI Realtime API] Edge -->|Gemini API| Gemini[Gemini Live API] Edge -->|xAI API| xAI[xAI Grok Voice Agent API] @@ -135,14 +147,14 @@ flowchart TD ```mermaid graph TD repo[ElatoAI] - repo --> frontend[前端 Vercel NextJS] - repo --> deno[Deno Edge Function] - repo --> esp32[ESP32 Arduino 客户端] - deno --> supabase[Supabase DB] + repo --> frontend[Frontend Vercel NextJS] + repo --> server[Deno Edge Function / Cloudflare Workers] + repo --> esp32[ESP32 Arduino Client] + server --> supabase[Supabase DB] frontend --> supabase - esp32 --> websockets[安全 WebSockets] - esp32 --> opus[Opus 编解码器] + esp32 --> websockets[Secure WebSockets] + esp32 --> opus[Opus Codec] esp32 --> audio_tools[arduino-audio-tools] esp32 --> libopus[arduino-libopus] esp32 --> ESPAsyncWebServer[ESPAsyncWebServer] @@ -151,38 +163,39 @@ graph TD ## 📊 关键指标 - **延迟**：全球往返延迟小于 2 秒 -- **音频质量**：使用 12kbps Opus 编码（高清晰度），24kHz 采样率 -- **不间断对话**：全球范围内支持最长 15 分钟连续对话 -- **全球可用性**：通过边缘计算进行优化 +- **音频质量**：12kbps Opus 编码（高清晰度）+ 24kHz 采样率 +- **不间断对话**：全球范围内最长可达 20 分钟连续对话 +- **全球可用性**：通过边缘计算优化 ## 🛡 安全性 - 使用安全 WebSocket（WSS）进行加密数据传输 -- 可选：使用 256 位 AES 对 API Key 进行加密 +- 可选：使用 256 位 AES 加密 API Key - 使用 Supabase DB 进行安全认证 -- 所有数据表均采用 Postgres RLS +- 所有表均采用 Postgres RLS ## 🚫 限制 - 连接边缘服务器时有 3-4 秒冷启动时间 -- 已测试最长连续对话时间约为 17 分钟 -- 当超过墙钟时间限制时，边缘服务器会停止运行 -- ESP32 上暂无语音打断检测 +- 已测试最长连续对话约为 17 分钟 +- 超过 wall clock time 后边缘服务器会停止 +- ESP32 上尚未支持语音打断检测 ## 🙌 贡献 -我们非常欢迎你的贡献！这里有一些可以参与的方向： +欢迎贡献。你可以从这些方向开始： 1. ESP32 上的语音打断（已支持 OpenAI） 2. ~~添加 Arduino IDE 支持~~ -3. ~~添加用于情绪检测的 Hume API 客户端~~ +3. ~~添加 Hume API 客户端用于情绪检测~~ 4. 在 Deno Edge 上添加 MCP 支持 5. ~~接入 Eleven Labs API 进行语音生成~~ 6. 添加 Azure OpenAI 支持（容易上手）- 审核中 7. 添加 Cartesia 支持 8. 添加 Amazon Nova 支持 9. 添加 Deepgram 支持 +10. ~~添加 Cloudflare Workers 支持~~ ## 许可证 -本项目基于 MIT License 发布，详情请参见 [LICENSE](LICENSE) 文件。 +本项目基于 MIT License 发布，详情请查看 [LICENSE](LICENSE)。 -**欢迎查看我们的硬件产品：[ElatoAI Products](https://www.elatoai.com/)。如果你觉得这个项目有趣或有帮助，欢迎在 GitHub 上给这个项目点个 Star。⭐** +**欢迎查看我们的硬件产品：[ElatoAI Products](https://www.elatoai.com/)。如果你觉得这个项目有趣或有帮助，欢迎在 GitHub 上给它点个 Star。⭐** diff --git a/server/cloudflare/README.md b/server/cloudflare/README.md index 0a77b49..5001ae1 100644 --- a/server/cloudflare/README.md +++ b/server/cloudflare/README.md @@ -1,46 +1,257 @@ -# server-cloudflare +# server/cloudflare -Cloudflare Workers + Durable Objects voice backend for Elato. +Cloudflare Workers + Durable Objects backend for Elato's ESP32 realtime voice flow. -This starts with one ESP32-compatible websocket path: +This server keeps the existing Elato device protocol and routes audio through Cloudflare-hosted services: -- `/ws/esp32` - -The route is backed by a Durable Object that preserves the Elato device control protocol. - -## Current stack - -- STT: `@cf/openai/whisper` +- STT: Cloudflare Workers AI via `@cloudflare/voice` - LLM: OpenAI Chat Completions -- TTS: `@cf/deepgram/aura-1` +- TTS: Cloudflare Workers AI Deepgram Aura +- Transport: WebSocket + Opus packetization for ESP32 -## Local setup +If you are new to the overall project, start with the root README first: -1. Install dependencies +- `/Users/akashdeepdeb/Desktop/Projects/ElatoAI/README.md` +- `/Users/akashdeepdeb/Desktop/Projects/ElatoAI/server/README.md` + +## What This Server Does + +This backend is meant to be an alternative to the Deno edge server, not a separate firmware protocol. + +The ESP32 still talks to the same Elato-style control surface: + +- `auth` +- `AUDIO.COMMITTED` +- `RESPONSE.CREATED` +- binary audio frames +- `RESPONSE.COMPLETE` +- `SESSION.END` + +Public route: + +```text +/ws/esp32 +``` + +Health check: + +```text +/healthz +``` + +## Current Layout + +```text +server/cloudflare/ +├── models/ +│ ├── llm.ts +│ ├── session.ts +│ ├── stt.ts +│ └── tts.ts +├── src/ +│ ├── index.ts +│ ├── opus.ts +│ ├── prompt.ts +│ └── types.ts +├── package.json +└── wrangler.toml +``` + +## How It Works + +1. The ESP32 opens a secure websocket to `/ws/esp32`. +2. The Worker creates a fresh Durable Object session for that websocket. +3. The server sends the Elato `auth` payload. +4. The server triggers the first assistant turn. +5. LLM output is synthesized to audio. +6. Audio is packetized into Opus frames and streamed back to the ESP32. +7. After playback, the ESP32 goes back to listening. +8. Incoming mic audio is fed to the STT session for the next turn. + +## Prerequisites + +You need: + +- Node.js 22+ +- npm +- a Cloudflare account with Workers enabled +- a Workers AI binding +- an OpenAI API key for the LLM path + +## Local Development + +### 1. Install dependencies ```bash +cd /Users/akashdeepdeb/Desktop/Projects/ElatoAI/server/cloudflare npm install ``` -2. Copy `.dev.vars.example` to `.dev.vars` and fill in your keys. +### 2. Create local env vars -3. Run locally +Copy the example file: + +```bash +cp .dev.vars.example .dev.vars +``` + +Then fill in the values you actually need. + +Typical local file: + +```env +OPENAI_API_KEY=... +ELATO_OPENAI_MODEL=gpt-4.1-mini +ELATO_OPENAI_SYSTEM_PROMPT=You are a friendly toy character. +ELATO_OPENAI_FIRST_MESSAGE=Say hello first in one short sentence. +``` + +Notes: + +- `JWT_SECRET_KEY` is not currently required for the stripped-down iteration unless you wire auth back in. +- Do not commit real secrets. + +### 3. Run locally ```bash npm run dev ``` -## Notes +This uses: -- ESP32 clients should connect to: - -```text -wss:///ws/esp32 +```bash +wrangler dev --ip 0.0.0.0 --port 8787 ``` -- Auth is intentionally left out of this iteration. Add your own auth check in the Worker route before using this in production. -- This backend now targets the current Elato ESP32 control protocol first: - `auth`, `AUDIO.COMMITTED`, `RESPONSE.CREATED`, binary audio frames, `RESPONSE.COMPLETE`, and `SESSION.END`. -- It does not currently use `@cloudflare/voice`; the Durable Object owns the websocket session directly so the firmware protocol stays explicit. -- The ESP32 route now packetizes Cloudflare TTS output into Opus frames before sending binary websocket packets, matching the same 24kHz mono / 120ms framing shape used by `server/deno`. -- The remaining gap is operational, not transport-level: this prototype still has placeholder auth / DB comments and has not been load-tested against long-running device sessions yet. +So local access is typically: + +```text +http://:8787/healthz +ws://:8787/ws/esp32 +``` + +For local firmware testing: + +- point the ESP32 at your machine's LAN IP, not `0.0.0.0` +- local plain `ws://` is fine for quick testing if your firmware build allows it +- production firmware should use `wss://` + +## Deploying to Cloudflare + +### 1. Set Worker secrets + +Set the runtime secrets in Cloudflare: + +- `OPENAI_API_KEY` +- optionally `ELATO_OPENAI_MODEL` +- optionally `ELATO_OPENAI_SYSTEM_PROMPT` +- optionally `ELATO_OPENAI_FIRST_MESSAGE` + +### 2. Deploy + +```bash +cd /Users/akashdeepdeb/Desktop/Projects/ElatoAI/server/cloudflare +npm run deploy +``` + +### 3. Point the ESP32 at the Worker + +Example production route: + +```text +wss://.workers.dev/ws/esp32 +``` + +## Durable Object Model + +The current setup uses one fresh Durable Object per websocket voice session. + +That is the sensible default for realtime voice apps because: + +- each call/session gets isolated state +- reconnects do not inherit stale memory +- turn state is easier to reason about +- cleanup is straightforward + +This is what the Worker does in `/Users/akashdeepdeb/Desktop/Projects/ElatoAI/server/cloudflare/src/index.ts`. + +## Migrations + +This backend already has a Durable Object rename migration in `/Users/akashdeepdeb/Desktop/Projects/ElatoAI/server/cloudflare/wrangler.toml`: + +- `ElatoOpenAiVoiceAgent` -> `ElatoVoiceSession` + +If you rename the DO again later, add another migration instead of just changing the class name. + +## Common Commands + +Typecheck: + +```bash +npm run typecheck +``` + +Local dev: + +```bash +npm run dev +``` + +Deploy: + +```bash +npm run deploy +``` + +## Operational Notes + +A few things matter in practice: + +- Rapid reconnect testing can trigger Workers AI rate limits, especially on TTS. +- If you redeploy while a websocket session is active, Cloudflare may log: + `This script has been upgraded. Please send a new request to connect to the new version.` + That is expected during deploy churn. +- If the ESP32 flips into speaking briefly and then falls back, check whether TTS actually produced audio or hit a `429`. +- If STT does not advance turns, inspect the STT provider logs first before debugging firmware state. + +## Current Limitations + +This Cloudflare backend is still a pragmatic project backend, not a polished platform product. + +Current caveats: + +- auth is still intentionally stubbed out with comments +- DB writes are still placeholders +- Workers AI rate limiting can affect repeated testing +- the stack is still operationally rough compared with the more mature Deno path + +## Recommended Files To Read + +If you are modifying this backend, read these first: + +- `/Users/akashdeepdeb/Desktop/Projects/ElatoAI/server/cloudflare/src/index.ts` +- `/Users/akashdeepdeb/Desktop/Projects/ElatoAI/server/cloudflare/models/session.ts` +- `/Users/akashdeepdeb/Desktop/Projects/ElatoAI/server/cloudflare/models/stt.ts` +- `/Users/akashdeepdeb/Desktop/Projects/ElatoAI/server/cloudflare/models/llm.ts` +- `/Users/akashdeepdeb/Desktop/Projects/ElatoAI/server/cloudflare/models/tts.ts` +- `/Users/akashdeepdeb/Desktop/Projects/ElatoAI/firmware-arduino/src/Audio.cpp` +- `/Users/akashdeepdeb/Desktop/Projects/ElatoAI/firmware-arduino/src/Config.cpp` + +## Relationship To Other Servers + +Elato currently includes multiple backend paths: + +- `/Users/akashdeepdeb/Desktop/Projects/ElatoAI/server/deno` +- `/Users/akashdeepdeb/Desktop/Projects/ElatoAI/server/cloudflare` +- `/Users/akashdeepdeb/Desktop/Projects/ElatoAI/server/fastapi` + +Use Cloudflare when you want: + +- Workers + Durable Objects +- Cloudflare-hosted STT/TTS +- a stateful edge session model + +Use Deno when you want: + +- the most battle-tested Elato path right now +- direct provider integrations already working in production