LiveKit Agents 接入 Cerebras 高速推理livekit-plugins-cerebras 完整实战指南【免费下载链接】agentsA framework for building realtime voice AI agents ️项目地址: https://gitcode.com/GitHub_Trending/agen/agents导读livekit-plugins-cerebras是 LiveKit Agents 生态中接入 Cerebras、models.py与 官方 README 为依据完整讲解安装、鉴权、模型选型、AgentSession 集成以及插件独有的 gzip 压缩与 msgpack 编码请求体优化能力帮助你在一小时内把 Cerebras 模型接入自己的实时语音 Agent。一、插件定位为什么在 LiveKit 中需要 Cerebras 插件LiveKit Agents 是一个构建实时语音/视频 AI Agent 的框架其架构中 LLM大语言模型负责对话的「大脑」部分理解用户输入、决定是否调用工具、生成回复文本。LiveKit 通过插件体系对接各家模型提供商每个插件通常封装了该提供商的 API 客户端、模型清单和 LiveKit 抽象llm.LLM的实现。livekit-plugins-cerebras正是这一体系中的 Cerebras 接入层其核心价值在于极低的首 token 延迟TTFTCerebras 以其专用 Wafer Scale Engine晶圆级引擎硬件提供高速推理非常适合对延迟敏感的实时语音对话场景与 LiveKit AgentSession 无缝集成插件导出的LLM类直接实现了 LiveKit 的llm.LLM抽象继承自livekit.plugins.openai.LLM可直接作为AgentSession的llm参数使用额外的请求体优化这是该插件区别于普通 OpenAI 兼容插件的独有特性——对请求载荷做 gzip 压缩与 msgpack 二进制编码进一步压低大 Prompt 场景下的传输耗时。从源码结构看llm.pyLLM类直接继承 LiveKit 官方的 OpenAI 插件LLM因此 Cerebras 的 API 也遵循 OpenAI 兼容协议所有 OpenAI 插件的既有能力函数调用、流式输出、结构化输出等都可直接复用。二、安装官方 README 给出的安装命令为pip install livekit-plugins-cerebras从插件的 pyproject.toml 可以确认其依赖与运行环境要求依赖/约束版本要求说明Python3.10.0插件最低支持的 Python 版本livekit-agents1.8.0且需要codecs与openai两个 extra提供 LiveKit Agents 运行时与 OpenAI 兼容协议实现openai2.16.0底层 HTTP 客户端_CerebrasClient._build_request依赖 2.16.0 引入的FinalRequestOptions.content字段二进制请求流式传输支持msgpack1.0请求体 msgpack 编码msgpack-types0.7.0msgpack 类型标注如果你使用 uv 管理项目同样可以安装到项目依赖中当前仓库即采用 uv.lock 锁定依赖。安装完成后插件会在导入时自动通过Plugin.register_plugin(CerebrasPlugin())完成注册见 __init__.py并暴露LLM与__version__两个公共符号。注意本文所述版本以当前仓库为准__version__目前为1.8.0见 version.py。请以安装时的实际发布版本为准。三、前置条件账户与 API Key官方 README 明确要求For credentials, youll need a Cerebras account and API key. Credentials can be passed directly or viaCEREBRAS_API_KEYenvironment variable.也就是说使用本插件前你需要注册一个 Cerebras 账户并创建 API Key通过以下两种方式之一提供凭据环境变量推荐设置CEREBRAS_API_KEY构造参数实例化LLM时直接传api_key...。源码 llm.py 中的_get_api_key函数完整实现了这一逻辑def _get_api_key(key: NotGivenOr[str]) - str: cerebras_api_key key if is_given(key) else os.environ.get(CEREBRAS_API_KEY) if not cerebras_api_key: raise ValueError( CEREBRAS_API_KEY is required, either as argument or set CEREBRAS_API_KEY environmental variable ) return cerebras_api_key关键行为优先使用构造参数传入的api_key其次读取CEREBRAS_API_KEY环境变量两者都缺失时立即抛出ValueError而不是在请求时才报错便于在 Agent 启动阶段快速暴露配置问题。四、支持的模型插件在 models.py 中以Literal类型声明了当前支持的 Cerebras 模型CerebrasChatModels Literal[ gpt-oss-120b, zai-glm-4.7, gemma-4-31b, ]模型 ID说明gpt-oss-120b默认模型。GPT-OSS 开源 120B 模型Cerebras 提供的高速推理主力模型zai-glm-4.7智谱 GLM 4.7 开源模型gemma-4-31bGoogle Gemma 系列 4 开源模型LLM构造函数的model参数同时接受str与CerebrasChatModels两种类型llm.py因此既可以使用上述字面量也可以传入 Cerebras 控制台支持的其他模型字符串请以 Cerebras 官方文档实际开放的模型为准。五、快速上手把 Cerebras LLM 接入 AgentSession5.1 最小示例按照 LiveKit Agents 的标准用法LLM实例直接作为AgentSession的llm参数from livekit import agents from livekit.plugins.cerebras import LLM async def entrypoint(ctx: agents.JobContext): await ctx.connect() session agents.AgentSession( llmLLM(modelgpt-oss-120b), # 模型可省略默认即 gpt-oss-120b ) await session.start( roomctx.room, agentagents.Agent(sessionsession), )也可以把模型、Agent 与工具函数注册session.on(function_call)等组合起来形成完整的实时对话 Agent——这与 LiveKit Agents 框架中其他 LLM 插件的用法完全一致你可以在仓库的 examples 目录中找到大量 Agent 编写的参考范例。5.2 构造函数完整参数结合源码 llm.pyLLM的完整参数如下参数默认值类型说明modelgpt-oss-120bstr \| CerebrasChatModels使用的 Cerebras 模型api_keyNOT_GIVENNotGivenOr[str]Cerebras API Key缺省时读取CEREBRAS_API_KEYbase_urlhttps://api.cerebras.ai/v1NotGivenOr[str]API 端点一般无需修改clientNoneopenai.AsyncClient \| None自定义 OpenAI AsyncClient传入后不再自动创建userNOT_GIVENNotGivenOr[str]请求中携带的用户标识temperatureNOT_GIVENNotGivenOr[float]采样温度parallel_tool_callsNOT_GIVENNotGivenOr[bool]是否允许并行函数调用tool_choiceNOT_GIVENNotGivenOr[ToolChoice]工具选择策略如强制指定某工具reasoning_effortNOT_GIVENNotGivenOr[ReasoningEffort]推理强度适用于支持推理的模型safety_identifierNOT_GIVENNotGivenOr[str]安全标识prompt_cache_keyNOT_GIVENNotGivenOr[str]Prompt 缓存键用于缓存复用top_pNOT_GIVENNotGivenOr[float]核采样参数max_completion_tokensNOT_GIVENNotGivenOr[int]单次补全的最大 token 数timeoutNonehttpx.Timeout \| NoneHTTP 超时缺省为connect15s, read5s, write5s, pool5smax_retriesNOT_GIVENNotGivenOr[int]失败重试次数缺省为 0gzip_compressionTruebool是否对请求体做 gzip 压缩msgpack_encodingTruebool是否用 msgpack 二进制格式编码请求体其中与普通 OpenAI 插件最不同的两个参数是gzip_compression与msgpack_encoding默认均为True下一节专门展开讲解其原理。5.3 完整配置示例一个同时配置了鉴权、模型、采样与工具行为的示例from livekit import agents from livekit.plugins.cerebras import LLM llm LLM( modelzai-glm-4.7, api_keyYOUR_CEREBRAS_API_KEY, # 也可改用环境变量 CEREBRAS_API_KEY temperature0.7, top_p0.9, max_completion_tokens1024, max_retries3, # 请求失败自动重试 3 次 gzip_compressionTrue, # 开启请求体 gzip 压缩 msgpack_encodingTrue, # 开启 msgpack 编码 )六、深度原理gzip msgpack 请求体优化这是livekit-plugins-cerebras相对其他 OpenAI 兼容插件最值得一提的实现细节。源码中定义了一个_CerebrasClient类llm.py它继承自openai.AsyncClient重写了_build_request()方法在请求发出前对请求载荷做两种优化6.1 msgpack 二进制编码if self._use_msgpack: body msgpack.packb(json_data) content_type application/vnd.msgpack else: body json.dumps(json_data, separators(,, :), ensure_asciiFalse).encode() content_type application/json开启时请求体从 JSON 文本切换为 msgpack 二进制格式Content-Type变为application/vnd.msgpack与 JSON 相比msgpack 体积更小、序列化/反序列化更快能减少大 Prompt 场景下的传输字节数代码注释特别说明直接对json_data做packb避免了「JSON → dict → msgpack」的二次往返转换。6.2 gzip 压缩if self._use_gzip: body gzip.compress(body, compresslevel5) # 切换为二进制内容路径绕过 openapi_dumps() options.json_data None options.extra_json None options.content body overrides: dict[str, str] {Content-Type: content_type} if self._use_gzip: overrides[Content-Encoding] gzip options.headers existing | overrides在 msgpack或 JSON编码之后再叠加 gzip 压缩压缩级别为 5体积与 CPU 开销的折中请求头追加Content-Encoding: gzip服务端解压后按 msgpack/JSON 解码为了走二进制内容通道代码将options.json_data置空、把压缩后的字节写入options.content——这正是pyproject.toml要求openai2.16.0的原因该版本才支持FinalRequestOptions.content字段见 pyproject.toml 的注释。6.3 何时生效、何时关闭_CerebrasClient仅在两种情况下被自动创建llm.py你没有传入自定义client且gzip_compression或msgpack_encoding至少有一个为True。如果传入自定义client或同时把两个开关都设为False则请求按普通 OpenAI 兼容 JSON 方式发送。因此默认配置两者均 True适合绝大多数场景尤其是 Prompt 较大的 Agent知识库、长系统提示词可显著降低 TTFT若你的 Cerebras 端点/代理不支持 gzip 或 msgpack可通过gzip_compressionFalse, msgpack_encodingFalse关闭或直接传入自定义 client。关于优化效果的量化数据仓库源码仅说明「可以降低大 Prompt 请求的 TTFTcan reduce TTFT for requests with large prompts」本文不引入任何未经仓库证实的性能数字。七、其他使用细节与注意事项7.1 与 OpenAI 插件的关系LLM继承自livekit.plugins.openai.LLM构造时向父类传递了_strict_tool_schemaFalsellm.py并对tool_choice、parallel_tool_calls、reasoning_effort、prompt_cache_key等参数做了透传。这意味着你在 OpenAI 插件上熟悉的工具调用、流式输出等能力在 Cerebras 上同样可用但函数调用的 schema 校验采用非严格模式。7.2 超时与连接池插件自动创建的 httpx 客户端默认超时为connect15.0s, read5.0s, write5.0s, pool5.0s连接池上限为 50max_connections50, max_keepalive_connections50, keepalive_expiry120。这些与父类 OpenAI 插件的默认值一致可通过timeout参数覆盖。7.3 日志与插件注册插件的日志器名称为livekit.plugins.cerebras见 log.py排查问题时可开启对应级别的日志导入livekit.plugins.cerebras包即完成插件注册无需额外注册步骤仓库环境变量LK_OPENAI_DEBUG亦可作用于父类OpenAI 插件用于输出请求调试信息。7.4 运行前提需要 Python 3.10 与livekit-agents1.8.0需要 Cerebras API Key该插件是模型插件通过你的 Cerebras 账户直接调用 API与 LiveKit Cloud 的 Inference 服务无需各提供商独立 Key是两条并行的接入路径。若你想避免为每家提供商单独申请 Key可参考仓库中关于 LiveKit Inference 的介绍见 livekit-inference.md但两者不可混淆本插件要求持有 Cerebras 自身账户与 Key。八、小结livekit-plugins-cerebras以极小的接入成本把 Cerebras 的高速推理带进了 LiveKit Agents一键安装pip install livekit-plugins-cerebras一个 Key 搞定鉴权CEREBRAS_API_KEY环境变量或api_key参数缺省即抛错防呆模型即插即用默认gpt-oss-120b另支持zai-glm-4.7、gemma-4-31b天然适配实时语音继承 OpenAI 插件全部能力且默认开启 gzip msgpack 请求体优化为低延迟语音对话进一步减负。如需深入了解 LiveKit Agents 的 LLM 集成全貌可继续阅读仓库根目录的 README.md 与 AGENTS.md或参考 examples 目录下的各类 Agent 示例。【免费下载链接】agentsA framework for building realtime voice AI agents ️项目地址: https://gitcode.com/GitHub_Trending/agen/agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考