语音集成：AI 应用中的语音输入处理

语音集成：AI 应用中的语音输入处理

学习目标

理解 CopilotKit 的语音输入架构：

• TranscriptionService 的抽象接口设计
• 语音转文字端点的处理流程
• 专用错误码体系
• 前端语音录制组件集成

前置知识

本章涉及多引擎架构的通用原理，建议先阅读：

• 多引擎回退与质量评分

下文假设你已理解上述概念，直接聚焦 CopilotKit 的语音集成实现。

项目实践

TranscriptionService 抽象

TranscriptionService 是可插拔的语音转文字服务接口：

接口定义（伪代码）：
interface TranscriptionService {
  transcribe(audioData: ArrayBuffer): Promise<string>
}

设计原则：

• 抽象层不绑定具体提供商（OpenAI Whisper、Google STT 等）
• 运行时通过 transcriptionService 配置注入具体实现
• 前端通过独立端点 /api/copilotkit/transcribe 调用

语音端点处理流程

处理步骤（源码验证）：

1. 前端录制音频（Web Audio API）
2. POST 发送到 /api/copilotkit/transcribe
3. 运行时调用 TranscriptionService.transcribe(audioData)
4. 返回转录文本
5. 前端将转录文本作为用户消息注入 Agent

错误码体系

CopilotKit 定义了专用的转录错误码：

错误码	说明	前端响应
TRANSCRIPTION_FAILED	通用转录失败	提示用户重试
TRANSCRIPTION_SERVICE_NOT_CONFIGURED	未配置转录服务	提示管理员配置
TRANSCRIPTION_INVALID_AUDIO	音频格式/数据无效	提示用户重新录制
TRANSCRIPTION_RATE_LIMITED	请求频率超限	指数退避重试
TRANSCRIPTION_AUTH_FAILED	认证失败	提示重新登录
TRANSCRIPTION_NETWORK_ERROR	网络错误	自动重试

前端集成

Voice 包提供语音录制组件：

import { useVoice } from "@copilotkit/voice";

const { isRecording, startRecording, stopRecording } = useVoice();

转录后的文本自动注入到聊天消息中，与文本输入体验一致。

问题与规避

问题	规避策略
音频格式不兼容	TranscriptionService 实现层处理格式转换
长音频超时	分块传输；或限制单次录制时长
并发转录	Rate limiting 错误码 + 前端退避重试

设计取舍

独立语音端点 vs 集成到聊天端点

独立端点（CopilotKit 的选择）：

• 优势：语音转文字是独立操作，不需要 Agent 参与
• 代价：需要额外维护一个端点

集成到聊天端点：

• 优势：架构更简洁
• 代价：聊天端点职责过重，语音处理阻塞聊天请求

参考来源

• packages/runtime/src/v2/runtime/handlers/handle-transcribe.ts
• packages/runtime/src/v2/runtime/core/transcription-service/transcription-service.ts
• packages/voice/src/