此集成处于 Beta 阶段,其 API 可能会发生变化。
使用 LangSmith LiveKit 集成,将您的 LiveKit Agents 语音代理追踪到 LangSmith。有关高级约定,请参阅语音追踪基础。
LiveKit 集成需要 langsmith[livekit]>=0.9.7。
该集成通过钩入 LiveKit 已经发出的跨度,并将其映射到 LangSmith 的追踪格式,从而使每次对话成为一条单独的 LangSmith 追踪:每个管道事件一个跨度,外加 LiveKit 的延迟和令牌指标。

安装

安装此集成以及您的代理所使用的 LiveKit 插件:

设置环境变量

该集成从环境变量中读取您的 LangSmith 凭证,并通过 OpenTelemetry 为您导出到 LangSmith:
.env

设置追踪

在创建 AgentServer 之前,导入 configure_livekit 并调用一次。它会构建追踪器提供者,注册 LangSmith 跨度处理器,并将其接入 LiveKit:
此方法适用于 STT/LLM/TTS 级联模型和语音到语音(实时)模型。实时模型(例如 lk_openai.realtime.RealtimeModel(...))需要额外调用以捕获用户的转录文本。请参阅当 LiveKit 与实时模型一起使用时。

使用您自己的追踪器提供者

configure_livekit() 会构建一个 TracerProvider,注册 LangSmith 跨度处理器,并将其接入 LiveKit。如果您想使用自己管理的 TracerProvider,请自行构建处理器,将其添加到您的提供者中,并通过 LiveKit 的追踪器钩子注册该提供者。LiveKit 仅通过其追踪器绑定的提供者发出跨度:

将对话分组到一个线程中

要将对话的运行分组到一个 LangSmith 线程中,以便进行线程级视图以及令牌和成本聚合,请在 @server.rtc_session() 处理程序内、在发出跨度之前,对每次对话调用一次 set_thread_id:

当 LiveKit 与实时模型一起使用时

对于语音到语音(实时)模型,没有单独的语音转文本步骤,因此 LiveKit 会异步转录用户的音频,并通过会话的 user_input_transcribed 事件传递转录文本,而不是通过其发出的 OTel 追踪。
instrument_session 需要 langsmith[livekit]>=0.10.4。
在创建 AgentSession 后立即调用 instrument_session 一次,这样 SDK 就会为您订阅该事件,并将每次转录与其对应的轮次配对。它通过线程 ID 进行关联,因此请先使用 set_thread_id 设置它,并传递相同的 ID:
仅对实时模型调用 instrument_session。在 STT/LLM/TTS 级联中,转录文本已经(从语音转文本步骤中)被捕获,因此在那里调用它会将用户轮次记录两次。

记录音频

该集成将通话录音附加到对话的根跨度上。您如何捕获录音在本地开发和生产环境之间有所不同。

开发:嵌入本地文件

在控制台和本地开发环境中,启用 LiveKit 的会话录制,并将 audio_path_provider 指向 LiveKit 在 ctx.session_directory 下写入的 audio.ogg。该集成读取该文件并将字节嵌入到追踪中。
在控制台模式下,还需要在命令行上传递 --record。录音反映的是播放给客户端的内容,因此抢占式输入会被截断。
不要在生产环境中使用 audio_path_provider。在部署的 worker 中,ctx.session_directory 是一个临时的临时目录,LiveKit 会在会话结束时删除它,因此没有持久化的文件可供嵌入。

生产环境:使用 Egress 录制并附加文件

在生产环境中,使用 LiveKit Egress 将房间录制到您自己的对象存储中,然后将完成的录音作为真正的音频附件附加到追踪上。Egress 在通话结束后才完成上传,因此集成会保持对话的根跨度处于打开状态,直到您提供字节:
  1. 当您启动 Egress 时调用 processor.expect_recording(thread_id)。
  2. 通话结束后,等待 Egress 完成,从您的存储下载文件,然后调用 processor.complete_recording(thread_id, audio_bytes)。集成将嵌入字节并导出追踪。
您必须对 expect_recording 和 complete_recording 使用相同的 thread_id,以便录音匹配到正确的对话。
wait_for_egress 会轮询 list_egress 直到状态为 EGRESS_COMPLETE(或订阅 egress_ended webhook),而 download_from_storage 会使用您的云提供商客户端读取对象。LiveKit Egress 也可以写入 Google Cloud Storage 和 Azure:将 s3= 替换为 gcp=api.GCPUpload(...) 或 azure=api.AzureBlobUpload(...)。
始终要调用 complete_recording,因为追踪的根跨度会保持打开状态直到它运行,包括在失败时使用 data=None。如果 worker 先停止,集成将在没有音频的情况下刷新追踪。

后续步骤

语音基础

追踪语音代理的核心约定。

随追踪上传文件

将对话音频录音附加到您的追踪。