picoclaw/pkg/audio/asr/README.zh.md

ASR（自动语音识别）

这个目录负责 PicoClaw 的语音转文字能力。

如果你是第一次配置 ASR，可以参考如下步骤：

1. 在 model_list 里添加一个或多个支持 ASR 的模型条目。
2. 用 voice.model_name 指向你想使用的那个条目。
3. 在 .security.yml 里配置对应的 API Key。

快速推荐

对于大多数新用户，建议先从下面两种开始：

提供商	示例模型	推荐理由
Groq	groq/whisper-large-v3-turbo	Whisper 风格转录速度快，并且提供 OpenAI 兼容接口，配置比较直接。Groq 目前官方提供2000请求每日的免费套餐。
ElevenLabs	elevenlabs/scribe_v1	上手简单，语音转文字质量也不错。ElevenLabs 目前官方免费套餐包含 STT 用量。

价格和免费额度可能会变化，正式使用前请以官网定价页为准。

ASR 配置是如何工作的

PicoClaw 不会把 ASR 的 API Key 放在 voice 配置里。

推荐的方式是：

• voice.model_name 用来选择 model_list 里的某个命名模型。
• model_list 条目描述真实的提供商和模型。
• .security.yml 负责保存该模型条目的 API Key。

这种方式更明确、更安全，也和 PicoClaw 其他模型配置方式保持一致。

推荐配置方式

方案 A：Groq Whisper

config.json

{
  "voice": {
    "model_name": "groq-asr",
    "echo_transcription": true
  },
  "model_list": [
    {
      "model_name": "groq-asr",
      "model": "groq/whisper-large-v3-turbo"
    }
  ]
}

.security.yml

model_list:
  groq-asr:
    api_keys:
      - "gsk_your_groq_key"

说明：

• 你可以不写 api_base，PicoClaw 会自动使用 Groq 默认接口地址。
• 如果你手动设置 Groq Whisper 的 api_base，下面两种写法都可以：
  • https://api.groq.com/openai/v1
  • https://api.groq.com/openai/v1/audio/transcriptions
• 只要是 OpenAI 兼容、并且模型名里包含 whisper 的模型，都可以走 Whisper 转录路径，不仅限于 whisper-large-v3-turbo。

方案 B：ElevenLabs

config.json

{
  "voice": {
    "model_name": "elevenlabs-asr",
    "echo_transcription": true
  },
  "model_list": [
    {
      "model_name": "elevenlabs-asr",
      "model": "elevenlabs/scribe_v1"
    }
  ]
}

.security.yml

model_list:
  elevenlabs-asr:
    api_keys:
      - "sk-elevenlabs-your-key"

方案 C：OpenAI Whisper

config.json

{
  "voice": {
    "model_name": "openai-asr"
  },
  "model_list": [
    {
      "model_name": "openai-asr",
      "model": "openai/whisper-1"
    }
  ]
}

.security.yml

model_list:
  openai-asr:
    api_keys:
      - "sk-openai-your-key"

其他支持 ASR 的模型类型

PicoClaw 目前主要支持三种 ASR 路径：

路径	示例模型	行为说明
ElevenLabs ASR	elevenlabs/scribe_v1	使用 ElevenLabs 的语音转录接口。
Whisper 接口模型	openai/whisper-1、groq/whisper-large-v3	使用 OpenAI 兼容的 /audio/transcriptions 接口。
支持音频的聊天模型 （重构中）	openai/gpt-4o-audio-preview、gemini/gemini-2.5-flash	把音频发给多模态聊天模型，并要求它返回转录结果。

如果你不确定该选哪种，建议优先使用 Groq Whisper 或 ElevenLabs。

PicoClaw 如何选择转录器

DetectTranscriber 会按下面顺序选择 ASR：

1. 首选路径：根据 voice.model_name 在 model_list 中找到对应模型。
2. 如果找到的模型属于以下类型：
   • elevenlabs/...，则使用 ElevenLabs transcriber。
   • OpenAI 兼容的 Whisper 模型，则使用 Whisper transcriber。
   • 支持音频输入的聊天模型，则使用 AudioModelTranscriber。
3. 回退路径：如果没有设置 voice.model_name，PicoClaw 会为了兼容旧配置，扫描 model_list 中可自动识别的 ASR 条目。

回退扫描只是为了兼容旧行为。新配置建议始终显式设置 voice.model_name。

常见错误

• 在 model_list 里定义了 ASR 模型，但忘了设置 voice.model_name。
• 把 API Key 写进了 voice，而不是 .security.yml。
• 选择了不支持 ASR 的模型，却期望得到 Whisper 风格的转录结果。
• 自定义了错误的 api_base，导致请求打到错误的接口地址。

最小检查清单

在测试语音输入前，请确认：

• voice.model_name 能正确匹配某个 model_list[].model_name。
• .security.yml 中对应条目已经配置了有效 API Key。
• 你选择的模型确实支持 ASR。
• 你当前使用的频道已经启用了语音输入能力。