核心用法
gemini-stt 是一款基于 Google Gemini 大模型的语音转文字工具，通过命令行直接调用，无需安装外部 Python 依赖库。用户只需提供音频文件路径，脚本即可自动完成转录。支持两种认证模式：优先检测 Vertex AI 的应用默认凭证（ADC），若未配置则回退至环境变量 GEMINI_API_KEY。
核心命令示例：
python transcribe.py /path/to/audio.ogg python transcribe.py audio.mp3 --model gemini-2.5-pro python transcribe.py voice.m4a --vertex --project my-project
显著优点
- 零依赖部署：仅依赖 Python 3.10+ 标准库，无需 pip 安装任何包，大幅降低环境冲突风险。
- 智能认证切换：自动优先使用 Vertex AI ADC，实现企业级身份管理；个人用户可快速通过 API Key 接入。
- 多模型灵活选择：从极速的 Flash Lite 到高质量的 Pro 系列，覆盖从实时转录到高精度识别的全场景。
- 格式兼容性广：原生支持 Telegram 语音消息（.ogg/.opus）及主流音频格式（.mp3、.wav、.m4a）。
- 低门槛集成：可无缝嵌入 Clawdbot 等自动化工作流，直接处理入站语音消息。
潜在缺点与局限性
- 云端依赖：必须联网调用 Google API，离线场景不可用；存在网络延迟和 API 服务可用性风险。
- 隐私考量：音频数据需上传至 Google 服务器处理，敏感内容存在数据主权和合规风险。
- 成本累积：高频调用下 Gemini API 按 token 计费，Vertex AI 按请求计费，大规模使用需关注账单。
- 认证复杂度：Vertex AI 需预装 gcloud CLI 并配置项目，对非 GCP 用户存在学习成本。
- 无本地加速：不支持 GPU 本地推理，完全依赖云端算力，无法自定义模型微调。
适合人群
- 开发者与自动化工程师：需快速为 Bot、语音助手添加转录能力的构建者。
- 内容创作者与播客制作人：批量处理访谈录音、会议记录的文字稿生成。
- 企业 IT 管理员：已入驻 GCP 生态，希望利用 Vertex AI 统一管理 AI 服务凭证的团队。
- Clawdbot 用户：直接处理 Telegram 等平台的入站语音消息。
常规风险
| 风险类型 | 说明 | 缓解建议 |
|---------|------|---------|
| 认证泄露 | API Key 硬编码或误提交至版本控制 | 使用环境变量、密钥管理服务或 ADC |
| 成本失控 | 长音频或高频调用导致费用激增 | 设置预算告警、使用 Flash Lite 默认模型 |
| 数据泄露 | 敏感语音上传至第三方云端 | 评估数据分级，敏感场景选用本地化方案 |
| 服务中断 | Google API 限流或区域性故障 | 实现重试机制，准备备用转录服务 |
| 输出偏差 | AI 幻觉或特定口音识别错误 | 人工抽检关键内容，Pro 模型复核重要文件 |