尧图网站设计 尧图网站设计YAOTU DESIGN
ARTICLE DETAIL

资讯详情

深耕网站设计与一线实操的经验洞察。

从零搭建实时语音 AI 智能体:LiveKit Agents 完整实战指南

从零搭建实时语音 AI 智能体:LiveKit Agents 完整实战指南 从零搭建实时语音 AI 智能体LiveKit Agents 完整实战指南【免费下载链接】agentsA framework for building realtime voice AI agents ️项目地址: https://gitcode.com/GitHub_Trending/agen/agents想做一个能开口说话的助手用户开口它听懂、思考、回话还能调用工具、接打真实电话——这条链路该怎么搭LiveKit Agents 就是为这类运行在服务器上的实时语音智能体而生的 Python 框架下面带你从本地跑起来一路走到生产部署。先搞清楚实时语音智能体要解决什么传统聊天机器人只处理文本而语音场景多了几件棘手的事用户的话要变成文字STT语音识别、大模型要生成回复LLM、文字再变回语音TTS语音合成、还得判断用户到底说没说完、该不该打断对方。LiveKit Agents 把这些问题拆成可替换的模块围绕三个方向给出了答案模型自由组合STT、LLM、TTS 和端到端 Realtime API 可以任意混搭仓库里 70 多个模型服务商插件livekit-agents/ 核心库之外的 livekit-plugins/ 目录按需取用MCPModel Context Protocol一套让模型调用外部工具的标准协议服务器提供的工具也能一行代码接入交互体验打磨用 transformer 模型做语义级轮次检测判断用户是否说完当前一句话从而减少话没说完就被打断的误伤内置测试框架还能让另一个 LLM 当裁判judge评估智能体回答是否合格接入与部署框架自带任务调度负责把终端用户派给智能体客户端可用 LiveKit 各平台 WebRTC SDK 构建也能通过 telephony 栈直接拨打或接听电话借助 RPC 与 Data API智能体和前端可以交换结构化数据整条技术栈含 LiveKit WebRTC 媒体服务器本身全部开源可部署在自己的机房。安装只需一条命令方括号里的 extras 决定顺带装哪些模型插件pip install livekit-agents[openai,deepgram,cartesia]三步跑通最小语音助手第一步准备凭据。示例需要三个环境变量指向 LiveKit Cloud 或自建 LiveKit 服务器LIVEKIT_URL、LIVEKIT_API_KEY、LIVEKIT_API_SECRET。第二步写智能体。下面这个精简版可以直接运行from livekit.agents import (Agent, AgentServer, AgentSession, JobContext, RunContext, cli, function_tool, inference) function_tool async def lookup_weather(context: RunContext, location: str): Look up weather. return {weather: sunny, temperature: 70} server AgentServer() server.rtc_session() async def entrypoint(ctx: JobContext): session AgentSession( vadinference.VAD(), sttinference.STT(deepgram/nova-3, languagemulti), llminference.LLM(google/gemma-4-31b-it), ttsinference.TTS(cartesia/sonic-3, voicevoice-id), ) agent Agent(instructionsFriendly voice assistant, tools[lookup_weather]) await session.start(agentagent, roomctx.room) await session.generate_reply(instructionsgreet the user) if __name__ __main__: cli.run_app(server)几个关键动作值得展开function_tool把一个普通异步函数变成 LLM 可调用的工具docstring 成为工具说明类型标注的参数如location: str由模型自动填充context: RunContext则是框架注入的运行期上下文inference系列走 LiveKit Inference——通过 LiveKit Cloud 用统一 API 访问各家模型不用直接管理服务商 key。想用自己的 key换成deepgram.STT(...)、openai.LLM(...)、cartesia.TTS(...)插件即可session.start(agent..., room...)把智能体挂进会话并绑定ctx.room用户所在的 WebRTC 房间generate_reply(instructionsgreet the user)让智能体主动开口——这就是助手先打招呼的开场白模式不等用户先说话。第三步运行。在终端执行python myagent.py console即可在本地对话运行模式详见console、dev、start 怎么选一节。看懂框架的四块拼图上面的代码恰好覆盖框架的四个基本构件理解它们的关系就理解了框架架构构件职责白话理解Agent带明确指令instructions与工具的 LLM 应用助手的人设 技能清单AgentSession管理一次用户交互的容器驱动识别→思考→合成→播放的完整管道助手的耳朵和嘴entrypointserver.rtc_session()装饰的入口函数每来一个会话任务被调用一次类似 Web 服务器里的请求处理器AgentServer主进程负责任务调度job scheduling为每个用户会话拉起智能体总调度台四者的协作链是AgentServer 收到调度任务 → 调用 entrypoint 并注入JobContext→ entrypoint 里创建 AgentSession 和 Agent →session.start完成绑定。这些符号都在 livekit-agents/livekit/agents/ 根包顶层直接导出mcp等重依赖模块则按需懒加载。换模型、调体验工程化进阶配置最小示例跑通后真实对话体验往往差在细节上。参考实现 examples/voice_agents/basic_agent.py 展示了几个高频调优项都通过AgentSession的构造参数完成AgentSession( stt..., llm..., tts..., turn_handlingTurnHandlingOptions( interruption{ resume_false_interruption: True, # 误打断后自动恢复播放 false_interruption_timeout: 1.0, }, preemptive_generation{enabled: True, max_retries: 3}, ), aec_warmup_duration3.0, tts_text_transforms[filter_emoji, filter_markdown], stt_context_options{keyterms: [LiveKit], keyterm_detection: {enabled: True}}, )每一项对应一个具体场景误打断自动恢复背景噪声可能被误判成用户在插话导致助手突然停下。开启resume_false_interruption后若短时间内判定是误伤助手会自动把话说下去预生成降首字延迟preemptive_generation让 LLM 在等待用户说完的同时预先生成回复用户一停口就能立刻接上开播初期屏蔽打断aec_warmup_duration给客户端回声消除AEC几秒校准时间避免助手自己的声音被误当作用户输入TTS 文本变换合成前过滤 emoji 和 markdown 标记还能用replace自定义特定词的发音STT 上下文注入keyterm_detection由 LLM 自动识别对话中的高频专有名词注入 STT 上下文提高品牌词、术语的识别准确率。模型层面换大脑也很直接某个 Agent 构造时单独传llmopenai.realtime.RealtimeModel(voiceecho)就能把这一个智能体从STTLLMTTS 级联切换为端到端 Realtime API其余智能体不受影响。多个助手接力干活交接Handoff机制一次会话若需要角色分工——比如先有个信息收集员问清姓名和城市再交给故事讲述员讲故事——LiveKit Agents 的交接方式很直觉工具函数直接返回一个新的 Agent 实例框架就在当前会话内完成切换。class IntroAgent(Agent): async def on_enter(self): self.session.generate_reply(instructionsgreet the user) function_tool async def information_gathered( self, context: RunContext, name: str, location: str, ): Called once the users name and city are known. context.userdata.name name context.userdata.location location return StoryAgent(name, location), Lets start the story!三个要点工具即跳转返回元组(story_agent, 衔接话术)框架检测到返回值是 Agent 后切换活动智能体并播放第二项作为过渡语对话不冷场userdata 跨智能体共享AgentSession[StoryData]用类型参数声明会话级共享数据context.userdata让前一个助手把收集到的状态原样传给后继者单智能体覆盖模型管线StoryAgent构造时可传入自己的llm如 RealtimeModel并显式携带chat_ctx保留对话历史——交接的同时把级联模式升级为端到端模式。给智能体做体检内置测试框架LLM 输出是非确定的这次答对了不代表下次也对。框架把测试原语做成了链式断言一个完整用例长这样async with AgentSession(llmgoogle.LLM()) as sess: await sess.start(MyAgent()) result await sess.run(user_inputI need to place an order.) result.expect.next_event().is_function_call(namestart_order) result.expect.next_event().is_function_call_output() await (result.expect.next_event() .is_message(roleassistant) .judge(llm, intentassistant asks what the user would like))sess.run(user_input...)模拟一次用户输入驱动识别→LLM→工具调用→合成完整管线返回RunResultresult.expect提供链式事件断言校验工具名、校验工具执行完成、校验助手消息存在skip_next_event_if还能跳过模型偶尔多发的空消息这类不确定性分支真正难的是语义判断——助手是否询问了用户想点什么没法用字符串硬编码.judge(llm, intent...)就把这类断言交给裁判模型打分。需要脱离 AgentServer 做进程内测试时框架提供fake_job_context上下文管理器位于 livekit-agents/livekit/agents/testing.py它注入一个伪造的JobContext让代码里访问任务上下文的位置行为与真实任务一致可以直接配合真实房间session.start(...)。仓库自带的 tests/ 目录有数百个测试文件从打断恢复到预生成死锁等疑难路径都有覆盖是很好的写法范本。console、dev、start 怎么选三种运行模式对照cli.run_app(server)会根据最后一个参数暴露子命令三种模式覆盖从冒烟测试到生产的完整链路模式命令适用场景凭据要求consolepython myagent.py console终端里快速验证行为无需外部服务器devpython myagent.py dev配合 LiveKit 客户端 SDK / Playground 联调三个 LIVEKIT_* 环境变量startpython myagent.py start生产运行带生产级优化与优雅退出三个 LIVEKIT_* 环境变量底层机制的差异在 livekit-agents/livekit/agents/cli/cli.py 中看得很清楚行为视角console 不碰服务器它在独立线程里以server.run(devmodeTrue, unregisteredTrue)启动——worker 运行但不向服务器注册随后用server.simulate_job(console-room, fake_jobTrue)伪造一个任务来驱动 entrypoint音频则通过 TCP 音频输入/输出挂在本地控制台支持音频/文本两种模式与--record录制。这就是它零依赖的原因dev/start 走 worker 注册路径二者共用_run_worker——先按 CLI 参数--url/--api-key/--api-secret均声明了同名环境变量故环境变量等价于命令行参数调用server.update_options(...)再server.run(devmode...)向 LiveKit 服务器注册并等待任务分派。dev 模式传devmodeTrue日志更友好且一个进程可承载多个并发会话生产级优雅退出start 模式对停止信号的处理相当讲究——首次 SIGINT/SIGTERM 只是调度退出并执行 drain等在途语音会话结束--drain-timeout可配时长若 3 秒内事件循环仍被同步代码阻塞看门狗会升级为强制中断二次 CtrlC 才os._exit(1)硬退。这保证了滚动重启时不会粗暴截断正在进行的对话。一个版本现状提醒源码中对旧版 Python CLI 的console/dev部分子命令已标注 deprecated官方建议逐步迁移到 LiveKit CLI 的lk agent ...系列命令热重载等开发能力也在该工具链中提供选型时留意一下当前版本的提示信息。仓库自身的开发约定uv、pytest、ruff、pdoc如果你要二次开发或读源码仓库用 uv 管理依赖约定如下若需读源码可先git clone https://gitcode.com/GitHub_Trending/agen/agents装开发依赖uv sync --all-extras --dev跑示例创建examples/.env写入 LiveKit 与各模型服务商凭据模板见examples/.env.example然后uv run examples/voice_agents/basic_agent.py dev单元测试测试集中在 tests/ 目录uv run pytest --unit执行各插件的集成测试需要相应 API 凭据由 CI 在维护者 PR 上自动运行格式化与 Lintuv run ruff format与uv run ruff check --fix生成 API 文档uv run --active pdoc --skip-errors --html --output-dirdocs livekit需先uv sync --all-extras --group docs延伸阅读示例目录与许可证examples/ 目录是按场景组织的成套示例每个带 Dockerfile 的都可以容器化部署挑几个有代表性的示例看点examples/voice_agents/basic_agent.py面向语音对话优化的起步智能体进阶配置齐活examples/voice_agents/mcp/一行代码接入 MCP 服务器工具examples/other/transcription/multi-user-transcriber.py输出房间内所有用户的转写文本examples/avatar/基于 Tavus、Bithuman、LemonSlice 等的数字人视频智能体examples/telephony/电话 IVR、DTMF 按键、AMD应答检测等电话场景examples/hotel_receptionist/酒店前台策略文档 评测场景 工具集贴近业务落地的参考许可证框架本体采用 Apache-2.0见 LICENSE而 LiveKit 的轮次检测模型单独采用 LiveKit Model License见 MODEL_LICENSE。也就是说如果启用了语义级轮次检测模型侧许可条款与框架本体是分离的商用前需分别确认。小结LiveKit Agents 把实时语音智能体拆成四层可独立替换的构件AgentServer 管进程与调度AgentSession 管交互管道Agent 管指令、工具与生命周期STT/LLM/TTS/Realtime 模型则是即插即用的零件。配合 console 无服务器冒烟、dev/start 两种部署形态、RunResult.expect judge 的测试体系同一套代码可以走完从终端验证到生产调度的全过程——而examples/与核心库源码里每一层机制都有完整实现可以参考。【免费下载链接】agentsA framework for building realtime voice AI agents ️项目地址: https://gitcode.com/GitHub_Trending/agen/agents创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表