两种架构，两种追踪形状
您构建语音代理的方式决定了追踪的外观。有两种常见的架构，它们会产生根本不同的追踪。级联式
级联式将独立的、单一用途的模型串联起来：语音转文本（STT）转录用户的音频，语言模型（LLM）对文本进行推理并决定做什么，文本转语音（TTS）合成回复。中间件、工具调用和检索步骤位于它们之间。 由于每个阶段都是具有明确输入和输出的独立模型调用，因此级联式像任何其他代理管道一样进行追踪。追踪是一个由STT、LLM、TTS、工具和中间件运行组成的树：各个阶段可以并行运行，对话的每一轮都会重复一个新的 STT → LLM → TTS 循环。这些运行具有有意义的输入/输出对（音频输入 → 转录输出，提示输入 → 补全输出）。
构建级联式语音代理的两个最常见框架是 LiveKit 和 Pipecat。
语音到语音 (S2S)
语音到语音模型（例如 OpenAI Realtime API 或 Gemini Live）原生处理音频，并通过单一的持久连接（通常是 WebSocket）用音频进行回复。没有需要追踪的 STT/LLM/TTS 分解。 相反，模型服务器和您的客户端在线路上交换一串事件：音频块、转录片段、工具调用请求、轮次边界、中断和错误。自然的追踪单位是事件有效载荷，而不是请求/响应对。您记录的每个事件成为一个 span，其内容是跨越线路的有效载荷。 本页的其余部分描述了适用于这两种架构的约定。提供商指南涵盖了 OpenAI Realtime 和 Gemini Live 的事件流细节。核心约定
以下是我们推荐的实践，以便在 LangSmith 中充分利用语音追踪。您应根据最适合您基础设施和实现的方式来追踪语音应用程序，但遵循我们在此建议的结构将有助于使您的追踪保持一致，并易于调试和评估。 我们推荐三个高层约定：- 将每次对话作为单次追踪，而不是将其拆分为多个追踪。
- 录制一个组合音频文件 并附加到根运行。
- 将追踪标记为音频，使用
ls_modality，以便将其作为语音追踪进行渲染和过滤。
将每次对话作为单次追踪
对话是一次单一的交互，因此我们建议将其保持在单个追踪中，各个模型调用或事件嵌套在一个代表整个对话的根运行之下。 不要将对话拆分为多个追踪。如果您为每次交流启动一个新的追踪，您会丢失交流之间存在的信息：- 中断：当用户打断代理，代理停止时（插话）。
- 时机和延迟：说话者之间的间隔，以及代理响应所需的时间。
- 上下文：对对话早期部分的引用。
- 对话级结果：用户的目标是否最终得到解决。
语音代理没有可靠的“轮次”概念。说话者重叠、中断和声音渐弱。不要将运行分组到合成的轮次中。而是追踪真实的单位：级联式中的模型调用，或语音到语音流中的事件有效载荷。
录制一个组合音频文件
将一个音频文件附加到根运行，该文件包含用户和代理双方的音频，录制自实际播放给客户端的音频，而不是模型生成的音频。 在客户端录制。一种常见的方法是立体声 WAV，用户的麦克风在一个声道上，代理的语音（在扬声器处捕获）在另一个声道上。这很重要，因为生成的音频和听到的音频不是一回事：网络延迟、数据包丢失或乱序以及插话都会改变用户实际体验到的内容。在代理说话中途将其切断的插话，在录制中应显示为截断，因为那就是实际发生的情况。录制实际播放的内容，而不是生成但可能从未被听到的内容，这是使追踪忠实于真实交互的关键。 使用附件 API 附加文件：Python
将追踪标记为音频
在根运行上设置ls_modality 元数据字段为 "audio"。这将把该追踪标记为语音追踪，以便 LangSmith 可以适当地渲染它，并且您可以在项目中过滤语音追踪。
Python
有关其他
ls_ 元数据字段，请参阅元数据参数参考。后续步骤
追踪 OpenAI Realtime
追踪基于 OpenAI Realtime API 构建的语音代理。
追踪 Gemini Live
追踪基于 Gemini Live API 构建的语音代理。
追踪 LiveKit
追踪使用 LiveKit Agents 构建的语音代理。
追踪 Pipecat
追踪使用 Pipecat 构建的语音代理。
通过追踪上传文件
将对话音频录制附加到您的追踪中。
记录多模态追踪
在 LangSmith UI 中渲染音频和其他媒体。
Connect these docs to Claude, VSCode, and more via MCP for real-time answers.