1. Free-Claude-Code 语音转录到底解决什么问题Free-Claude-Code 是一个把 Claude Code CLI 的流式输出适配到第三方模型提供商的开源中间件同时提供 Discord 和 Telegram 两个 IM 前端。你在聊天软件里发一条语音Bot 把它转成文字再送进 Claude Code 处理最后把结果回给你——这就是语音转录子系统要干的事。它要解决的核心矛盾有三个。第一是平台差异Discord 发的是 .ogg/.mp4/.wav 附件Telegram 发的是 voice 对象默认 OGG格式和下载 API 完全不同。第二是阻塞风险Whisper 本地推理是 CPU/GPU 密集型一条 30 秒音频在 CPU 上可能跑 3 到 10 秒如果直接在 asyncio 事件循环里调用整个 Bot 会卡死期间收不到任何消息。第三是后端选择有人有 NVIDIA 显卡想跑本地 CUDA有人只有 CPU 想跑轻量模型有人干脆想用云端 API 省事。适合谁看正在做语音交互 Bot 的后端开发者或者想把语音转录能力接进自己 IM 工作流的人。你需要有基本的 Python asyncio 概念知道什么是事件循环剩下的配置和代码我都会给全。我试过在只有 4 核 CPU 的云主机上跑 base 模型单条 20 秒语音大约 4 秒出结果配合转录中…的状态消息体验可以接受。下面从架构到配置一步步拆。2. TaoToken 统一 Key 管理两类 ASR 后端凭据语音转录链路里其实有两类凭据要管一类是本地 Whisper 下载模型时可能用到的 HuggingFace TokenHF_TOKEN另一类是 NVIDIA NIM 云端 ASR 的 API Key。再加上 Claude Code 本身调用大模型需要的 Key一个项目里散落着三四种凭据切换环境时很容易搞混。TaoToken 在这里的价值是把大模型调用这一层的凭据统一起来。它的 API 地址是 https://taotoken.net/api兼容 OpenAI 风格的接口你用一个 Key 就能访问多种模型。对于 Free-Claude-Code 这种需要把 Claude Code 输出适配到第三方提供商的场景统一 Key 意味着你换模型时不用改一堆环境变量。具体怎么接Free-Claude-Code 的大模型配置走的是 MODEL 和对应的 API Key 环境变量。你可以把 TaoToken 作为模型提供商接进去Base URL 填 https://taotoken.net/apiKey 填你在控制台生成的令牌Model ID 填你要用的模型标识。这样 Claude Code 的请求会经过 TaoToken 转发到目标模型。需要说明的是TaoToken 管的是大模型调用凭据本地 Whisper 的模型下载和 NVIDIA NIM 的 ASR Key 是另外两条独立的凭据链。三者不要混在一起配否则排障时你会分不清是哪个环节出的问题。我的建议是在 .env 里用注释把三段配置明确分开大模型段、本地 Whisper 段、NIM ASR 段。如果你还没生成 Key可以去控制台创建https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentconsole 。生成后先别急着填把下面的配置模板过一遍再动手。对于长期跑编码 Agent 的场景Coding Plan 会比按量计费更划算适合把 Free-Claude-Code 当日常工具用的开发者https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcoding-plan 。3. 可复制的双后端切换配置与环境变量清单这一节给你能直接抄的配置。Free-Claude-Code 的语音后端通过 WHISPER_DEVICE 路由三个取值cpu、cuda、nvidia_nim。前两个走本地 transformers 管道第三个走 NVIDIA Riva gRPC。先看 .env 的完整模板我把三段凭据分开写# 平台选择 MESSAGING_PLATFORMdiscord # Discord 配置 DISCORD_BOT_TOKENyour-discord-bot-token ALLOWED_DISCORD_CHANNELS123456789012345678 # 语音转录开关 VOICE_NOTE_ENABLEDtrue # 方案 A本地 CPU 推理 WHISPER_DEVICEcpu WHISPER_MODELbase HF_TOKEN # 方案 B本地 CUDA 推理 # WHISPER_DEVICEcuda # WHISPER_MODELlarge-v3 # HF_TOKENhf_xxxxxxxx # 方案 CNVIDIA NIM 云端 ASR # WHISPER_DEVICEnvidia_nim # WHISPER_MODELopenai/whisper-large-v3 # NVIDIA_NIM_API_KEYnvapi-xxxxxxxx # 大模型配置走 TaoToken 统一 Key MODELyour-model-id OPENAI_BASE_URLhttps://taotoken.net/api OPENAI_API_KEYsk-your-taotoken-key模型短名到 HuggingFace ID 的映射在源码里是固定的你填短名就行_MODEL_MAP { tiny: openai/whisper-tiny, base: openai/whisper-base, small: openai/whisper-small, medium: openai/whisper-medium, large-v2: openai/whisper-large-v2, large-v3: openai/whisper-large-v3, large-v3-turbo: openai/whisper-large-v3-turbo, }NVIDIA NIM 的 ASR 模型映射则是另一套它把模型 ID 映射到 function_id 和语言代码_NIM_ASR_MODEL_MAP { nvidia/parakeet-ctc-0.6b-zh-cn: (9add5ef7-322e-47e0-ad7a-5653fb8d259b, zh-CN), nvidia/parakeet-ctc-1.1b-asr: (1598d209-5e27-4d3c-8079-4751568b1081, en-US), openai/whisper-large-v3: (b702f636-f60c-4a3d-a6f4-f3568c13bd7d, multi), }如果你用 uv 管理依赖pyproject.toml 里的可选依赖要选对[project.optional-dependencies] voice_local [torch, transformers, librosa, accelerate] voice [grpcio, nvidia-riva-client]本地推理装 voice_local云端 ASR 装 voice。两个都装也行但纯云端方案没必要拉几个 GB 的 PyTorch。国内下载模型慢的话加一行镜像export HF_ENDPOINThttps://hf-mirror.com这个环境变量会被 transformers 读取模型从镜像站拉速度差别很明显。4. 验证转录链路从发语音到收到回复配置填完先别急着上生产按这个顺序验证一遍。第一步装依赖。本地方案uv sync --extra voice_local云端方案uv sync --extra voice第二步启动服务uv run server.py第三步在 Discord 频道发一条语音。正常的话你会看到三个阶段的反馈Bot 先回Transcribing voice note…几秒后这条消息被编辑成 Claude 的处理状态最后收到文本回复。如果你想在代码层面单独验证转录函数可以写个最小脚本import asyncio from pathlib import Path from messaging.voice import VoiceTranscriptionService async def main(): service VoiceTranscriptionService( hf_token, nvidia_nim_api_keynvapi-your-key, ) text await service.transcribe( file_pathPath(voice_note.ogg), mime_typeaudio/ogg, whisper_modelbase, whisper_devicecpu, ) print(f转录结果{text}) asyncio.run(main())跑通本地 CPU 后把 whisper_device 改成 nvidia_nimwhisper_model 改成 openai/whisper-large-v3再跑一次。两次结果对比一下你就能直观感受到云端 ASR 在长音频上的延迟优势。验证成功的标志是转录文本非空且能正确送入后续的 Claude 处理链路。如果文本为空源码里会返回 (no speech detected)这时候先检查音频本身是不是静音或噪声太大。5. 常见报错排查401、local proxy failed、reading choices排障这块我按真实遇到的报错来列每个都给定位思路。401 Unauthorized。这个最常见分两种。如果是 NVIDIA NIM 返回的 401检查 NVIDIA_NIM_API_KEY 是不是 nvapi- 开头以及有没有多余空格。如果是大模型调用返回 401检查 OPENAI_API_KEY 和 OPENAI_BASE_URL 是否配对——Base URL 填了 https://taotoken.net/apiKey 就得是 TaoToken 控制台生成的别把别家的 Key 填进来。local proxy failed。这个报错通常出现在网络层说明请求根本没到达目标服务。先确认你的 Base URL 拼写正确注意结尾不要多加斜杠。然后检查本机 DNS 和出网是否正常。如果是容器环境确认容器能访问外网。Error reading choices。这个报错说明请求发出去了但返回的 JSON 结构里没有 choices 字段。常见原因是 Model ID 填错了服务端返回了一个错误对象而不是正常的补全结果。把 MODEL 改成你确认可用的模型标识重新请求。OAuth 相关报错。如果你用的是 Claude Code 原生的 OAuth 登录流程但同时又配了第三方 Base URL两者会冲突。走 TaoToken 这种 API Key 方式时确保没有残留的 OAuth 凭据文件干扰。检查 ~/.claude 目录下有没有旧的认证缓存必要时清掉重来。CUDA out of memory。本地跑 large-v3 需要约 6GB 显存不够就换 base 或 small或者直接切 nvidia_nim 走云端。ImportError: Local Whisper requires…。说明你没装 voice_local 依赖执行 uv sync --extra voice_local 补上。模型下载卡住。设置 HF_ENDPOINThttps://hf-mirror.com 后重启服务。排查时记住一个原则先确认是哪一层的问题。转录层报错看 WHISPER_DEVICE 和对应 Key大模型层报错看 Base URL 和 Model ID。两层分开测别一起调。6. 把语音转录接进你的工作流配置跑通之后日常使用就是发语音、等回复。但有几个实用技巧值得说。状态消息的即时反馈很关键。源码里在转录开始前就发了Transcribing voice note…这个设计降低了等待焦虑。你自己做类似功能时也建议保留这个模式哪怕转录只要两秒用户看到反馈心里也踏实。可取消设计值得借鉴。PendingVoiceRegistry 用双向索引支持用户在转录中途发 /clear 或 /stop转录完成后会再检查一次 is_pending()如果被取消就丢弃结果。这个模式在你做任何长耗时异步任务时都能用。模型缓存别忽略。Whisper Pipeline 按 (model_id, device, token) 做键缓存切换模型会触发重新加载。所以生产环境别频繁切模型选定一个就跑。如果你要把这套能力接进自己的项目最小依赖是 messaging/voice.py 里的 VoiceTranscriptionService 和 messaging/transcription.py 里的 transcribe_audio。把这两个文件抽出来配上 asyncio.to_thread 的调用方式就能复用一个不阻塞事件循环的转录服务。需要看更多接入示例的话接入文档在这里https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentdoc 。想直接对话验证模型效果可以用模型对话页https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentmodel 。API Key 在控制台生成https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentapi-keys 。最后提醒一句本地 Whisper 和云端 NIM 的切换只改 WHISPER_DEVICE 一个变量但依赖包不同切换前确认对应依赖已安装。这个坑我在测试时踩过切到 nvidia_nim 忘了装 voice 依赖报了一堆 import 错误装完就好了。