SuperAPI AI 工具集

operating-livekit-agents

部署与运维

查看项目

更新于 10-15 21:41

技能介绍

用途:在智能体开发完成后,负责把它上线到生产并稳定运行——将版本发布到 LiveKit Cloud、回滚、管理密钥与配置、维持真实负载下的性能,并在不破坏现有运行的前提下变更。相关命令位于 lk agent 下,应阅读 lk agent --help 及各子命令帮助获取参数,本技能不重复列出。

部署:自托管 LiveKit 服务器不适用 lk agent deploy,需用自有工具(Docker、Kubernetes、systemd)以容器或进程方式发布,密钥放在环境变量中,服务端可查 lk docs get-page /home/self-hosting。项目目录通过 CLI 写入的配置文件(livekit.toml)绑定到某个智能体,在该目录执行命令无需指定 id。智能体以容器形式发布,CLI 可生成 Dockerfile 或使用预构建镜像;首次部署前先在本地运行容器启动命令(lk agent start),它是生产模式,带生产日志与停机排空,与 dev 模式不同。每次部署创建一个版本并逐步放量,status、versions、logs(构建日志与部署日志分开)可查看当前版本与失败原因。密钥以环境变量注入、与代码分开管理,不得写入镜像或提交;修改密钥会重启智能体。回滚可返回上一版本,速度取决于套餐。部署后用 status、日志和真实对话验证,可用 running-livekit-simulations 按名称对已部署智能体跑场景文件做端到端检查。

worker 进程模型:两个 SDK 都在父进程派生的 worker 子进程中运行会话,这是生产环境专属缺陷的最常见来源。父进程预热、子进程继承:把昂贵的只读资源(VAD、轮次检测模型、持久客户端)在父进程通过 prewarm 钩子加载一次,各会话继承而不重复加载;共享内容必须只读或并发安全,子进程修改父状态属未定义行为。不要预热会话专属状态,也不要预热内存开销大于收益的内容。要确认子进程确实使用了预热实例。框架掌管事件循环:不要在 worker 内新建异步运行时,也不要在同步构造函数中阻塞等待异步调用;需要异步初始化时改为首次使用时惰性加载,或把构造与 await 初始化分开。

提供商:STT、TTS、LLM、VAD 等在生产中都会失败(限流、超时、过载、故障)。要设置超时,区分可重试的瞬时失败与需要降级或升级的持续失败,降级为有意义的语音回复而非静默,并记录提供商响应时间。新增提供商前先查 SDK 是否已有插件,沿用代码库既有的初始化、配置与错误处理方式,并在真实时延下测试。

性能:用户感知的指标是首次出声时间,优化前先拆解连接、提供商初始化、首次推理、工具执行各段。注意反模式:异步上下文中的同步 I/O、通话中加载模型或连接、无摘要的无界上下文、不分对话阶段全局注册工具。端点检测与轮次检测是需调优的参数,应通过音频模拟测量而非凭感觉。

停机与升级:生产模式下收到终止信号会排空——停止接新任务、在排空超时内完成进行中任务后退出。编排器宽限期短于排空超时会中断通话,需保持一致;通话后工作(写状态、发事件、完成录制)必须绑定任务生命周期并在排空内完成。dev 模式无排空,停机行为须在 start 模式测试。SDK 版本迭代快且可能破坏兼容,应固定版本,升级前阅读变更日志,在分支上升级、跑测试、进行真实对话与模拟套件,部署后数小时关注时延与错误率。

可观测性:每条日志带会话 id 以便端到端追踪;对阶段边界(已连接、首次用户语音、首次智能体响应)计时;提供商指标与应用日志分开跟踪。LiveKit Cloud 提供智能体日志、会话洞察与可导出到自有观测平台的追踪。

排障:先分类再复现——循环与任务错误(查运行时创建或同步路径 await)、提供商超时与性能退化(单次超时属瞬时,时延上升属系统性)、工具静默失败(需显式错误处理返回模型可说的内容)、连接不稳定(先理解 SDK 内置重连再叠加重试)。随后本地复现(debugging-livekit-agents)、固化为测试(testing-livekit-agents),整段对话失败则加场景防止回归。

修改已上线代码库:先读项目自身文档与约定,读两三个同类模块再动手,沿用既有测试夹具与 mock 模式,在边界(提供商调用、数据库)打桩并运行真实模块逻辑。相关技能:building-livekit-agents、debugging-livekit-agents、testing-livekit-agents、running-livekit-simulations、reading-livekit-docs。