本地语音提供商
在 Kaiwu 中配置本地语音，支持设备、自托管、Google 及本地神经网络 STT/TTS 提供商。
本地语音是 Kaiwu 的可配置语音流水线。
你可以自由组合搭配以下功能：
- 语音转文字（STT）
- 文字转语音（TTS）
- 直通会话或语音智能体对话流
前往设置 → 语音 → 本地语音即可进行配置。
本地语音支持的功能
STT 提供商
你可以选择以下任一语音转文字提供商：
- 设备 STT：使用设备系统自带的平台语音识别
- OpenAI 兼容 STT：接入自定义的
/v1/audio/transcriptions端点 - Google Gemini (audio)：使用 Google Gemini 音频转录
- 本地神经 STT：在原生客户端上运行的端侧 Sherpa 流式 STT
TTS 提供商
你可以选择以下任一文字转语音提供商：
- 设备 TTS：使用设备系统自带的平台文字转语音
- OpenAI 兼容 TTS：接入自定义的
/v1/audio/speech端点 - Google Cloud Text-to-Speech
- 本地神经 TTS：支持 Web 端与原生客户端的 Kokoro
你可以自由混用不同的提供商，例如：
- 设备 STT + 设备 TTS
- 设备 STT + Kokoro TTS
- OpenAI 兼容 STT + Google Cloud TTS
- Gemini STT + Kokoro TTS
对话模式
本地语音支持两种对话模式。
直通会话
在直通会话模式下，语音转写后的文本会直接发送到当前活跃的会话中。
适用于以下需求：
- 类似听写的输入体验
- 会话内简单的语音输入
- 追求简单直观、减少中间处理环节
在此模式下依然可以启用 TTS，由 Kaiwu 朗读回复内容。
智能体
在智能体模式下，语音输入会先交由专属的语音智能体处理。
当你希望语音交互层具备以下能力时，可以使用此模式：
- 进行追问
- 执行操作前先总结要点
- 执行结构化操作
- 避免将每一句话都写入目标会话
如果你希望语音交互像与同事沟通一样自然，而不仅仅充当听写工具，该模式会非常实用。
语音智能体后端
在本地语音智能体模式下，语音智能体后端决定了实际运行智能体的运行时：
- 守护进程语音智能体：使用基于 Kaiwu 守护进程的语音智能体运行时
- OpenAI 兼容语音智能体：直接调用配置的 chat-completions 端点
若需要最紧密的 Kaiwu 集成体验（包括下文介绍的工作目录和瞬移行为），建议使用守护进程后端。
运行设备选择
对于基于守护进程的本地语音智能体模式，你可以选择语音智能体的运行位置：
- 自动：自动选择一台稳定的设备
- 固定设备：始终使用你指定的设备
“自动”模式的工作机制
“自动”并不意味着“随最新活跃的设备随时切换”。
该模式的核心目标是稳定性：
- Kaiwu 在启动语音智能体时会自动解析并选定一台设备
- 运行中的语音智能体会固定在该设备上，不会因活跃会话的切换而频繁漂移
这样可以避免在应用内切换时产生不必要的停止与重启开销。
如果需要明确可预期的运行位置，请改用固定设备。
语音主目录与会话项目根目录
基于守护进程的本地语音智能体模式支持两种工作目录：
语音主目录
这是一个稳定的非项目目录，供全局或侧边栏发起的语音会话使用。
当你希望语音智能体拥有中立的工作区，而不是自动在某个项目内部启动时，可以使用此目录。
会话项目根目录
直接从某个会话中启动语音时，Kaiwu 可以在该会话的项目根目录下启动语音智能体。
当你希望语音智能体像当前项目中的编程同事一样协同工作时，可以使用此目录。
停留在语音主目录
启用停留在语音主目录后，语音智能体将始终保持在语音主目录中。
这意味着：
- 从会话发起的语音不会在该会话的项目根目录下启动
- 禁止瞬移到会话根目录
当你需要更安全、更中立的默认工作目录时，建议启用此选项。
瞬移至当前会话
对于基于守护进程的本地语音智能体会话，会话语音界面会提供瞬移操作。
瞬移功能允许你将正在运行的语音智能体迁移到当前会话的项目根目录。
重要规则：
- 瞬移仅支持守护进程后端
- 关闭允许瞬移时，该操作将被隐藏或阻止
- 开启停留在语音主目录时，该操作将被隐藏或阻止
- 运行时不满足条件时，将默认失败并阻止操作
当你最初从语音主目录全局启动，后续又希望智能体深入探查当前项目时，这个功能非常实用。
根目录预热
本地语音智能体既可以只维护单个工作根目录运行时，也可以保持多个根目录处于预热状态：
- 单一根目录：仅保持一个根目录处于活跃状态
- 保持预热：保留最近使用过的多个根目录，以便快速切回或恢复
使用保持预热时，你可以设置最多保留的预热根目录数量。
追求极简行为时建议选择单一根目录；若经常在少数几个项目之间往返切换，且需要更快的复用速度，建议选择保持预热。
持久化与恢复能力
语音智能体模式将两项相关配置解耦分开：
会话记录持久化
- 临时：语音智能体的会话记录状态为临时保存
- 持久化：在应用重新加载或重启后，依然保留语音智能体的对话状态
恢复模式
启用持久化后，你可以选择智能体的恢复方式：
- 重放：根据保存的会话记录或重放输入重建上下文
- 提供商原生恢复：在支持的情况下，使用提供商原生的恢复机制
提供商原生恢复取决于具体能力支持。若当前后端与智能体的组合不支持该特性，Kaiwu 会将其禁用，而不是假装可以正常工作。
你还可以开启回退到重放，这样当提供商原生恢复在实际场景中不可用时，系统仍可通过重放机制恢复状态。
智能体来源与模型来源
本地语音智能体模式还将以下两项设置解耦：
智能体来源
- 跟随会话：复用当前会话的智能体与后端上下文
- 固定智能体：指定特定的语音智能体后端或提供商
模型来源
针对对话和提交行为，模型选择可以来自：
- 当前会话
- 对话模型
- 自定义选定的模型
当后端支持动态模型列表时，Kaiwu 会在下拉菜单中直接展示该实时列表，无需手动输入文本。
本地语音通用设置
首选 STT 与 TTS 提供商
通过 STT 提供商和 TTS 提供商下拉菜单，为当前的本地语音配置指定语音后端。
测试 TTS
点击测试 TTS可以端到端验证当前选中的 TTS 提供商是否正常工作。
该项主要用于测试以下提供商的音频输出：
- 设备 TTS
- OpenAI 兼容 TTS
- Google Cloud TTS
- Kokoro 本地神经 TTS
自动朗读回复
启用后，Kaiwu 会在一轮对话完成时自动朗读回复内容。
插话打断（Barge-in）
启用后，开启新一轮发言可直接打断当前正在播放的语音，无需等待上一条语音回复播放完毕。
网络超时
通过网络超时设置 Kaiwu 在判定失败前等待 STT 或 TTS 网络操作的最长时间。
在以下场景中该配置尤为关键：
- 自托管的 OpenAI 兼容端点
- Google Gemini STT
- Google Cloud TTS
设备 STT 与设备 TTS
如果希望配置尽可能简单，且无需额外部署服务器，推荐使用设备自带的提供商。
设备 STT
设备 STT 会在支持的平台上直接使用内置的系统语音识别。
选中设备 STT 时，Kaiwu 还可提供免提控制选项，例如：
- 静音超时
- 最小语音时长
这些设置项决定了何时判定一轮语音说话已经结束。
设备 TTS
设备 TTS 使用操作系统自带的语音合成引擎。
这是使用成本最低的方案，但音频质量和可选音色取决于具体的系统平台。
OpenAI 兼容 STT 与 TTS
如果你已经部署了 OpenAI 风格的语音端点服务，可以使用这些提供商。
STT
OpenAI 兼容 STT 要求满足以下格式：
POST /v1/audio/transcriptions
支持配置的项目包括：
- Base URL
- API 密钥
- 模型
TTS
OpenAI 兼容 TTS 要求满足以下格式：
POST /v1/audio/speech
支持配置的项目包括：
- Base URL
- API 密钥
- 模型
- 音色
- 输出格式（
mp3或wav）
该方案非常适合搭配遵循 OpenAI API 规范的自托管语音服务器。
Google 提供商
Google Gemini STT
本地语音支持接入 Google Gemini STT 作为 STT 提供商。
支持配置的项目包括：
- API 密钥
- 模型
- 可选的语言提示
若希望在不改动本地语音其他流水线的前提下获得 Google 水准的转录质量，可以选择此方案。
Google Cloud TTS
本地语音支持接入 Google Cloud Text-to-Speech 作为 TTS 提供商。
支持配置的项目包括：
- API 密钥
- 可选的 Android 证书 SHA-1
- 语言
- 音色
- 输出格式
- 语速
- 音调
Google Cloud 音色选择器支持搜索，可供选择当前 API 密钥及所选语言支持的所有音色。
本地神经 TTS：Kokoro
Kaiwu 的本地神经 TTS 目前基于 Kokoro 实现。
Web 端与桌面 Web 端
在 Web 端，Kokoro 通过 Web 运行时运行，并按需下载所需资源。
支持配置的项目包括：
- Kokoro 模型包
- 下载 / 准备模型
- 清理浏览器缓存
- 音色
- 语速
首次下载成功后，浏览器会缓存模型文件，后续对话无需重复获取。
原生客户端
在原生版本中，Kokoro 使用可独立下载的原生模型包。
支持配置的项目包括：
- Kokoro 模型包
- 下载模型
- 删除已下载资源
- 检查更新
- 音色
- 语速
模型按需下载，后续可随时删除以释放存储空间。
音色试听
Kokoro 音色下拉菜单内置了试听播放功能，可以在确认选择前先试听效果。
本地神经 STT：Sherpa 流式 STT
在原生版本中，本地神经 STT 使用可独立下载的 Sherpa 流式 STT 模型包。
支持配置的项目包括：
- 模型包
- 下载模型
- 删除已下载资源
- 检查更新
- 语言提示
这为本地语音提供了一套完全在端侧运行的 STT 方案，无需依赖外部服务器。
模型下载、更新与存储
Kokoro 原生 TTS 模型包与 Sherpa 原生 STT 模型包均基于 Kaiwu 的模型清单文件按需下载。
用户可以在设置中执行以下操作：
- 下载缺失的模型包
- 查看下载进度
- 中止正在进行的下载
- 检查是否有更新版本的模型包
- 删除已下载资源以释放存储空间
在 Web 端，Kokoro 运行时文件保存在浏览器缓存中；在原生客户端上，模型包则保存在本地设备存储中。
推荐配置方案
极简全本地配置
- STT：设备 STT
- TTS：设备 TTS
- 对话模式：直通会话
兼顾输出品质与极简部署的方案
- STT：设备 STT
- TTS：本地神经 TTS（Kokoro）
- 对话模式：智能体
全自托管语音栈
- STT：OpenAI 兼容 STT
- TTS：OpenAI 兼容 TTS
- 对话模式：智能体
云端与本地混合方案
- STT：Google Gemini STT
- TTS：Kokoro 或 Google Cloud TTS
- 对话模式：智能体
网络注意事项
移动端与 localhost
在手机上，localhost 和 127.0.0.1 通常指向手机本身，而不是你的电脑。
如果语音服务器运行在电脑上，请使用：
- 电脑的局域网 IP，或
- 穿透隧道
Web 端与跨域资源共享（CORS）
对于 Web 端，STT 或 TTS 服务器可能需要正确配置 CORS。
将服务暴露至局域网外
若要将语音服务器暴露到本地局域网之外，请务必配置完善的身份认证并启用 HTTPS。
常见问题排查
本地语音能接收输入，但没有语音播报
请检查：
- 是否已选择 TTS 提供商
- 若需要自动播放，是否已开启自动朗读回复
- 测试 TTS 是否能正常发声
Kokoro 不可用
请检查：
- 当前平台是否支持该运行时
- 模型是否已成功下载
- 所选 Kokoro 模型包是否处于就绪状态
Sherpa STT 不可用
请检查：
- 是否运行在原生客户端上
- Sherpa 模型包是否已经下载
- 所选语言或模型包是否与使用场景相符
目标会话中没有写入任何内容
若当前处于智能体模式，这是正常现象。语音智能体并不需要把每句话都写入目标会话，它可以将部分交互保留在内部语音对话中，仅在必要时才将明确的操作回传至目标会话。