ODS本地STT实战：Whisper语音识别私有化部署完整指南

【免费下载链接】ODS Turn your PC, Mac, or Linux box into an AI server. LLM inference, chat UI, voice, agents, workflows, RAG, and image generation. 项目地址: https://gitcode.com/GitHub_Trending/dr/ODS

ODS（Osmantic Deployment System）是一个把你的 PC、Mac 或 Linux 电脑变成私有 AI 服务器的开源系统，内置的 Whisper 本地 STT（语音转文字） 服务让你在家就能完成语音识别私有化部署——音频全程不出你的设备，无需云端、无需订阅、零月费。本文带你从安装到调通，完整记录这次实战。

为什么选择本地STT：语音数据永远不离开你的电脑 🎙️

用云端语音 API 的最大隐患是：你说的话必须先上传到别人的服务器。开会录音、语音备忘、家庭语音助手……这些数据一旦上云，隐私边界就不在自己手里了。

ODS 的解法是把 Whisper 直接跑在本地 Docker 容器里：

• 全程私有：麦克风录到的音频在本机完成转写，网络隔离下也能工作
• OpenAI 兼容 API：提供 POST /v1/audio/transcriptions 接口，任何支持 OpenAI 音频接口的应用都能直接对接
• 对话场景优化：容器启动时自动应用一套 VAD（语音活动检测）调优补丁，静音切分参数针对口语对话打磨过
• 与生态联动：Open WebUI 的语音输入、n8n 工作流都开箱可用

一句话概括 ODS 里的分工：Whisper 负责"听"，把语音变成文字；TTS 服务负责"说"，把 AI 的回答读出来。两者跑起来就是一个完整的本地语音对话闭环。

50秒看懂：ODS的Whisper是怎么跑起来的

整个服务由一个 Docker 容器组成，关键文件都在服务目录 ods/extensions/services/whisper/ 下：

文件	作用
compose.yaml	服务定义：端口 9000、内存上限 4G、健康检查
compose.nvidia.yaml	NVIDIA GPU 加速覆盖层，自动预留 1 张显卡
manifest.yaml	服务元数据，声明 voice 功能依赖 whisper + tts
docker-entrypoint.sh	启动脚本：先打 VAD 补丁，再拉起 speaches 服务
README.md	服务完整文档，含 API 示例与排障清单

底层引擎是高性能 Whisper 服务器 speaches，模型按需从 HuggingFace 下载并缓存在 data/whisper/ 目录，24 小时不用的模型会自动卸载（WHISPER__TTL=86400），不白占内存。

一键安装步骤：3步启动私有语音识别

第 1 步：安装 ODS（前提是有 Docker）

# Linux / macOS
curl -fsSL https://install.osmantic.com/ods.sh | bash

安装器会根据你的硬件自动选择模型并完成预下载，全程无需手动配置。

第 2 步：确认 whisper 服务在运行

docker compose ps whisper      # 看容器状态
curl http://localhost:9000/health   # 健康检查

第 3 步：发起第一次转写

curl http://localhost:9000/v1/audio/transcriptions \
  -F "file=@audio.wav" \
  -F "model=Systran/faster-whisper-base"

返回 JSON 里就是你的录音文本。也可以在浏览器打开 http://localhost:3000 的 Open WebUI，直接用麦克风语音输入——它会自动走本地 Whisper，不用改任何设置。

Whisper模型怎么选：base与turbo两档就够了

模型通过 .env 里的 AUDIO_STT_MODEL 变量控制，安装时已按硬件选好默认值：

硬件环境	默认模型	体积	特点
NVIDIA 显卡	deepdml/faster-whisper-large-v3-turbo-ct2	约 1.5GB	精度最高，GPU 加速飞快
macOS / AMD / 纯 CPU	Systran/faster-whisper-base	约 130MB	轻量快速，CPU 也能实时转

选型建议：普通会议记录、英文+普通话场景，base 完全够用；如果你要转写方言、专业术语或长访谈，换更大的模型——改完 AUDIO_STT_MODEL 后重新安装，或手动执行预下载命令（详见 whisper/README.md 的 Recovery 一节）。

进阶玩法：把本地STT接进自动化工作流

因为接口和 OpenAI 完全兼容，本地 STT 可以无缝嵌入各类自动化场景。ODS 自带了一套 n8n 工作流模板，语音转写模板见 03-voice-transcription.json，配套的还有语音备忘、Whisper转笔记等场景，导入即用。

配合 TTS 服务（extensions/services/tts/），你还可以搭建"说完话→本地转文字→AI 思考→本地读出来"的完整语音助手，全程零云端。整个语音链路的设计思路可以阅读官方友好指南 HOW-ODS-SERVER-WORKS.md。

常见问题快速排障清单 ✅

现象	快速解决
转写返回 404 "Model is not installed locally"	speaches 不会在转写时自动下载模型，按 README 的恢复命令手动 POST /v1/models/<模型ID> 预下载即可
容器起不来 / 转写报错	docker compose logs whisper 看日志，检查磁盘剩余空间是否够下载模型
转写质量差	请求里把 model 换更大的档位，如 Systran/faster-whisper-small
端口冲突	.env 里改 WHISPER_PORT（默认 9000）
Open WebUI 没走本地 Whisper	确认 open-webui 环境变量中 AUDIO_STT_ENGINE=openai 且 API 地址指向 whisper:8000/v1

更多排障细节见服务文档 whisper/README.md 和总排障手册 TROUBLESHOOTING.md。

总结：本地Whisper部署比想象中更简单

回看这次实战，核心收益只有一条：语音数据从麦克风到文字，全程留在你自己的硬件上。而 ODS 把原本需要自己拼装容器、调 VAD 参数、管模型缓存的繁琐工作，压缩成了一条安装命令：

• 5 分钟内完成 Whisper STT 私有化部署
• OpenAI 兼容 API，现有应用零改造接入
• CPU 和 GPU 双后端，130MB 到 1.5GB 多档模型自由选
• 与 Open WebUI、n8n、TTS 组成完整本地语音生态

想深入定制，建议直接翻这三个文件：服务入口 docker-entrypoint.sh、服务定义 compose.yaml、功能声明 manifest.yaml。祝你的语音数据从此只为你自己服务 🎧

【免费下载链接】ODS Turn your PC, Mac, or Linux box into an AI server. LLM inference, chat UI, voice, agents, workflows, RAG, and image generation. 项目地址: https://gitcode.com/GitHub_Trending/dr/ODS