尧图网页设计 
LiveKit Agents Tavus 插件实战为实时语音 AI 接入虚拟数字人TAVUS_API_KEY 配置与 AvatarSession 深度解析【免费下载链接】agentsA framework for building realtime voice AI agents ️项目地址: https://gitcode.com/GitHub_Trending/agen/agents导读livekit-plugins-tavus是 LiveKit Agents 官方插件体系中面向Tavus 虚拟数字人virtual avatar的接入方案用于在实时语音 AI 会话中挂载一个可发音、可出镜的虚拟形象实现能听会说还能露脸的交互体验。本文以该插件官方 README 为核心结合仓库内 avatar.py 与 api.py 的源码实现完整讲解安装、API Key 前置条件、环境变量体系、AvatarSession关键参数与底层会话启动链路读完即可在自己的 Agent 项目中正确配置并运行 Tavus 数字人。插件定位给实时语音 Agent 加一张脸在 LiveKit Agents 的生态里语音 Agent 通常只处理音频链路STT → LLM → TTS。而 Tavus 是一家提供**可实时驱动虚拟化身avatar**能力的服务它能在云端渲染一个数字人形象并接收 Agent 的语音输出让数字人的嘴型、表情与语音实时同步。livekit-plugins-tavus就是这个生态位上的官方插件它实现了 LiveKit Agents 的AvatarSession抽象与AgentSession协同工作它通过conversation_id与 Tavus 云端建立会话并把 Tavus 数字人作为房间内一个独立 participant加入 LiveKit 房间它把 Agent 生成的语音通过DataStream数据流推送给 Tavus 云端用于驱动口型实现音视频联动。从 pyproject.toml 可以看到该插件依赖livekit-agents1.8.0要求 Python3.10当前版本见 version.py为1.8.0采用 Apache-2.0 许可。安装一行命令接入官方 README 给出的安装方式非常直接pip install livekit-plugins-tavus如果你使用 uv 管理依赖也可以等价地在项目pyproject.toml中加入livekit-plugins-tavus后执行同步。安装完成后导入路径为livekit.plugins.tavus包对外暴露三个成员见init.pyAvatarSession—— 插件核心类用于建立 Tavus 数字人会话TavusException—— Tavus 相关错误的统一异常类型__version__—— 插件版本号。此外模块底部会自动执行Plugin.register_plugin(TavusPlugin())即安装即注册为 LiveKit Agents 的官方插件方便框架做统一管理。前置条件TAVUS_API_KEY 与 LiveKit 凭据README 明确强调的唯一前置条件是Tavus 的 API KeyYoull need an API key from Tavus. It can be set as an environment variable:TAVUS_API_KEY在源码中这一约束被强制执行TavusAPI.__init__会先读取参数api_key否则回退读取环境变量TAVUS_API_KEY两者都取不到时直接抛出TavusException(TAVUS_API_KEY must be set)见 api.py。除了 Tavus 侧凭据实际启动会话还需要一组LiveKit 房间凭据用于让 Tavus 云端以数字人身份加入你的房间环境变量用途TAVUS_API_KEYTavus 平台 API Key必填缺失即抛异常LIVEKIT_URLLiveKit 服务器的 WebSocket 地址形如wss://xxx.livekit.cloud数字人将基于它连入房间LIVEKIT_API_KEY/LIVEKIT_API_SECRETLiveKit 项目的 API 密钥对用于为数字人生成带房间权限的 Access TokenAvatarSession.start()会依次读取上述三个 LiveKit 环境变量任一缺失都会抛出TavusException见 avatar.py。三者同样支持通过start()的livekit_url、livekit_api_key、livekit_api_secret参数直接传入参数优先于环境变量。环境变量总览官方命名与废弃别名结合 api.py 与 test_tavus.py 的测试用例插件完整支持以下环境变量且存在新名优先、旧名告警降级的兼容策略环境变量新废弃别名说明TAVUS_FACE_IDTAVUS_REPLICA_ID指定数字人使用的人脸/复制体 IDTAVUS_PAL_IDTAVUS_PERSONA_ID指定 Tavus PAL形象配置ID读取顺序是显式参数 → 新环境变量 → 废弃环境变量。若设置了废弃变量如TAVUS_REPLICA_ID源码会通过_deprecated_env()打印DeprecationWarning提示迁移到新名称见 api.py但功能上仍完全可用——测试test_deprecated_env_vars_still_work_and_warn正是验证这一点设置TAVUS_REPLICA_IDoldf、TAVUS_PERSONA_IDoldp后请求 payload 中的face_id、pal_id仍被正确填充。快速接入AvatarSession 完整参数清单AvatarSession的构造签名见 avatar.py如下from livekit.plugins.tavus import AvatarSession avatar AvatarSession( face_id你的 face_id, # 数字人人脸 ID pal_id你的 pal_id, # Tavus PAL 形象 ID # replica_id..., # 已废弃face_id 的旧别名 # persona_id..., # 已废弃pal_id 的旧别名 api_urlhttps://tavusapi.com/v2, # 可选Tavus API 地址默认即此值 api_keyTAVUS_API_KEY, # 可选不传则读环境变量 avatar_participant_identitytavus-avatar-agent, # 可选数字人在房间内的身份 avatar_participant_nametavus-avatar-agent, # 可选数字人显示名称 )各参数说明face_idTavus 的人脸复制体ID决定数字人长相。默认值为源码中的DEFAULT_FACE_ID r4067604db72Lucy - Homephoenix-4.5。pal_idTavus PALPersona Avatar Layer配置 ID决定形象与行为层组合。默认值为DEFAULT_PAL_ID pb87e71797da。replica_id/persona_id一对废弃别名。replica_id→face_idpersona_id→pal_id。源码用_coalesce_with_deprecated()统一处理仅当新参数未提供时才使用旧名并在用到旧名时告警见 avatar.py。api_urlTavus API 根地址默认https://tavusapi.com/v2见 api.py一般无需修改。api_keyTavus API Key不传时回退到TAVUS_API_KEY环境变量。avatar_participant_identity/avatar_participant_name数字人作为房间 participant 的身份与显示名默认均为tavus-avatar-agent。conn_optionsAPIConnectOptions类型控制对 Tavus API 的调用超时与重试默认使用DEFAULT_API_CONNECT_OPTIONS。构造完成后将avatar传入你的AgentSession框架会在合适时机自动调用avatar.start(agent_session, room)即可开始会话。默认 PAL 与 Face 的智能兜底逻辑这是插件一个很贴心的设计即使你不指定任何形象参数也能直接跑通。TavusAPI.create_conversation()内部的默认值逻辑见 api.py为若既没有pal_id也没有extra_payload中的pal_id则自动填入内置的DEFAULT_PAL_ID并在未显式给出face_id时一并填入DEFAULT_FACE_ID若用户只给了face_id则保留默认 PAL 用户指定 Face若用户只给了pal_id则不再填face_id——因为用户自建的 PAL 自带默认 Face强塞默认 Face 反而会覆盖它若通过extra_payload整体覆盖了pal_id同样不会附加默认 Face。这一行为在 test_tavus.py 中有四组用例逐一验证test_no_pal_uses_default_pal_with_face_override、test_pal_id_only_skips_pal_creation_and_omits_face、test_defaults_to_stock_pal_and_face_when_neither_given、test_extra_payload_pal_keeps_its_own_face。测试同时断言整个过程不会额外调用创建 PAL 的接口说明默认 PAL 是 Tavus 平台内置的现成资源无需你预先创建。start() 内部数字人是如何加入房间的AvatarSession.start()见 avatar.py是插件最核心的执行链路共四步第一步校验 LiveKit 凭据。读取LIVEKIT_URL、LIVEKIT_API_KEY、LIVEKIT_API_SECRET或方法入参缺失即抛TavusException。第二步为数字人签发房间 Token。使用 LiveKit 的api.AccessToken以agent身份、identity 为tavus-avatar-agent签发room_joinTrue且限定roomroom.name的 grants并附加一个关键属性ATTRIBUTE_PUBLISH_ON_BEHALF 本地 Agent 的 participant identity见 avatar.py。这个属性授权数字人代表本地 Agent 发布音视频轨道是Agent 出镜权限层面的关键设计。第三步调用 Tavus API 创建会话。调用create_conversation()传入pal_id、face_id以及properties{livekit_ws_url: livekit_url, livekit_room_token: livekit_token}。Tavus 云端据此让数字人连入你的房间并把返回的conversation_id保存在self.conversation_id上供后续排障与扩展使用。第四步替换音频输出为 DataStream。通过agent_session.output.replace_audio_tail(DataStreamAudioOutput(...))见 avatar.py把 Agent 的 TTS 音频输出从本地扬声器链路切换为面向数字人的数据流DataStreamAudioOutput( roomroom, destination_identityself._avatar_participant_identity, # 发给数字人 participant sample_rateSAMPLE_RATE, # 24000 Hz wait_remote_trackrtc.TrackKind.KIND_VIDEO, # 等待数字人视频轨道就绪 )SAMPLE_RATE 24000为音频采样率常量见 avatar.py。DataStreamAudioOutput定义于框架层的 livekit-agents/livekit/agents/voice/avatar/_datastream_io.py它基于 LiveKit DataStream 主题lk.audio_stream将音频帧推送给远端数字人工作进程并通过lk.playback_finished、lk.playback_started、lk.clear_buffer等 RPC 实现播放状态回传与缓冲清空从而支撑打断interruption场景下音频的即时停止与重放。wait_remote_trackKIND_VIDEO则确保在数字人视频轨出现后才开始推送音频避免音画错位。基类AvatarSession的抽象契约avatar_identity、provider、start定义在 livekit-agents/livekit/agents/voice/avatar/_types.pyTavus 实现中provider返回tavusavatar_identity返回数字人 participant identity便于框架在房间内识别数字人轨道。底层 API 封装会话、PAL 与重试机制TavusAPI见 api.py负责与 Tavus REST API 通信默认地址https://tavusapi.com/v2通过x-api-key请求头携带密钥。它提供三个方法create_conversation()—— 创建数字人会话语返回conversation_id。请求体包含pal_id、face_id有值才发送、properties以及一个自动生成的conversation_name形如lk_conversation_shortuuidextra_payload可整体覆盖请求体字段。create_pal()—— 创建自定义 PAL 形象返回pal_id。源码中的默认请求体给出了 PAL 的典型结构见 api.py{ pal_name: name, # 不传则自动生成 lk_pal_shortuuid default_face_id: default_face_id, # 必填 pipeline_mode: echo, # 回声管线接收 TTS 音频驱动口型 layers: { transport: {transport_type: livekit}, # 传输层走 LiveKit }, }create_persona()—— 创建 persona 的废弃接口官方注释明确建议改用create_pal()调用时会打印告警它仍走旧的/personas端点。重试机制所有请求统一经_post()见 api.py按conn_options.max_retry进行重试重试间隔为conn_options.retry_interval连接超时取自conn_options.timeout。非 2xx 响应抛APIStatusError并附带状态码与响应体重试耗尽后抛APIConnectionError。这些行为由AgentSession传入的conn_optionsAPIConnectOptions控制默认值即框架的DEFAULT_API_CONNECT_OPTIONS。升级迁移提示新旧参数并存期如何安全过渡如果你在旧版本项目中看到replica_id、persona_id、TAVUS_REPLICA_ID、TAVUS_PERSONA_ID等命名请注意它们均为兼容性保留的废弃别名插件内部已统一映射到face_id/pal_id与TAVUS_FACE_ID/TAVUS_PAL_ID。迁移建议代码层面将replica_id替换为face_idpersona_id替换为pal_id环境变量层面将TAVUS_REPLICA_ID替换为TAVUS_FACE_IDTAVUS_PERSONA_ID替换为TAVUS_PAL_ID新旧参数同时传入时新参数优先且不会触发告警测试test_no_warning_when_new_and_deprecated_both_given验证了该行为弃用告警以DeprecationWarning形式通过logger.warning输出可在测试或 CI 中监听以发现存量用法。测试验证与进一步阅读插件的单元测试集中在 tests/test_tavus.py覆盖了本文提到的全部关键行为新旧参数映射与告警、环境变量回退链、默认 PAL/Face 兜底逻辑、以及AvatarSession构造时的参数解析如AvatarSession(face_idf9, pal_idp9)与废弃别名AvatarSession(replica_idr9, persona_idx9)的等价性。测试通过 mock_post断言请求 payload不依赖真实 Tavus 服务可直接在本地运行pytest livekit-plugins/livekit-plugins-tavus/tests/若想查看更多插件的对照实现可参考同目录下的 livekit-plugins-liveavatar同为 LiveKit 官方数字人方案以及 examples/avatar 示例中的AvatarSession用法示例选用 Lemonslice 数字人但AvatarSession的接入范式完全一致。完整理解DataStreamAudioOutput的协议细节可继续阅读 livekit-agents/livekit/agents/voice/avatar/_datastream_io.py 与 livekit-agents/livekit/agents/voice/avatar/_types.py。小结livekit-plugins-tavus的官方 README 虽短但其背后是一套完整的数字人接入协议环境变量TAVUS_API_KEY完成鉴权face_id/pal_id决定形象start()内部的 Token 签发 create_conversationDataStreamAudioOutput三步链路实现Agent 说话 → 数字人出镜对口型的实时闭环。掌握本文的参数体系与底层调用链即可在 LiveKit Agents 项目中快速、可靠地接入 Tavus 虚拟数字人。【免费下载链接】agentsA framework for building realtime voice AI agents ️项目地址: https://gitcode.com/GitHub_Trending/agen/agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 LiveKit Agents Tavus 插件实战：为实时语音 AI 接入虚拟数字人（TAVUS_API_KEY 配置与 AvatarSession 深度解析）
LiveKit Agents Tavus 插件实战为实时语音 AI 接入虚拟数字人TAVUS_API_KEY 配置与 AvatarSession 深度解析【免费下载链接】agentsA framework for building realtime voice AI agents ️项目地址: https://gitcode.com/GitHub_Trending/agen/agents导读livekit-plugins-tavus是 LiveKit Agents 官方插件体系中面向Tavus 虚拟数字人virtual avatar的接入方案用于在实时语音 AI 会话中挂载一个可发音、可出镜的虚拟形象实现能听会说还能露脸的交互体验。本文以该插件官方 README 为核心结合仓库内 avatar.py 与 api.py 的源码实现完整讲解安装、API Key 前置条件、环境变量体系、AvatarSession关键参数与底层会话启动链路读完即可在自己的 Agent 项目中正确配置并运行 Tavus 数字人。插件定位给实时语音 Agent 加一张脸在 LiveKit Agents 的生态里语音 Agent 通常只处理音频链路STT → LLM → TTS。而 Tavus 是一家提供**可实时驱动虚拟化身avatar**能力的服务它能在云端渲染一个数字人形象并接收 Agent 的语音输出让数字人的嘴型、表情与语音实时同步。livekit-plugins-tavus就是这个生态位上的官方插件它实现了 LiveKit Agents 的AvatarSession抽象与AgentSession协同工作它通过conversation_id与 Tavus 云端建立会话并把 Tavus 数字人作为房间内一个独立 participant加入 LiveKit 房间它把 Agent 生成的语音通过DataStream数据流推送给 Tavus 云端用于驱动口型实现音视频联动。从 pyproject.toml 可以看到该插件依赖livekit-agents1.8.0要求 Python3.10当前版本见 version.py为1.8.0采用 Apache-2.0 许可。安装一行命令接入官方 README 给出的安装方式非常直接pip install livekit-plugins-tavus如果你使用 uv 管理依赖也可以等价地在项目pyproject.toml中加入livekit-plugins-tavus后执行同步。安装完成后导入路径为livekit.plugins.tavus包对外暴露三个成员见init.pyAvatarSession—— 插件核心类用于建立 Tavus 数字人会话TavusException—— Tavus 相关错误的统一异常类型__version__—— 插件版本号。此外模块底部会自动执行Plugin.register_plugin(TavusPlugin())即安装即注册为 LiveKit Agents 的官方插件方便框架做统一管理。前置条件TAVUS_API_KEY 与 LiveKit 凭据README 明确强调的唯一前置条件是Tavus 的 API KeyYoull need an API key from Tavus. It can be set as an environment variable:TAVUS_API_KEY在源码中这一约束被强制执行TavusAPI.__init__会先读取参数api_key否则回退读取环境变量TAVUS_API_KEY两者都取不到时直接抛出TavusException(TAVUS_API_KEY must be set)见 api.py。除了 Tavus 侧凭据实际启动会话还需要一组LiveKit 房间凭据用于让 Tavus 云端以数字人身份加入你的房间环境变量用途TAVUS_API_KEYTavus 平台 API Key必填缺失即抛异常LIVEKIT_URLLiveKit 服务器的 WebSocket 地址形如wss://xxx.livekit.cloud数字人将基于它连入房间LIVEKIT_API_KEY/LIVEKIT_API_SECRETLiveKit 项目的 API 密钥对用于为数字人生成带房间权限的 Access TokenAvatarSession.start()会依次读取上述三个 LiveKit 环境变量任一缺失都会抛出TavusException见 avatar.py。三者同样支持通过start()的livekit_url、livekit_api_key、livekit_api_secret参数直接传入参数优先于环境变量。环境变量总览官方命名与废弃别名结合 api.py 与 test_tavus.py 的测试用例插件完整支持以下环境变量且存在新名优先、旧名告警降级的兼容策略环境变量新废弃别名说明TAVUS_FACE_IDTAVUS_REPLICA_ID指定数字人使用的人脸/复制体 IDTAVUS_PAL_IDTAVUS_PERSONA_ID指定 Tavus PAL形象配置ID读取顺序是显式参数 → 新环境变量 → 废弃环境变量。若设置了废弃变量如TAVUS_REPLICA_ID源码会通过_deprecated_env()打印DeprecationWarning提示迁移到新名称见 api.py但功能上仍完全可用——测试test_deprecated_env_vars_still_work_and_warn正是验证这一点设置TAVUS_REPLICA_IDoldf、TAVUS_PERSONA_IDoldp后请求 payload 中的face_id、pal_id仍被正确填充。快速接入AvatarSession 完整参数清单AvatarSession的构造签名见 avatar.py如下from livekit.plugins.tavus import AvatarSession avatar AvatarSession( face_id你的 face_id, # 数字人人脸 ID pal_id你的 pal_id, # Tavus PAL 形象 ID # replica_id..., # 已废弃face_id 的旧别名 # persona_id..., # 已废弃pal_id 的旧别名 api_urlhttps://tavusapi.com/v2, # 可选Tavus API 地址默认即此值 api_keyTAVUS_API_KEY, # 可选不传则读环境变量 avatar_participant_identitytavus-avatar-agent, # 可选数字人在房间内的身份 avatar_participant_nametavus-avatar-agent, # 可选数字人显示名称 )各参数说明face_idTavus 的人脸复制体ID决定数字人长相。默认值为源码中的DEFAULT_FACE_ID r4067604db72Lucy - Homephoenix-4.5。pal_idTavus PALPersona Avatar Layer配置 ID决定形象与行为层组合。默认值为DEFAULT_PAL_ID pb87e71797da。replica_id/persona_id一对废弃别名。replica_id→face_idpersona_id→pal_id。源码用_coalesce_with_deprecated()统一处理仅当新参数未提供时才使用旧名并在用到旧名时告警见 avatar.py。api_urlTavus API 根地址默认https://tavusapi.com/v2见 api.py一般无需修改。api_keyTavus API Key不传时回退到TAVUS_API_KEY环境变量。avatar_participant_identity/avatar_participant_name数字人作为房间 participant 的身份与显示名默认均为tavus-avatar-agent。conn_optionsAPIConnectOptions类型控制对 Tavus API 的调用超时与重试默认使用DEFAULT_API_CONNECT_OPTIONS。构造完成后将avatar传入你的AgentSession框架会在合适时机自动调用avatar.start(agent_session, room)即可开始会话。默认 PAL 与 Face 的智能兜底逻辑这是插件一个很贴心的设计即使你不指定任何形象参数也能直接跑通。TavusAPI.create_conversation()内部的默认值逻辑见 api.py为若既没有pal_id也没有extra_payload中的pal_id则自动填入内置的DEFAULT_PAL_ID并在未显式给出face_id时一并填入DEFAULT_FACE_ID若用户只给了face_id则保留默认 PAL 用户指定 Face若用户只给了pal_id则不再填face_id——因为用户自建的 PAL 自带默认 Face强塞默认 Face 反而会覆盖它若通过extra_payload整体覆盖了pal_id同样不会附加默认 Face。这一行为在 test_tavus.py 中有四组用例逐一验证test_no_pal_uses_default_pal_with_face_override、test_pal_id_only_skips_pal_creation_and_omits_face、test_defaults_to_stock_pal_and_face_when_neither_given、test_extra_payload_pal_keeps_its_own_face。测试同时断言整个过程不会额外调用创建 PAL 的接口说明默认 PAL 是 Tavus 平台内置的现成资源无需你预先创建。start() 内部数字人是如何加入房间的AvatarSession.start()见 avatar.py是插件最核心的执行链路共四步第一步校验 LiveKit 凭据。读取LIVEKIT_URL、LIVEKIT_API_KEY、LIVEKIT_API_SECRET或方法入参缺失即抛TavusException。第二步为数字人签发房间 Token。使用 LiveKit 的api.AccessToken以agent身份、identity 为tavus-avatar-agent签发room_joinTrue且限定roomroom.name的 grants并附加一个关键属性ATTRIBUTE_PUBLISH_ON_BEHALF 本地 Agent 的 participant identity见 avatar.py。这个属性授权数字人代表本地 Agent 发布音视频轨道是Agent 出镜权限层面的关键设计。第三步调用 Tavus API 创建会话。调用create_conversation()传入pal_id、face_id以及properties{livekit_ws_url: livekit_url, livekit_room_token: livekit_token}。Tavus 云端据此让数字人连入你的房间并把返回的conversation_id保存在self.conversation_id上供后续排障与扩展使用。第四步替换音频输出为 DataStream。通过agent_session.output.replace_audio_tail(DataStreamAudioOutput(...))见 avatar.py把 Agent 的 TTS 音频输出从本地扬声器链路切换为面向数字人的数据流DataStreamAudioOutput( roomroom, destination_identityself._avatar_participant_identity, # 发给数字人 participant sample_rateSAMPLE_RATE, # 24000 Hz wait_remote_trackrtc.TrackKind.KIND_VIDEO, # 等待数字人视频轨道就绪 )SAMPLE_RATE 24000为音频采样率常量见 avatar.py。DataStreamAudioOutput定义于框架层的 livekit-agents/livekit/agents/voice/avatar/_datastream_io.py它基于 LiveKit DataStream 主题lk.audio_stream将音频帧推送给远端数字人工作进程并通过lk.playback_finished、lk.playback_started、lk.clear_buffer等 RPC 实现播放状态回传与缓冲清空从而支撑打断interruption场景下音频的即时停止与重放。wait_remote_trackKIND_VIDEO则确保在数字人视频轨出现后才开始推送音频避免音画错位。基类AvatarSession的抽象契约avatar_identity、provider、start定义在 livekit-agents/livekit/agents/voice/avatar/_types.pyTavus 实现中provider返回tavusavatar_identity返回数字人 participant identity便于框架在房间内识别数字人轨道。底层 API 封装会话、PAL 与重试机制TavusAPI见 api.py负责与 Tavus REST API 通信默认地址https://tavusapi.com/v2通过x-api-key请求头携带密钥。它提供三个方法create_conversation()—— 创建数字人会话语返回conversation_id。请求体包含pal_id、face_id有值才发送、properties以及一个自动生成的conversation_name形如lk_conversation_shortuuidextra_payload可整体覆盖请求体字段。create_pal()—— 创建自定义 PAL 形象返回pal_id。源码中的默认请求体给出了 PAL 的典型结构见 api.py{ pal_name: name, # 不传则自动生成 lk_pal_shortuuid default_face_id: default_face_id, # 必填 pipeline_mode: echo, # 回声管线接收 TTS 音频驱动口型 layers: { transport: {transport_type: livekit}, # 传输层走 LiveKit }, }create_persona()—— 创建 persona 的废弃接口官方注释明确建议改用create_pal()调用时会打印告警它仍走旧的/personas端点。重试机制所有请求统一经_post()见 api.py按conn_options.max_retry进行重试重试间隔为conn_options.retry_interval连接超时取自conn_options.timeout。非 2xx 响应抛APIStatusError并附带状态码与响应体重试耗尽后抛APIConnectionError。这些行为由AgentSession传入的conn_optionsAPIConnectOptions控制默认值即框架的DEFAULT_API_CONNECT_OPTIONS。升级迁移提示新旧参数并存期如何安全过渡如果你在旧版本项目中看到replica_id、persona_id、TAVUS_REPLICA_ID、TAVUS_PERSONA_ID等命名请注意它们均为兼容性保留的废弃别名插件内部已统一映射到face_id/pal_id与TAVUS_FACE_ID/TAVUS_PAL_ID。迁移建议代码层面将replica_id替换为face_idpersona_id替换为pal_id环境变量层面将TAVUS_REPLICA_ID替换为TAVUS_FACE_IDTAVUS_PERSONA_ID替换为TAVUS_PAL_ID新旧参数同时传入时新参数优先且不会触发告警测试test_no_warning_when_new_and_deprecated_both_given验证了该行为弃用告警以DeprecationWarning形式通过logger.warning输出可在测试或 CI 中监听以发现存量用法。测试验证与进一步阅读插件的单元测试集中在 tests/test_tavus.py覆盖了本文提到的全部关键行为新旧参数映射与告警、环境变量回退链、默认 PAL/Face 兜底逻辑、以及AvatarSession构造时的参数解析如AvatarSession(face_idf9, pal_idp9)与废弃别名AvatarSession(replica_idr9, persona_idx9)的等价性。测试通过 mock_post断言请求 payload不依赖真实 Tavus 服务可直接在本地运行pytest livekit-plugins/livekit-plugins-tavus/tests/若想查看更多插件的对照实现可参考同目录下的 livekit-plugins-liveavatar同为 LiveKit 官方数字人方案以及 examples/avatar 示例中的AvatarSession用法示例选用 Lemonslice 数字人但AvatarSession的接入范式完全一致。完整理解DataStreamAudioOutput的协议细节可继续阅读 livekit-agents/livekit/agents/voice/avatar/_datastream_io.py 与 livekit-agents/livekit/agents/voice/avatar/_types.py。小结livekit-plugins-tavus的官方 README 虽短但其背后是一套完整的数字人接入协议环境变量TAVUS_API_KEY完成鉴权face_id/pal_id决定形象start()内部的 Token 签发 create_conversationDataStreamAudioOutput三步链路实现Agent 说话 → 数字人出镜对口型的实时闭环。掌握本文的参数体系与底层调用链即可在 LiveKit Agents 项目中快速、可靠地接入 Tavus 虚拟数字人。【免费下载链接】agentsA framework for building realtime voice AI agents ️项目地址: https://gitcode.com/GitHub_Trending/agen/agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考