LiveKit Agents 实时语音 AI 框架工程化实操完整手册【免费下载链接】agentsA framework for building realtime voice AI agents ️项目地址: https://gitcode.com/GitHub_Trending/agen/agentsLiveKit Agents 是一个用于构建实时语音 AI 智能体的 Python 框架支持打断、工具调用与多供应商 STT/TTS/LLM 插件化接入。本文带你从环境搭建、代码质量门禁、Docker 化测试到容器化部署跑通这个仓库的完整工程工作流。 单仓多包布局先看清仓库结构仓库是一个 uv高性能 Python 包管理器负责依赖解析与环境同步管理的 monorepo。pyproject.toml 里的[tool.uv.workspace]声明了所有工作区成员livekit-agents/核心框架含 CLI、推理管线、voice 会话编排livekit-plugins/数十个 AI 供应商插件openai、google、deepgram、elevenlabs 等每个插件独立成包examples/语音、前台接待、虚拟形象等可运行示例tests/测试套件与 Docker 测试环境scripts/类型检查等辅助脚本理解这一点很关键插件与核心走的是workspace 源码链接tool.uv.sources中workspace true所以改插件代码后uv sync即可生效无需先发布。 本地环境一键搭建克隆仓库后git clone https://gitcode.com/GitHub_Trending/agen/agents在仓库根目录执行make doctor # 诊断环境检查 uv/python/git 版本、仓库结构、livekit 链接状态 make install # 安装全部依赖含开发依赖等价于 uv sync --all-extras --dev make status # 查看当前 livekit 包是 PyPI 版还是本地 editable 版make doctor会逐项报告问题数量并在发现缺失时以非零码退出适合作为 CI 前的第一道自检。make help可按分组列出全部 target不确定命令时先看它。 RTC 本地链接与版本切换框架依赖底层的 livekit-rtcRust 实现的实时通信库。如果你同时有 python-sdks 仓库可以把它链进来做底层联调make link-rtc— 下载预编译 FFI 产物并 editable 链接本地 python-rtc默认路径make link-rtc-local— 用 cargo 从源码构建 Rust SDK适合改底层 C 代码make link-rtc-version VERSION0.18.0— 从 PyPI 安装指定版本make unlink-rtc— 取消本地链接恢复 PyPI 版本⚠️make doctor检查 python-rtc 是否位于../python-sdks/livekit-rtc若目录结构不符会直接报错先按仓库约定摆放目录再执行链接命令。✅ 质量门禁format、lint、type-check 三件套静态检查全部由 makefile 收敛为单命令入口make format # ruff 格式化代码 make lint # ruff 静态检查 make type-check # 通过 scripts/check_types.py 运行 mypy make check # 串联 format-check lint type-check提交前跑这一条即可 make fix # 自动修复格式化与 lint 问题配置同样集中在 pyproject.tomlruff 设line-length 100、target-version py310lint 规则选了 pycodestyle、pyflakes、isort、bugbear、pyupgrade 及 asyncio 悬挂任务检测RUF006mypy 开启strict true并挂 pydantic 插件。CONTRIBUTING.md 明确要求 PR 前先本地跑make check这条命令就是事实上的合入门禁。 Docker Compose 化测试环境tests/docker-compose.yml 提供了一套隔离的测试环境两个服务app基于 tests/Dockerfile.tests 构建挂载 tests、livekit-agents、livekit-plugins 与 uv.lock 实现代码热重载toxiproxy故障注入代理混沌测试工具可模拟延迟/断连各供应商 API 域名通过extra_hosts指向它方便在测试里模拟网络劣化执行流程cd tests make up # 启动环境若仓库根有 .env 会自动加载其中的 API 密钥 make test # 等待 toxiproxy 就绪后在容器内跑 pytest结束自动 down make down # 停止环境测试集本身按 marker 分类声明在 pyproject.toml 的[tool.pytest.ini_options]unit无外部依赖的快测试、plugin(name)、stt(name)、tts(name)、realtime(name)、evals行为评测、docs。tests/conftest.py 把每个 marker 注册为--选项因此可以按需切片uv run pytest --unit # 只跑无云账号的单元测试 uv run pytest --stt openai # 只跑 OpenAI 的 STT 集成测试 uv run pytest --list-categories # 列出全部测试模块按分类分组不执行⚠️ conftest 强制每个测试模块必须声明类别 marker未分类的模块默认会被拦截可用--allow-uncategorized临时放行。新增测试文件前先给模块加上pytestmark。 CI/CD 与发布流水线.github/workflows/ 下按职责拆分了十余条流水线核心几条tests.ymlpush/PR 触发含跨平台 blockguard 测试、unit-testsuv sync后执行make unit-tests仅跑--unit --audio_eot两类别无需云账号、evaluation行为评测ci.yml常规代码质量检查publish.yml 与 publish-docs.yml分别负责发包与文档构建release-gate.yml版本发布门禁注意 fork 仓库的 PR 不跑带密钥的集成测试workflow 里显式判断fork false这是常见的密钥泄漏防护做法。本地跑单测与 CI 保持一致的方式同样是make unit-tests等价于pytest --unit --audio_eot。 容器化部署你的 Agent生产部署以 examples/Dockerfile-example 为参考模板几个值得照搬的细节基于python:3.11.6-slim设PYTHONDONTWRITEBYTECODE1与PYTHONUNBUFFERED1前者减小镜像、后者避免日志被缓冲创建非特权用户appuserUID 10001运行应用构建期执行python -m livekit.agents download-files把依赖的模型文件提前下载进镜像避免运行时拉取框架侧的可观测性开箱即用livekit-agents/livekit/agents/metrics/ 提供使用量与性能指标采集livekit-agents/livekit/agents/telemetry/ 负责事件遥测与 PII 脱敏上报。接入自己的监控系统时从这里拿指标口径即可。克隆仓库后建议先跑make doctor验证环境健康再执行make unit-tests确认本地测试能绿之后用uv run pytest --list-categories浏览测试分类按你要集成的供应商挑--stt/--tts切片跑通集成用例就可以开始写自己的 Agent 了。【免费下载链接】agentsA framework for building realtime voice AI agents ️项目地址: https://gitcode.com/GitHub_Trending/agen/agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 LiveKit Agents 实时语音 AI 框架：工程化实操完整手册
LiveKit Agents 实时语音 AI 框架工程化实操完整手册【免费下载链接】agentsA framework for building realtime voice AI agents ️项目地址: https://gitcode.com/GitHub_Trending/agen/agentsLiveKit Agents 是一个用于构建实时语音 AI 智能体的 Python 框架支持打断、工具调用与多供应商 STT/TTS/LLM 插件化接入。本文带你从环境搭建、代码质量门禁、Docker 化测试到容器化部署跑通这个仓库的完整工程工作流。 单仓多包布局先看清仓库结构仓库是一个 uv高性能 Python 包管理器负责依赖解析与环境同步管理的 monorepo。pyproject.toml 里的[tool.uv.workspace]声明了所有工作区成员livekit-agents/核心框架含 CLI、推理管线、voice 会话编排livekit-plugins/数十个 AI 供应商插件openai、google、deepgram、elevenlabs 等每个插件独立成包examples/语音、前台接待、虚拟形象等可运行示例tests/测试套件与 Docker 测试环境scripts/类型检查等辅助脚本理解这一点很关键插件与核心走的是workspace 源码链接tool.uv.sources中workspace true所以改插件代码后uv sync即可生效无需先发布。 本地环境一键搭建克隆仓库后git clone https://gitcode.com/GitHub_Trending/agen/agents在仓库根目录执行make doctor # 诊断环境检查 uv/python/git 版本、仓库结构、livekit 链接状态 make install # 安装全部依赖含开发依赖等价于 uv sync --all-extras --dev make status # 查看当前 livekit 包是 PyPI 版还是本地 editable 版make doctor会逐项报告问题数量并在发现缺失时以非零码退出适合作为 CI 前的第一道自检。make help可按分组列出全部 target不确定命令时先看它。 RTC 本地链接与版本切换框架依赖底层的 livekit-rtcRust 实现的实时通信库。如果你同时有 python-sdks 仓库可以把它链进来做底层联调make link-rtc— 下载预编译 FFI 产物并 editable 链接本地 python-rtc默认路径make link-rtc-local— 用 cargo 从源码构建 Rust SDK适合改底层 C 代码make link-rtc-version VERSION0.18.0— 从 PyPI 安装指定版本make unlink-rtc— 取消本地链接恢复 PyPI 版本⚠️make doctor检查 python-rtc 是否位于../python-sdks/livekit-rtc若目录结构不符会直接报错先按仓库约定摆放目录再执行链接命令。✅ 质量门禁format、lint、type-check 三件套静态检查全部由 makefile 收敛为单命令入口make format # ruff 格式化代码 make lint # ruff 静态检查 make type-check # 通过 scripts/check_types.py 运行 mypy make check # 串联 format-check lint type-check提交前跑这一条即可 make fix # 自动修复格式化与 lint 问题配置同样集中在 pyproject.tomlruff 设line-length 100、target-version py310lint 规则选了 pycodestyle、pyflakes、isort、bugbear、pyupgrade 及 asyncio 悬挂任务检测RUF006mypy 开启strict true并挂 pydantic 插件。CONTRIBUTING.md 明确要求 PR 前先本地跑make check这条命令就是事实上的合入门禁。 Docker Compose 化测试环境tests/docker-compose.yml 提供了一套隔离的测试环境两个服务app基于 tests/Dockerfile.tests 构建挂载 tests、livekit-agents、livekit-plugins 与 uv.lock 实现代码热重载toxiproxy故障注入代理混沌测试工具可模拟延迟/断连各供应商 API 域名通过extra_hosts指向它方便在测试里模拟网络劣化执行流程cd tests make up # 启动环境若仓库根有 .env 会自动加载其中的 API 密钥 make test # 等待 toxiproxy 就绪后在容器内跑 pytest结束自动 down make down # 停止环境测试集本身按 marker 分类声明在 pyproject.toml 的[tool.pytest.ini_options]unit无外部依赖的快测试、plugin(name)、stt(name)、tts(name)、realtime(name)、evals行为评测、docs。tests/conftest.py 把每个 marker 注册为--选项因此可以按需切片uv run pytest --unit # 只跑无云账号的单元测试 uv run pytest --stt openai # 只跑 OpenAI 的 STT 集成测试 uv run pytest --list-categories # 列出全部测试模块按分类分组不执行⚠️ conftest 强制每个测试模块必须声明类别 marker未分类的模块默认会被拦截可用--allow-uncategorized临时放行。新增测试文件前先给模块加上pytestmark。 CI/CD 与发布流水线.github/workflows/ 下按职责拆分了十余条流水线核心几条tests.ymlpush/PR 触发含跨平台 blockguard 测试、unit-testsuv sync后执行make unit-tests仅跑--unit --audio_eot两类别无需云账号、evaluation行为评测ci.yml常规代码质量检查publish.yml 与 publish-docs.yml分别负责发包与文档构建release-gate.yml版本发布门禁注意 fork 仓库的 PR 不跑带密钥的集成测试workflow 里显式判断fork false这是常见的密钥泄漏防护做法。本地跑单测与 CI 保持一致的方式同样是make unit-tests等价于pytest --unit --audio_eot。 容器化部署你的 Agent生产部署以 examples/Dockerfile-example 为参考模板几个值得照搬的细节基于python:3.11.6-slim设PYTHONDONTWRITEBYTECODE1与PYTHONUNBUFFERED1前者减小镜像、后者避免日志被缓冲创建非特权用户appuserUID 10001运行应用构建期执行python -m livekit.agents download-files把依赖的模型文件提前下载进镜像避免运行时拉取框架侧的可观测性开箱即用livekit-agents/livekit/agents/metrics/ 提供使用量与性能指标采集livekit-agents/livekit/agents/telemetry/ 负责事件遥测与 PII 脱敏上报。接入自己的监控系统时从这里拿指标口径即可。克隆仓库后建议先跑make doctor验证环境健康再执行make unit-tests确认本地测试能绿之后用uv run pytest --list-categories浏览测试分类按你要集成的供应商挑--stt/--tts切片跑通集成用例就可以开始写自己的 Agent 了。【免费下载链接】agentsA framework for building realtime voice AI agents ️项目地址: https://gitcode.com/GitHub_Trending/agen/agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考