LiveKit Agents 接入 Smallest AIPulse 语音识别与 Lightning 语音合成的完整实战指南【免费下载链接】agentsA framework for building realtime voice AI agents ️项目地址: https://gitcode.com/GitHub_Trending/agen/agents导读本文讲解如何在 LiveKit Agents 框架中通过livekit-plugins-smallestai插件接入 Smallest AI 的语音能力一边是支持 39 种语言自动检测、流式转写的 Pulse 语音识别STT一边是提供 217 预置音色、支持 WebSocket 低延迟流式合成的 Lightning 语音合成TTS。读完本文你将掌握该插件的安装与 API Key 配置、STT/TTS 的完整参数语义与默认值、流式与批处理两条工作路径的底层调用链并能直接在实时语音 Agent 中组合使用。一、插件概览与仓库结构livekit-plugins-smallestai是 LiveKit Agents 官方插件体系livekit-plugins 目录下众多 provider 插件之一中对接 Smallest AI 的实现。从源码结构看该插件包非常精简核心代码集中在 livekit/plugins/smallestai 目录stt.pySTT类与SpeechStream类对应 Pulse 语音识别支持批处理 HTTP 与流式 WebSocket 两种模式tts.pyTTS类、ChunkedStreamHTTP 合成与SynthesizeStreamWebSocket 连续流式合成models.py模型与编码类型的类型别名定义init.py导出公共 API并注册SmallestAIPlugin插件version.py当前插件版本为1.8.0。依赖方面pyproject.toml 声明了livekit-agents[codecs]1.8.0与numpy1.26要求 Python 3.10。也就是说你只需安装插件本体即可获得全部 STT/TTS 能力无需额外引入其他 SDK。二、安装与前置条件2.1 安装pip install livekit-plugins-smallestai安装完成后from livekit.plugins import smallestai即可导入使用。插件在init.py 中通过Plugin.register_plugin(SmallestAIPlugin())完成自动注册同时导出STT、SpeechStream、TTS、ChunkedStream与__version__。2.2 获取并配置 API Key你需要一个 Smallest AI 的 API Key建议通过环境变量注入export SMALLEST_API_KEYyour_api_key_here源码中的取值逻辑是“显式参数优先环境变量兜底”在 stt.py 与 tts.py 中api_key api_key or os.environ.get(SMALLEST_API_KEY)两者都未提供时会直接抛出ValueError并提示你设置SMALLEST_API_KEY环境变量。因此你也可以在构造时显式传入api_key...参数例如从密钥管理服务动态读取。三、语音识别Pulse STTPulse 是 Smallest AI 的语音识别模型同时支持流式转写与批处理转写两种路径并内置 39 种语言的自动检测能力。3.1 基础用法from livekit.plugins import smallestai # 流式转写固定英文 stt smallestai.STT(languageen) # 自动语言检测覆盖 39 种语言 stt smallestai.STT(languagemulti)languagemulti模式下服务端会在is_final响应中回传实际检测到的语言从 stt.py 的源码看插件会把检测到的语言写进SpeechData.language供下游 LLM 或日志链路使用。3.2 完整构造参数STT构造器签名见 stt.py全部为关键字参数以下表格整理了每个参数的语义、取值与默认值参数默认值说明modelpulseSTT 模型。pulse支持流式与批处理覆盖 38 种语言pulse-pro是仅支持英文的高精度模型且仅限批处理——对其调用stream()会抛出ValueErrorlanguageenBCP-47 语言码如en、hi、fr传multi启用 39 语言自动检测pulse-pro只支持ensample_rate16000音频采样率支持 8000/16000/22050/24000/44100/48000encodinglinear16PCM 编码格式类型见 models.py可选linear16、linear32、alaw、mulaw、opus、ogg_opusword_timestampsTrue为每个词输出起止时间戳与置信度pulse与pulse-pro均支持diarizeFalse说话人分离。流式模式下每个词带整数 speaker ID批处理模式下为字符串标签eou_timeout_ms100服务端判定“话语结束”的静音阈值毫秒合法范围 100–10000。默认 100ms 使服务端 EOU 在 LiveKit 自身 end-of-turn 检测之上几乎不增加额外延迟若省略则回退到服务端 800ms 默认值endpointingTrue是否依据尾部静音直接定稿转写。开启时eou_timeout_ms作为上限关闭时仅依赖eou_timeout_ms触发定稿keywords未提供NOT_GIVEN热词加权格式为(keyword, intensifier)元组列表如[(NVIDIA, 2.0), (Jensen Huang, 1.0)]。intensifier 约 1.0轻微到 5.0强烈超过 5 有幻觉风险仅流式模式支持每会话最多 10000 个formatTrue为流式转写结果添加标点与大小写设为False可得到无标点小写原文适合 LLM/NLP 流水线或搜索引擎索引仅流式模式生效sentence_timestampsFalse输出句子级时间信息以utterances列表含text/start/end开启diarize时含speaker放入SpeechData.metadata[utterances]仅流式模式生效。批处理模式下只要开启word_timestamps就会自动附带redact_piiFalse用占位符如[FIRSTNAME_1]、[PHONENUMBER_1]遮蔽姓名、地址、电话号码匹配项同时写入SpeechData.metadata[redacted_entities]仅流式模式生效仅en/hi可靠redact_pciFalse遮蔽银行卡号、CVV、邮编、账号等支付信息如[CREDITCARDCVV_1]机制同上仅流式模式生效仅en/hi可靠api_keyNoneAPI Key缺省回退到SMALLEST_API_KEY环境变量http_sessionNone可复用的 aiohttpClientSessionbase_urlhttps://api.smallest.ai/waves/v1覆盖默认 API 基地址3.3 两条转写路径与底层实现从 stt.py 可见STT初始化时会依据模型是否在_STREAMING_MODELS {pulse}集合中来设置capabilities.streaming。这带来一个重要的框架行为当使用不支持流式的模型如pulse-pro时LiveKit Agents 框架会自动用StreamAdapter把批处理接口包装成流式接口上层 Agent 代码无需改动。批处理路径recognize()在_recognize_impl中插件把AudioBuffer通过rtc.combine_audio_frames(buffer).to_wav_bytes()编码为 WAV 字节流然后以application/octet-stream方式 POST 到{base_url}/stt/见 stt.py。响应中的transcription、words、utterances、language字段被组装成FINAL_TRANSCRIPT类型的SpeechEvent。流式路径stream()建立wss://api.smallest.ai/waves/v1/stt/live?model...的 WebSocket 连接见 stt.py。音频按 50ms 分块sample_rate // 20采样点/块发送插件用 5 秒心跳 Ping 保持连接会话结束时发送{type: close_stream}让服务端冲刷剩余音频并回传is_lastTrue。值得注意的细节是Pulse API 不主动上报“开始说话”因此插件在收到首个非空 transcript 时自行推断并派发START_OF_SPEECH事件见 stt.py。流式响应中is_finalFalse的消息被映射为INTERIM_TRANSCRIPT中间结果is_finalTrue的消息被映射为FINAL_TRANSCRIPT同时派发END_OF_SPEECH这套事件流与 LiveKit Agents 的端到端语音管线天然兼容。此外插件内部每 5 秒汇总一次音频时长通过RECOGNITION_USAGE事件上报用量见 stt.py可用于计费与监控。3.4 运行时动态调参STT.update_options(...)支持在运行期修改model、language、sample_rate、encoding、eou_timeout_ms、endpointing、keywords、format、sentence_timestamps、redact_pii、redact_pci等参数。从 stt.py 的实现看改动会同步到所有活跃流并触发流通过_reconnect_event重新建立 WebSocket 连接。这意味着你可以在对话中途根据用户语言或场景动态切换识别配置。3.5 实战建议追求低延迟保持默认endpointingTrueeou_timeout_ms100让 LiveKit 的 turn 检测负责收尾服务端 EOU 只作兜底提升专有名词准确率在keywords中加入品牌名、人名等热词注意 intensifier 不要超过 5合规脱敏涉及金融、医疗等敏感场景时开启redact_pii/redact_pci并把脱敏实体名单用于审计多语言场景直接使用languagemulti无需预判用户语言。四、语音合成Lightning TTSLightning 是 Smallest AI 的语音合成模型提供标准与 Pro 两档音色池支持 HTTP 一次性合成与 WebSocket 连续流式合成。4.1 基础用法from livekit.plugins import smallestai tts smallestai.TTS(voice_idemily)不传voice_id时源码会根据模型自动选择默认音色lightning_v3.1_pro默认meher其他模型默认sophia见 tts.py。4.2 完整构造参数TTS构造器签名见 tts.py参数默认值说明api_keyNoneAPI Key缺省回退到SMALLEST_API_KEY环境变量modellightning_v3.1_proTTS 模型。lightning_v3.1为标准模型217 个音色、12 种语言lightning_v3.1_pro默认为高级音色池精选美式/英式/印度口音原生 44.1kHzvoice_idNone音色 ID默认按模型取meherPro/sophia标准。注意 Pro 音色必须搭配lightning_v3.1_pro标准音色搭配lightning_v3.1sample_rate24000输出采样率。两个模型原生 44.1kHz支持 8000/16000/24000/44100speed1.0语速范围 0.5–2.0languageen合成语言传auto可自动检测并支持语码切换。Pro 模型仅支持en、hi、autooutput_formatpcmHTTPsynthesize()的输出格式pcm、mp3、wav、ulaw、alawWebSocket 流式始终返回 PCMword_timestampsFalse请求服务端按词上报时间事件并以TimedString形式随音频输出。仅 WebSocket 流式生效且仅 base-queue 英文印地语音色meher、devansh、kartik、maithili、liam、avery支持其他音色会静默不产生词事件max_buffer_flush_ms0WebSocket 连续流式协议的服务端缓冲上限毫秒。开启后服务端按文本缓冲时长强制产出部分音频无需等待显式 flush0表示关闭按时间强制冲刷。调高如 200–400可换取更少、更大的音频块牺牲少量延迟base_url/ws_urlhttps://api.smallest.ai/waves/v1/wss://api.smallest.ai/waves/v1/tts/live覆盖 HTTP 与 WebSocket 端点http_sessionNone可复用的 aiohttpClientSession4.3 两条合成路径HTTP 一次性合成synthesize()→ChunkedStream把文本连同模型、音色、采样率、语速、语言、输出格式以 JSON POST 到{base_url}/tts返回的原始字节按audio/{output_format}的 MIME 类型逐块推给AudioEmitter见 tts.py。适合短文本、无需首字延迟优化的场景或word_timestamps无需开启时使用。WebSocket 连续流式stream()→SynthesizeStream这是 Agent 主管线默认使用的高效路径。它基于 Waves 连续流式协议——文本 token 到达即转发continue: true不本地缓冲整段文本结束才发flush: true消息见 tts.py。这样合成可以在完整文本产生之前就开始显著降低首字节延迟time-to-first-byte。响应中的status字段驱动状态机chunk携带 base64 音频数据word_timestamp携带按词时间信息complete结束本段error抛出异常见 tts.py。插件内部用utils.ConnectionPool维护 WebSocket 连接池单条连接最长存活 3600 秒见 tts.py并暴露prewarm()方法允许在会话开始前预热连接从而跳过建立 WebSocket 的首包等待——这是实时语音场景中降低冷启动延迟的关键手段。4.4 运行时动态调参TTS.update_options(...)支持运行期修改model、voice_id、speed、sample_rate、language、output_format、word_timestamps、max_buffer_flush_ms见 tts.py。其中切换word_timestamps会同步更新capabilities.aligned_transcript从而影响 LiveKit Agents 是否将按词时间信息暴露给对齐转录aligned transcript模块。五、在实时语音 Agent 中组合使用把 STT 与 TTS 组合进 LiveKit Agents 的AgentSession即可构建一个完整的实时语音 Agent。以下是符合本插件公开 API 的典型用法import asyncio from livekit import agents from livekit.plugins import openai, silero, smallestai async def entrypoint(ctx: agents.JobContext): await ctx.connect() session agents.AgentSession( sttsmallestai.STT(languagemulti), # 39 语言自动检测 llmopenai.LLM(modelgpt-4o), ttssmallestai.TTS(voice_idemily), # Lightning 流式合成 vadsilero.VAD.load(), ) await session.start( roomctx.room, agentagents.LLMAgent(instructionsYou are a helpful assistant.), ) await asyncio.sleep(86400)在该管线中VAD 负责判定用户说话起止STT 输出INTERIM_TRANSCRIPT/FINAL_TRANSCRIPT事件驱动 LLM 回复LLM 输出再交给 TTS 流式合成并推送到房间。由于插件完整实现了 LiveKit Agents 的stt.STT/tts.TTS抽象基类SpeechStream、SynthesizeStream、ChunkedStream均为标准子类它可以在不修改业务代码的前提下与其他插件如 OpenAI LLM、Silero VAD自由组合并自动获得框架提供的断句tokenization、缓冲、重连与指标上报能力。需要进一步确认实现细节的读者可以直接阅读 stt.py 与 tts.py 的完整源码若想了解如何在更复杂的多 Agent 场景中编排语音管线仓库 examples 目录下的多个语音示例如 frontdesk、hotel_receptionist都提供了可供参考的AgentSession组装模式。六、小结livekit-plugins-smallestai以极薄的封装把 Smallest AI 的 Pulse STT 与 Lightning TTS 接入 LiveKit AgentsSTTpulse支持流式 批处理、39 语言自动检测、热词加权、句子/词级时间戳、PII/PCI 脱敏、说话人分离并支持运行期热更新TTSlightning_v3.1/lightning_v3.1_pro两档模型、217 音色、0.5–2.0 语速调节、WebSocket 连续流式协议与连接池预热满足实时对话的低延迟要求框架集成完整实现stt.STT/tts.TTS抽象自动获得 LiveKit 的断句、缓冲、重连、事件与用量上报能力可与其他 provider 插件自由混排。动手前记得先设置SMALLEST_API_KEY环境变量然后按需调整language、voice_id与eou_timeout_ms等关键参数即可快速构建属于自己的多语言实时语音 Agent。【免费下载链接】agentsA framework for building realtime voice AI agents ️项目地址: https://gitcode.com/GitHub_Trending/agen/agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考