STT Library Research

[TheShigure7]

STT 库调研与 AnyClaw 适配建议

1. 目标

本文档聚焦 Speech-to-Text，回答 4 个问题：

1. anyclaw1.2 当前的 STT 是怎么实现的。
2. 现成成熟方案有哪些。
3. 这些方案的典型使用方法是什么。
4. AnyClaw 哪些部分该保留自研，哪些部分可以收缩或替换。

---

2. AnyClaw1.2 当前现状

anyclaw1.2 当前 STT 主要位于：

• anyclaw1.2/anyclaw/pkg/speech/stt_provider.go
• anyclaw1.2/anyclaw/pkg/speech/stt_manager.go
• anyclaw1.2/anyclaw/pkg/speech/stt_whisper.go
• anyclaw1.2/anyclaw/pkg/speech/stt_google.go
• anyclaw1.2/anyclaw/pkg/speech/stt_whispercpp.go
• anyclaw1.2/anyclaw/pkg/gateway/gateway_speech_stt.go

从代码结构看，当前做法不是简单“调用一个现成 SDK”：

• 自己定义了 provider 抽象
• 自己实现了 manager
• 自己实现了 pipeline / integration
• 自己写了 OpenAI 和 Google 的 HTTP 调用层
• 本地 whisper.cpp 也包了一层进程执行器

这意味着：

• 不是自己造了 STT 模型
• 但确实自己造了一套 多供应商接入层 + 编排层

---

3. 方案一：OpenAI Speech-to-Text

3.1 定位

OpenAI 官方已经提供成熟的 Speech-to-Text 能力，适合：

• 文件转写
• 流式转写
• 实时转写
• 与语音 Agent 联动

3.2 官方能力形态

官方资料明确给出几种典型方式：

1. 文件上传，阻塞式转写
2. 文件上传，流式返回结果
3. Realtime WebSocket / WebRTC 实时转写
4. Agents SDK VoicePipeline

这说明如果团队目标只是接入 OpenAI 转写，底层并不需要自己再造一层复杂客户端。

3.3 典型使用方法

Python 文件转写：

from openai import OpenAI

client = OpenAI()

with open("speech.mp3", "rb") as f:
    transcript = client.audio.transcriptions.create(
        file=f,
        model="gpt-4o-transcribe",
        response_format="text",
    )

print(transcript)

文件流式转写：

from openai import OpenAI

client = OpenAI()

with open("speech.mp3", "rb") as f:
    stream = client.audio.transcriptions.create(
        file=f,
        model="gpt-4o-transcribe",
        response_format="text",
        stream=True,
    )

for event in stream:
    print(event)

实时转写则走 Realtime transcription session，通过 WebSockets 或 WebRTC 建立转写会话。

3.4 对 AnyClaw 的意义

AnyClaw 当前 stt_whisper.go 是手写 multipart 和 endpoint 的方式，这种写法能工作，但维护上会重复承担：

• 请求封装
• 错误解析
• 兼容性维护

如果未来主要支持 OpenAI，建议：

• 保留 AnyClaw 的 provider manager / pipeline / gateway wiring
• 尽量减少手写 API 客户端细节

3.5 优缺点

优点：

• 官方能力成熟
• 支持文件、流式、实时多场景
• 与后续语音 Agent 路线一致

缺点：

• 依赖云端
• 成本可变
• 对网络质量敏感

3.6 参考资料

• Speech-to-text guide: https://platform.openai.com/docs/guides/speech-to-text
• Realtime transcription: https://developers.openai.com/api/docs/guides/realtime-transcription
• Cookbook: https://cookbook.openai.com/examples/speech_transcription_methods

---

4. 方案二：Google Cloud Speech-to-Text

4.1 定位

Google Cloud Speech-to-Text 是成熟云转写方案，适合：

• 企业级云语音识别
• 批量文件转写
• 流式转写
• 需要官方 Go client 的场景

4.2 核心特点

Google 不只是提供 REST API，还提供官方客户端库，包括 Go client。

这点和 AnyClaw 当前 stt_google.go 的手写 REST 调用形成鲜明对比。

4.3 典型使用方法

安装 Go client：

go get cloud.google.com/go/speech

创建客户端：

ctx := context.Background()
client, err := speech.NewClient(ctx)
if err != nil {
    // handle error
}
defer client.Close()

在 Google Cloud 文档里，Speech-to-Text client library 用于直接构造识别请求，而不是自己手写 JSON 和 HTTP 请求。

另外，流式识别还支持：

• enable_voice_activity_events
• SPEECH_ACTIVITY_BEGIN
• SPEECH_ACTIVITY_END

4.4 对 AnyClaw 的意义

如果 AnyClaw 要继续保留 Google STT 支持，更建议：

• 上层继续保留 provider 抽象
• 下层优先切官方 Go client

这样可以减少：

• 手写 REST 细节
• 自己维护协议字段
• 自己维护兼容性

4.5 优缺点

优点：

• 官方 Go client 完整
• 支持云端流式识别
• 支持语音活动事件

缺点：

• 依赖 Google Cloud
• 配置和认证相对更重
• 不适合纯离线本地场景

4.6 参考资料

• Go client libraries: https://cloud.google.com/speech-to-text/docs/client-libraries
• Quickstart with client libraries: https://cloud.google.com/speech-to-text/v2/docs/transcribe-client-libraries
• Voice activity events: https://cloud.google.com/speech-to-text/docs/voice-activity-events

---

5. 方案三：whisper.cpp

5.1 定位

whisper.cpp 是最成熟的本地离线 Whisper 运行方案之一，适合：

• 本地离线转写
• 边缘设备
• 隐私要求高
• 不想依赖云服务

5.2 核心特点

官方仓库强调：

• C/C++ 实现
• 支持 CPU-only
• 支持多种硬件加速
• 支持量化模型
• 适合作为本地 ASR 引擎

5.3 典型使用方法

官方 quick start：

git clone https://github.com/ggml-org/whisper.cpp.git
cd whisper.cpp
sh ./models/download-ggml-model.sh base.en
cmake -B build
cmake --build build -j --config Release

然后使用 whisper-cli 转写音频文件。

AnyClaw 当前的接法本质上就是这条路线：

1. 准备模型文件
2. 通过 binaryPath 定位本地可执行文件
3. 把音频写成临时文件
4. exec 调起 whisper.cpp
5. 解析文本或 JSON 输出

5.4 对 AnyClaw 的意义

和 OpenAI / Google 不同，whisper.cpp 本来就是一个本地二进制/库路线，所以 AnyClaw 外面包一层 Go 封装是合理的。

这一块更像：

• 不是重复造轮子
• 而是给成熟本地引擎写集成层

5.5 优缺点

优点：

• 本地离线
• 数据不出本机
• 成本稳定
• 适合私有化环境

缺点：

• 要管理模型文件
• CPU/GPU 资源占用明显
• 识别能力依赖本地硬件

5.6 参考资料

• whisper.cpp GitHub: https://github.com/ggml-org/whisper.cpp

---

6. 对比总结

方案	类型	延迟	本地/云端	接入复杂度	适合 AnyClaw 的场景
OpenAI STT	官方云 API	低到中	云端	中	OpenAI 语音 Agent 路线
Google Cloud STT	官方云 API + Go client	低到中	云端	中	企业级云识别与流式识别
whisper.cpp	本地离线引擎	中	本地	中	隐私优先、离线场景
当前自研上层编排	自研 orchestration	取决于底座	混合	已有	多供应商统一接入

---

7. AnyClaw 哪些该保留自研，哪些可收缩

7.1 建议保留自研的部分

这些更接近 AnyClaw 的平台价值：

• provider 抽象
• manager
• pipeline
• integration
• gateway wiring
• 与任务、会话、路由、审批的结合

7.2 建议收缩的部分

这些更像通用接入细节：

• OpenAI 底层 HTTP 手写客户端
• Google 底层 REST 手写客户端
• 对单一供应商字段的重复封装

如果项目未来会长期维护语音能力，建议尽量：

• 对 OpenAI 走官方支持方式
• 对 Google 优先走官方 Go client

7.3 whisper.cpp 的例外

whisper.cpp 不属于“手写云 API 客户端”范畴，它本身就是本地引擎，因此 AnyClaw 写一层本地集成封装是合理的。

---

8. 对 AnyClaw 的建议

8.1 短期建议

短期最实用的做法：

• 保留现有 STT 上层架构
• 不急着重写 manager / pipeline
• 优先梳理 OpenAI / Google 底层客户端是否要收缩

8.2 中期建议

中期建议形成“三轨制”：

1. OpenAI STT
   • 面向语音 Agent、实时体验
2. Google Cloud STT
   • 面向企业云识别与流式场景
3. whisper.cpp
   • 面向离线、本地、私有化

上层统一用 AnyClaw 的 provider 抽象屏蔽差异。

8.3 结构建议

建议把 STT 层分为两层：

• 底层引擎层
  • OpenAI
  • Google
  • whisper.cpp
• 平台编排层
  • provider manager
  • pipeline
  • routing / session / task integration

这样更清楚地区分：

• 哪些是“可替换底座”
• 哪些是“AnyClaw 的平台价值”

---

9. 最终结论

对 anyclaw1.2 来说：

• OpenAI STT 和 Google Cloud STT 本来就有成熟官方能力。
• 当前项目主要是自己造了统一接入层和底层 HTTP 适配层。
• whisper.cpp 则更像是合理地复用成熟本地引擎，并在外部包了一层 AnyClaw 集成。

一句话总结：

AnyClaw 的 STT 不是“自己造模型”，而是“在成熟服务和成熟本地引擎之上，自建了一套多供应商接入与编排层”；其中最值得收缩的是云厂商底层客户端细节，最值得保留的是平台级编排能力。