Nanosamurai

项目简介

Nanosamurai（nanosamur.ai）是一套开源的语音 AI 编排平台，专为"不能把敏感对话交给第三方"的组织而设计。它的口号是"守护你的敏感对话，你的声音、你的掌控"。项目以生产级、分布式架构实现，模型无关，并支持多租户，完全运行在你自己掌控的基础设施中——本机、私有云或本地机房皆可。

作者过去几年为多家处理敏感数据、必须在气隙环境中运行的机构做咨询，Nanosamurai 正是这些实战经验的产物。它可以理解为语音处理领域的"Ollama + Ollama Cloud"：既能在电脑上通过 Electron 应用加 docker compose 本地运行，也能把同一套栈直接搬到云或 K8s 上，因为它从一开始就按规模化设计，并内置了可观测性栈。

核心功能

• 多模式语音处理：支持实时、半实时（精修）与批量三种转写模式，可分别选用不同模型，并提供统一的技术栈用于稳健的语音处理、Agent 工作流与 Webhook。
• 模型无关：目前已支持 whisper、qwen asr、nemotron asr、parakeet tdt 等模型，并持续接入更多。
• 说话人识别与预处理：内置 diarization（当前支持 Pyannote 或 Sortformer）、VAD、对齐等能力。
• 开箱即用的前后端：提供浏览器 UI、Windows 优先的 Electron 桌面端、API、Python SDK 与 CLI 源码、录音存储、PostgreSQL 转写持久化。
• 多租户支持：面向组织级部署，隔离不同租户的数据。
• 内置可观测性：可选 Grafana、Prometheus、Tempo、Loki 与 Alloy 组成的监控栈，便于追踪与审计。
• Agent 工作流与 Webhook 契约：公开代码包含相关工作流与 Webhook 契约（社区版暂不附带执行与投递服务，但可自行实现并接入）。

技术实现

系统采用分布式的微服务架构。客户端一侧提供基于 ClojureScript 的浏览器 UI 与 Windows 优先的 Electron 应用，二者均通过 HTTP 访问 /api 与 /auth，并通过 WebSocket 传输音频（/ws/audio，PCM16LE 单声道 16kHz）与事件（/ws/events，JSON 事件）。服务端核心是 SamuraiBFF，负责 API 与编排，它按所选实时轨向 RealtimeService 发起 gRPC 流。

音频数据经 Kafka 流转：SamuraiBFF 将 AudioChunk（protobuf）写入 audio.raw 主题、将压缩 JSON 写入 sessions.meta；RefinementService 消费 audio.raw 产出精修事件 transcripts.refined；RecorderWorker 消费音频并把会话 WAV 写入兼容 S3 的对象存储（生产可用 Ceph，本地用 LocalStack），随后产出 recordings.finished；FinalizerService 据此生成最终转写 transcripts.final；SamuraiPersistor 消费精修与最终转写并写入 PostgreSQL，供 SamuraiBFF 查询。实时、精修与终结环节均可选用不同的语音模型，并可读取可选的说话人注册信息进行说话人区分。整套服务镜像从 ghcr.io/nanosamurai/* 拉取并按源码 SHA 固定版本，保证可复现。

快速上手

1. 准备环境：这是运行社区版本地的公共前门仓库，需先准备好 Docker 与 Docker Compose。
2. 克隆主仓库：以官方主仓库 https://github.com/nanosamurai/nanosamurai 为入口，它提供了 docker compose 起步配置。
3. 启动服务栈：通过 docker compose 拉起所需服务（本地环境下对象存储使用 LocalStack 等），服务镜像会按固定的源码 SHA 自动拉取。
4. 打开界面试用：访问浏览器 UI 或启动 Electron 应用，在 demo 页面体验把一场实时对话转成区分说话人的转写、工作流结果、可检索的最终记录与全链路追踪的完整流程；仓库同时提供公开冒烟测试与 trace-context 审计。

适用人群

适合对数据主权与合规有硬性要求的组织——特别是政府、医疗、金融、法务等处理敏感语音、必须把对话留在自有基础设施内的团队，以及需要在气隙环境中部署语音转写的 MLOps 与平台工程师。对于希望从本地小规模起步、又能平滑扩展到云端或 K8s 集群的开发者，它提供了同一套栈贯穿始终的路径。

• 官方仓库：https://github.com/nanosamurai/nanosamurai
• 官方网站：https://nanosamur.ai