首页 产品 为什么选 OCTO 解决方案 文档 关于
文档中心 / 模块详解 / 语音转写
← 返回文档中心

语音转写

OCTO 文档中心 · 模块详解
  • Mininglamp-OSS/octo-speech 源码（Go STT/ASR微服务，全仓code search确认）
  • Mininglamp-OSS/octo-web 源码（TS/React，语音输入组件确认）
  • 内部部署仓库 docker-compose.yaml / Helm values.yaml
  • OCTO知识库建设组 / 2026-09-22 P1第一轮Q1产品管家源码级回答（topic_key: 2026-09-22:p1:round1-modules-deep）
  • 02-architecture/OCTO全组件服务清单.md（第六节）

语音Speech模块说明 v1.0

Speech（语音）模块提供语音转文字（ASR, Automatic Speech Recognition）能力，覆盖语音输入和语音消息转写两条独立链路。P1源码确认：纯STT/ASR服务，完全无TTS。 Profile开关`speech`，默认不启用，需开启speech profile；用户首次使用需opt-in（设置→语音设置确认协议）。

一、模块定位（一句话口径）

语音Speech = OCTO内置ASR语音转文字微服务：两条独立链路——①语音输入（Voice Input）：录音转文字填入输入框（全端支持），Web端额外支持选中文本录音替换（语音编辑）；②语音消息转写（Voice Message Transcription）：收到语音消息自动转文字，支持@mention识别、口语化书面语优化、情感emoji标注（VOICE_EMOTION_EMOJI=true默认开），转写结果对能看到消息的人可见。无TTS/实时流式转写/通话/字幕。 opt-in（首次需在设置→语音设置开启并确认协议）。

1.1 核心事实：完全无TTS ✅源码确认

  • README自述 "speech-to-text microservice / Multi-engine ASR"
  • 全仓搜索 tts/synthesize/text-to-speech = 0 命中
  • service层仅有 Transcribe（internal/service/transcribe.go）
  • 纯STT/ASR，无任何TTS方向
  • octo-web搜索 MessageContentTypeVoice = 0，Web端不支持发送type=4语音消息，仅做"录音→转文字填入输入框"

1.2 链路一：语音输入（Voice Input）

  • 功能：用户主动触发录音，语音转文字后填入输入框（用户可编辑后再发送）
  • 触发方式：
  • Web端：长按左Shift 300ms/500ms 或点击麦克风图标
  • 移动端（iOS/Android）：按住说话
  • 两种子模式：
  • 插入模式：转写文字插入光标位置
  • Web语音编辑：选中文本后录音，转写文字替换选中内容（Web端独有）
  • 端支持：全端支持（Web/iOS/Android）

1.3 链路二：语音消息转写（Voice Message Transcription）

  • 功能：收到语音消息后自动转写为文字
  • 转写结果可见范围：对能看到该消息的人可见（即消息可见范围内的人都能看到转写文字）
  • 额外能力：
  • @mention识别：语音中提到某人时，转写结果中正确识别为@mention
  • 口语化书面语优化：将口语化表达优化为更适合书面阅读的文字
  • 情感emoji标注（VOICE_EMOTION_EMOJI=true，默认开启）：识别语音情感并以emoji形式标注

1.4 opt-in与本地转写选项

  • 首次使用opt-in：需在设置→语音设置开启并确认协议
  • 本地转写可选（VOICE_LOCAL_ENABLED）：默认连接localhost:8787本地转写服务，失败时fallback云端
  • 降级链：本地(localhost:8787) → 后端API → 后端配置模型列表依次fallback

1.5 关键限制

  • 最大语音时长：60秒（VOICE_MAX_DURATION=60s）
  • 最大文件大小：3MB（VOICE_MAX_FILE_SIZE=3MB）
  • 最短时长：1秒

1.6 语音消息技术细节

  • 语音消息type=4，含url+duration字段
  • Web端不能录制发送语音消息(type=4)：octo-web搜索MessageContentTypeVoice=0，Web只做语音输入转文字（VoiceService.ts的transcribe()、useVoiceInput.ts、VoiceInputButton），docs-voice-host-compatibility.md明确"insert transcription via callback"

1.7 Bot联动

  • Bot收到语音消息自动转写为文字（Bot可直接处理转写后的文本）
  • Bot有语音纠错API：/v1/bot/voice/context管理人名、专有名词、术语（用于提升转写准确率）

二、部署与基础设施硬事实（来源：内部部署仓库配置）

2.1 octo-speech（语音ASR主服务）

项目 事实 来源
服务镜像 mininglamposs/octo-speech:latest（tag未pin） docker-compose / Helm
容器端口 8780 docker-compose
Profile speech docker-compose
数据库 MySQL octo_speech，用户speech（密码SPEECH_DB_PASSWORD可选） docker-compose env
默认语音引擎 Gemini（代码确证，VOICE_ENGINE部署默认值为qwen可能因部署配置差异） 产品管家+docker-compose
最大语音时长 60秒（VOICE_MAX_DURATION=60s） docker-compose env
最大文件大小 3MB（VOICE_MAX_FILE_SIZE=3MB） docker-compose env
本地转写 VOICE_LOCAL_ENABLED，默认localhost:8787 产品管家确认
情感emoji标注 VOICE_EMOTION_EMOJI=true（默认开启） 产品管家确认
存储卷 Helm 部署有PVC（pvc-speech.yaml）——持久化存储 Helm pvc
依赖 mysql（SPEECH_DB_PASSWORD非空时依赖） docker-compose depends_on
变量 默认值 说明 确认状态
SPEECH_DB_DSN — MySQL连接串（speech@octo_speech） ✅ 部署事实
VOICE_ENGINE qwen（部署默认） 语音引擎；代码确证支持3个云引擎(Gemini/GPT/Qwen)+可选本地ASR（见§2.1.1） ✅ P1源码确认
VOICE_MAX_DURATION 60s 最大语音时长 ✅ 部署事实+产品管家确认
VOICE_MAX_FILE_SIZE 3MB 最大音频文件大小 ✅ 部署事实+产品管家确认
VOICE_LOCAL_ENABLED — 本地转写开关（localhost:8787） ✅ 产品管家确认
VOICE_EMOTION_EMOJI true 情感emoji标注开关（默认开） ✅ 产品管家确认
SPEECH_API_KEY — 推断为内部鉴权key（无确证） ⚠️ 推断，待确认
2.1.1 转写引擎（3云引擎 + 1可选本地，源码确认）
引擎 模型列表 适用场景 备注
Gemini（默认） gemini-3.1-pro-preview / gemini-3-flash-preview / gemini-2.5-pro 通用转写 代码确认为默认引擎
GPT gpt-4o-mini-transcribe 仅语音输入append_only模式 不适用于语音消息转写
Qwen（通义千问） qwen3.5-omni-plus 通用转写 部署配置VOICE_ENGINE=qwen；独立配置VOICE_QWEN_URL/KEY
本地ASR（可选） localhost:8787 本地部署转写 需VOICE_LOCAL_ENABLED=true，默认关闭
  • 通用LiteLLM代理：VOICE_LITELLM_URL/VOICE_LITELLM_KEY
  • Qwen独立配置：VOICE_QWEN_URL/VOICE_QWEN_KEY
项目 事实 来源
调用地址 SPEECH_SERVICE_URL=http://octo-speech:8780 docker-compose env
API Key鉴权 SPEECH_API_KEY（octo-server→speech服务鉴权，推断为内部鉴权key，无确证） docker-compose env
路由端点 octo-server /api/v1/voice/transcribe 对接 SPEECH_SERVICE_URL octo-server 配置
Bot语音纠错API /v1/bot/voice/context（管理人名/专有名词/术语） 产品管家确认

2.2 octo-speech-admin（语音管理控制台：8781）

项目 事实 来源
服务镜像 mininglamposs/octo-speech-admin:latest（tag未pin） docker-compose / Helm
容器端口 8781 docker-compose
Profile speech docker-compose
宿主机端口 127.0.0.1:28088（loopback默认，SSH隧道访问） docker-compose
认证体系 独立账号体系（ADMIN_USERNAME/PASSWORD + JWT），与octo-server用户体系分离 docker-compose env
变量 说明
ADMIN_USERNAME 管理员用户名
ADMIN_PASSWORD 管理员密码
ADMIN_JWT_SECRET 管理台JWT签名密钥
2.2.1 speech-admin功能范围 ✅源码确认（cmd/admin/main.go全路由读取）
  • 登录
  • GET/POST /api/apps — 列出/创建应用
  • PUT /api/apps/:id/status — 启停应用
  • DELETE /api/apps/:id — 删除应用
  • POST /api/apps/:id/reset-key — 重置API Key
URL路径 后端 说明
/speech-admin/ speech-admin:8781 rewrite→:8781/，sub_filter替换静态资源路径前缀
/speech-admin-api/* speech-admin:8781 rewrite→:8781/api/*

2.3 音频存储与保留策略 ✅源码确认

  • app_registry — 应用注册 + API Key哈希
  • vocabulary_profile — 纠错词表（热词/专有名词）
  • local_asr_config — 本地ASR配置
  • audit_log — 管理操作审计日志
  • 默认保留 7天（defaultRetention=7，可配 ASR_LOG_RETENTION_DAYS）
  • cleaner.go 每小时清理过期日志
  • 默认关闭反馈日志（AllowFeedbackLog=false）
  • 用户主动删除自己语音数据的能力：未在源码中找到证据（S-05残留）

2.4 Helm部署额外配置

项目 说明
PVC pvc-speech.yaml——语音服务持久化存储卷，结合源码推断为本地ASR日志目录持久化（非MinIO，非模型文件）
Secret secret-speech.yaml——独立Secret管理语音服务凭据（API Key、LiteLLM Key等）

三、已确认能力（产品管家完整回答确认）

3.1 语音输入（Voice Input）—— 全端支持

  • 用户主动触发录音→ASR转文字→填入聊天输入框
  • 触发方式：Web长按左Shift(300ms/500ms)或麦克风图标；移动端按住说话
  • 两种子模式：插入光标位置 / Web语音编辑替换选中内容
  • 用户可在发送前编辑转写结果
  • 全端支持：Web、iOS、Android均可用

3.2 语音消息转写（Voice Message Transcription）

  • 收到语音消息时自动转写为文字（语音消息type=4，含url+duration）
  • 转写结果可见范围：对能看到消息的人可见
  • @mention识别：语音中提到的人名/用户在转写中识别为@mention
  • 口语化书面语优化：将口语表达转为更规范的书面语
  • 情感emoji标注：VOICE_EMOTION_EMOJI=true默认开启，以emoji标注语音情感

3.3 转写引擎（3云引擎+1本地，源码确认）

  • Gemini（默认）：gemini-3.1-pro-preview/3-flash-preview/2.5-pro
  • GPT：gpt-4o-mini-transcribe（仅语音输入append_only模式）
  • Qwen：qwen3.5-omni-plus
  • 本地ASR（可选）：localhost:8787，VOICE_LOCAL_ENABLED默认false
  • 降级策略：同引擎内多模型fallback（非跨引擎），callChatCompletionWithFallback/callGPTWithModelFallback
  • 配置：通用LiteLLM走VOICE_LITELLM_URL/KEY；Qwen独立走VOICE_QWEN_URL/KEY
  • ❌ Whisper/Azure/讯飞作为独立引擎——源码确认不存在
  • 有纠错词表（vocabulary_profile表）支持热词/专有名词优化

3.4 opt-in与本地转写

  • 首次使用需在设置→语音设置开启并确认协议
  • 支持本地转写（VOICE_LOCAL_ENABLED，localhost:8787），失败fallback云端

3.5 Bot联动

  • Bot收到语音消息自动转写为文字
  • Bot语音纠错API：/v1/bot/voice/context管理人名/专有名词/术语

3.6 关键限制

  • 最大时长60s，最大文件3MB，最短1s

3.7 明确不支持（源码确认）

  • TTS（文字转语音）：octo-speech全仓无tts/synthesize方向
  • Bot发送语音消息(type=4)：octo-web无发送type=4的UI/逻辑
  • Web端录制发送语音消息：仅语音输入转文字填入输入框，不直接发语音消息
  • 实时流式转写
  • 语音通话
  • 实时字幕/会议转写
  • speech-admin用量统计/引擎配置/热词管理/音频文件查看
  • 音频存MinIO/S3对象存储
  • Whisper/Azure/讯飞独立引擎

四、待确认项汇总

编号 待确认项 确认方式 优先级 安全敏感
S-01 用户能否删除自己的语音数据：音频仅落本地ASR日志目录(默认7天保留)，未找到用户主动删除能力的源码证据 产品管家补充/实测 P1 是（数据隐私/GDPR类）
  • ~~S-01 TTS能力~~ → ✅源码确认完全不存在
  • ~~S-03 speech-admin管理台功能~~ → ✅源码确认仅App+Key生命周期管理
  • ~~S-05 语音文件存储保留策略~~ → ✅源码确认：不进MinIO，仅本地日志目录，默认7天保留，cleaner每小时清理
  • ~~S-06 Web端能否录制发送语音消息~~ → ✅源码确认不能，仅语音输入转文字

五、与其他模块的关系

模块 关系 状态
octo-server octo-server通过SPEECH_SERVICE_URL调用speech服务；/api/v1/voice/transcribe端点；SPEECH_API_KEY鉴权；Bot语音纠错API /v1/bot/voice/context ✅ 部署事实+产品管家确认
IM/聊天 语音输入填入输入框（全端）；语音消息自动转写，转写结果对消息可见人可见 ✅ 产品管家确认
MySQL octo_speech库4张表：app_registry/vocabulary_profile/local_asr_config/audit_log（不存音频）；音频仅落本地ASR日志目录，默认7天保留 ✅ P1源码确认
speech-admin 独立管理控制台（/speech-admin/），独立认证体系；功能极窄：仅App+API Key生命周期管理（无用量统计/引擎配置/热词/音频查看），有audit_log ✅ P1源码确认（cmd/admin/main.go）
Gemini/GPT/Qwen/本地 3云引擎+1可选本地ASR；降级为同引擎内多模型fallback（非跨引擎）；LiteLLM/Qwen独立配置 ✅ P1源码确认
Bot API Bot收到语音消息自动转写为文字；Bot语音纠错API管理专有名词 ✅ 产品管家确认
Search 语音消息转写后的文字是否被搜索索引——合理推断应纳入消息搜索，但未确认 ⚠️ 推断，待确认
Summary 语音消息转写文字应可被Summary读取摘要，但具体链路待确认 ⚠️ 推断，待确认

六、版本记录

  • v0.1（2026-09-21）：基于内部部署仓库硬事实新建；功能描述全为配置推断待确认（已归档至99-archive/）
  • v0.2（2026-09-21）：产品管家Q1-Q3回答回填——①明确核心澄清"无TTS，仅ASR"（两条独立链路：语音输入+语音消息转写）；②语音输入确认全端支持+Web端语音编辑；③语音消息转写确认@mention识别/口语化书面语优化/情感标注；④明确不支持的场景（语音通话/实时转写/会议转写/TTS）；⑤部署硬事实完整保留并标注确认状态；⑥待确认项重排为统一编号表格（S-01~S-10），S-06数据保留策略标🔴安全敏感；⑦confidence更新为medium
  • v1.0（2026-09-22 07:30）：P1第一轮Q1源码级回答回填——①TTS完全不存在确认（octo-speech全仓code search=0，服务层仅有Transcribe）；②speech-admin功能极窄确认（cmd/admin/main.go路由全读：仅App+Key生命周期管理，无用量/引擎/热词/音频查看，有audit_log）；③音频存储确认（不进MinIO，仅本地ASR日志目录ASR_LOG_DIR，默认7天保留，cleaner每小时清理，AllowFeedbackLog默认false）；④MySQL octo_speech仅4表确认（app_registry/vocabulary_profile/local_asr_config/audit_log，不存音频）；⑤引擎精确确认（3云引擎Gemini/GPT/Qwen+可选本地ASR；降级为同引擎内多模型fallback非跨引擎；配置VOICE_LITELLM_*和VOICE_QWEN_*；Whisper/Azure/讯飞不存在）；⑥Web不能发语音消息(type=4)确认（MessageContentTypeVoice=0，仅语音输入转文字）；⑦关闭待确认项S-01/S-03/S-05/S-06，仅保留S-01(用户删除语音数据能力)；⑧confidence升至high，status升active
  • v0.3（2026-09-21）：基于完整产品管家回答（15:10细化版）回填——①纠正TTS表述：从"无TTS"改为"TTS待验证(P1)，不硬说有或没有"，整个voice模块代码全是ASR方向；②4种转写引擎代码确证：Gemini(默认)/GPT(仅语音输入append_only)/Qwen/本地，降级链确认，Whisper/Azure/讯飞未见记录；③转写结果可见性确认：对能看到消息的人可见；④情感标注细化：VOICE_EMOTION_EMOJI=true默认开启，以emoji形式标注；⑤opt-in流程确认：首次需在设置→语音设置开启并确认协议；⑥本地转写确认：VOICE_LOCAL_ENABLED，localhost:8787，失败fallback云端；⑦语音输入触发方式确认：Web长按左Shift300ms/500ms或麦克风图标，移动端按住说话；两种子模式（插入光标/Web语音编辑替换选中）；⑧Bot联动确认：Bot收语音自动转写+语音纠错API(/v1/bot/voice/context)；⑨语音消息type=4含url+duration确认；⑩最短1s限制补充；⑪speech-admin:8781 feature-map完全未收录确认；⑫SPEECH_API_KEY推断为内部鉴权key（无确证）；⑬待确认项表格更新（移除已确认项，保留真正待验证项S-01~S-09，重新编号）
← 返回文档中心