iotta

一体化自托管平台，用于在嵌入式设备上构建、测试和运行语音 AI——从第一天的仿真模拟，到生产环境的设备群管理。

iotta 是将嵌入式设备变成语音助手的服务器——它接收设备发来的音频，通过语音识别 → 大语言模型 → 语音合成流水线进行处理，调度工具调用，并将合成语音流式返回给设备。同时，iotta 也是开发环境，供同一个团队构建该助手：同一台服务器贯穿从无硬件的仿真模拟、原型调试，到生产环境部署的全过程，无需单独的测试工具，也无需在各阶段之间重新集成。

iotta 不包含任何产品相关的特定知识——任何语音 AI 产品都可以直接构建于其上，无需修改平台本身。

为什么选择 iotta

一个平台贯穿完整生命周期——硬件存在之前就能仿真，再将完全一致的行为带到现场。
AI 团队与固件团队基于同一份版本化工具契约并行开发。
自托管、不绑定提供商、全面可观测——在一台小型主机上以单容器运行，通过配置切换 OpenAI 或本地模型，默认开启 TLS，并配合支持自动回滚的安全分阶段 OTA。

完整介绍、功能详述以及与 xiaozhi 的对比，请参阅 docs/product.md（中文版）。

运营 UI

所有管理操作均在浏览器中完成，由平台自身提供，无需单独安装。（截图中为内置的空状态演示内容。）


设备与设备群在线状态	工具与提示词注册表


固件灰度发布	会话追踪

快速开始

Docker（推荐）

cp config.example.yaml config.yaml     # 按需修改路径和密钥
cp .env.example .env                    # 填写 OPENAI_API_KEY（及各类令牌）
docker compose up

运营 UI 随即在 http://localhost:8000/（会自动跳转至 /ui）提供服务。

从源码运行（开发模式）

# 系统依赖
apt install libopus-dev libportaudio2   # Linux
brew install opus portaudio             # macOS

# 服务端
cd server
pip install uv
uv pip install -e ".[dev,audio]"
cp config.example.yaml config.yaml      # 填写 API 密钥
IOTTA_CONFIG=config.yaml iotta          # 在 :8000 启动 API + UI

# 客户端（软件设备模拟器）
cd ../client
uv pip install -e .
iotta-client --server ws://localhost:8000/session

命令行工具

服务端包安装时会同时安装以下运维 CLI：

命令	用途
`iotta`	运行会话服务器 + 运营 UI
`iotta-registry`	管理工具/提示词版本及晋升
`iotta-eval`	运行有评分的评测套件
`iotta-devices`	设备、智能体、固件、OTA 灰度/回滚
`iotta-doctor`	预检：存储、磁盘、认证状态、提供商密钥
`iotta-backup` / `iotta-restore`	一致性快照 ↔ 恢复（单个 `.tar.gz`）

环境变量

变量	用途
`OPENAI_API_KEY`	通过 OpenAI 使用 ASR（Whisper）、LLM、TTS（参考提供商）
`IOTTA_CONFIG`	配置 YAML 的路径（默认：`config.yaml`）
`IOTTA_ADMIN_TOKEN`	管控 `/admin` 运营 API 的 Bearer 令牌
`IOTTA_SESSION_TOKEN`	共享设备会话令牌（同时支持按设备独立令牌）

代码仓库结构

server/              # FastAPI 会话服务器 + 运营 UI
  src/iotta/         # 主包
  src/iotta/web/     # 运营 UI（静态 ES 模块，无需构建步骤）
  tests/             # pytest 测试套件（无需外部依赖）
client/              # 软件设备客户端（麦克风 → Opus → 扬声器）
deploy/              # 反向代理配置示例（Caddy、nginx）
docs/                # 设计、产品、协议、各子系统参考文档

运行测试

cd server
PYTHONPATH=src python -m pytest tests/ -v

测试无需系统音频库（opuslib 已 mock），也不需要网络连接。

文档

文档	用途
`docs/product.md`	iotta 是什么、面向谁、与竞品对比（中文版）
`docs/design.md`	工程愿景与设计原则（中文版）
`docs/protocol-spec.md`	通信协议——规范性消息参考（中文版）
`docs/protocol-design.md`	协议设计原理 + 固件移植指南（来自 xiaozhi）（中文版）
`docs/commercialization.md`	开放核心模式、版本规划、设备上限设计
`CONTRIBUTING.md`	贡献指南（含变更日志规范）
`CHANGELOG.md`	发布历史与变更记录

授权与版本

iotta 采用双重授权的开放核心模式：

核心源码——FSL-1.1-ALv2（Functional Source License）：可自由使用、修改和自托管，包括内部及非竞争性商业用途；每次发布两年后自动转换为 Apache-2.0。
商业版——商业许可证（通过许可证密钥激活）：用于超出内置设备上限的运营，以及使用仅限商业版的功能。

免费社区版是完整的开发平台，活跃设备数量有上限，适用于演示、个人使用和评估。详见 docs/commercialization.md。核心版本始终可在无需任何云依赖的情况下运行。