本文基于开源项目openai-chatkit-advanced-samples，详解ChatKit 听写（语音转文字）功能的完整实现：前端如何用一行配置开启麦克风输入，服务端又如何调用gpt-4o-transcribe把语音实时转成文字填入输入框。读完你即可在自己的 ChatKit 应用中复刻这套「开口说、不用打字」的体验。

听写功能在哪里：Customer Support 示例

仓库收录了 4 个 ChatKit 场景示例，其中Customer Support（航空客服）是唯一启用听写的示例：聊天输入框内置麦克风按钮，点击即可开口说话，应用会先把语音转写为文字再发送。

官方在仓库 README 的功能索引中也专门列出了这项能力（README.md）：前端通过composer.dictation开启，服务端通过实现ChatKitServer.transcribe()完成转写。下面逐层拆解。

前端一键开启：composer.dictation 配置

听写的前端开关只有一个配置项。在 Customer Support 的聊天面板组件 ChatKitPanel.tsx 中，useChatKit的composer选项里声明：

composer: { placeholder: "Ask the concierge a question", attachments: { enabled: true, maxSize: MAX_UPLOAD_BYTES, accept: IMAGE_ATTACHMENT_ACCEPT }, dictation: { enabled: true }, },

就这么一行dictation: { enabled: true }，@openai/chatkit-reactSDK 会自动在输入框里渲染出麦克风按钮，并接管录音、上传等交互。你无需自己处理MediaRecorder、音频分片或 WebSocket 细节——这正是 ChatKit SDK「把复杂留给 SDK」的价值所在。

体验路径参考 customer-support/README.md：点击输入框的麦克风按钮 → 授予浏览器麦克风权限 → 说出你的请求（例如“帮我把 OA476 航班换到 14C 座”）→ 转写完成的文字会填入输入框，确认后即可发送。

服务端语音转文字：实现 ChatKitServer.transcribe()

前端录制的音频最终会发送到后端的/support/chatkit入口（main.py），由ChatKitServer统一路由。而真正决定「能不能转、用哪个模型转」的，是服务端是否实现了transcribe()钩子。

在 server.py 中，CustomerSupportServer覆写了该方法：

async def transcribe(self, audio_input: AudioInput, context: dict[str, Any]) -> TranscriptionResult: ext = { "audio/webm": "webm", "audio/mp4": "m4a", "audio/ogg": "ogg", }.get(audio_input.media_type) if not ext: raise HTTPException(status_code=400, detail="Unexpected audio format") audio_file = io.BytesIO(audio_input.data) audio_file.name = f"audio.{ext}" transcription = client.audio.transcriptions.create( model="gpt-4o-transcribe", file=audio_file ) return TranscriptionResult(text=transcription.text)

这段不到 15 行的代码包含 3 个关键决策：

1. 格式白名单：SDK 传入的AudioInput带有media_type，这里只放行webm / m4a / ogg三种浏览器常见录音格式，遇到未知格式直接返回 400，避免把脏数据喂给转写模型；
2. 文件命名技巧：OpenAI 的audio.transcriptions接口需要依据文件名后缀识别格式，所以代码给内存流临时命名为audio.{ext}，这是不少初学者的踩坑点；
3. 返回TranscriptionResult：只需把transcription.text包进 SDK 定义的TranscriptionResult返回，前端输入框就会自动填入文本。

完整调用链路：一次听写的旅程

把前后端串起来，一次语音输入经历如下流程：

值得注意的一点：听写只负责「语音 → 文本」这一步，转写完成后走的就是普通消息通道，与手打消息完全等价。因此 Agent 的工具调用、侧边栏状态同步等能力对语音输入天然可用，零额外适配。

本地运行：3 步跑起来

# 1. 克隆仓库 git clone https://gitcode.com/gh_mirrors/op/openai-chatkit-advanced-samples # 2. 准备环境变量（需安装 uv） export OPENAI_API_KEY="sk-..." export VITE_SUPPORT_CHATKIT_API_DOMAIN_KEY="任意非空占位值" # 3. 仓库根目录一键启动 npm run customer-support

启动后访问http://localhost:5171，在输入框点击麦克风即可体验。前后端分工可对照 customer-support/README.md 中的 Quickstart 章节逐步排查。

复刻到你自己项目：要点清单

🎙️ 想在其他示例（Cat Lounge、News Guide、Metro Map）中加入听写，只需两步：

• 前端：在对应ChatKitPanel.tsx的composer配置中加上dictation: { enabled: true }；
• 服务端：让ChatKitServer子类实现transcribe()，转写模型可沿用gpt-4o-transcribe，也按需替换为你自己的 ASR 服务（只需返回TranscriptionResult）。

两个小提醒：

• 生产环境部署时，前端域名需登记到 OpenAI 平台的域名白名单，并把正式 domain key 配入VITE_SUPPORT_CHATKIT_API_DOMAIN_KEY（开发阶段任意非空占位值即可），配置细节见 config.ts；
• 听写依赖浏览器麦克风权限，务必在支持 HTTPS（或 localhost）的环境下测试，否则浏览器会直接拒绝录音。

总结

ChatKit 的听写能力把「语音转文字」拆成了极简的前后端契约：前端一行dictation配置负责开启体验，服务端一个transcribe()方法负责落地转写，中间的音频采集、上传、回填全部由 SDK 托管。以 Customer Support 示例为模板，你几乎可以零成本地为任何 ChatKit 应用加上「开口说，不用打字」的交互能力。