WhisperLiveKit 服务器配置完全指南从 CLI 参数到 Python 嵌入式部署【免费下载链接】WhisperLiveKitReal-time, local speech-to-text with streaming ASR, speaker diarization, translation, and OpenAI/Deepgram-compatible APIs.项目地址: https://gitcode.com/GitHub_Trending/wh/WhisperLiveKit导读WhisperLiveKit 是一个实时、本地优先的语音转写服务提供流式 ASR、说话人分离、翻译以及 OpenAI/Deepgram 兼容 API。本文以 docs/configuration.md 为骨架系统梳理服务器端全部配置项——从wlk serve的命令行参数、解码与会话上下文策略到长会话内存管理、背压控制与 Python 嵌入式部署并结合仓库源码whisperlivekit/config.py、whisperlivekit/parse_args.py、whisperlivekit/basic_server.py逐项印证参数的真实语义。读完本文你将能独立完成从「选后端、定模型」到「调解码策略、控内存边界、嵌入 ASGI 应用」的完整配置闭环。配置入口总览两条等价路径WhisperLiveKit 提供两个完全对齐的配置入口CLI 方式wlk serve --help是完整的命令行参考所有参数均以--前缀的长选项形式暴露。Python 方式通过类型化的WhisperLiveKitConfigdataclass 构造配置对象。该类的所有字段都有与 CLI 默认值一致的默认值且from_namespace()方法负责把 argparse 的解析结果映射为配置对象。一个值得注意的细节是--model对应的内部字段名是model_size见 parse_args.py 中destmodel_size--language/--lan对应的内部字段是lan--translation-backend的取值在 CLI 层面为nllb、alignatt、mlx-llm-mt、hunyuan-mlx四选一。因此无论走哪条路径最终都汇聚到同一个 dataclass 实例——这就是「examples below use the same settings as the CLI」的底层含义。常用设置一张表掌握核心参数下表完整收录 docs/configuration.md 中 Common settings 的全部选项并补充了源码层面的取值约束默认值与 config.py 中的字段声明一一对应OptionPurposeDefault--backendASR 实现可选auto、mlx-whisper、faster-whisper、whisper、openai-api、funasr、voxtral、voxtral-mlx、qwen3-vllm、qwen3-vllm-metal、qwen3-streaming、canary详见 backendsauto--model所选后端的模型大小或名称如base、small.en、large-v3-turbobase--language源语言覆盖范围取决于后端auto表示自动检测auto--backend-policyWhisper 流式策略simulstreamingAlignAtt或localagreement也接受数字别名1/2simulstreaming--target-language启用向该语言的翻译如zh、frdisabled--translation-backendnllb、AlignAtt4LLM 服务器、或本地 MLX 翻译nllb--diarization将词归属到说话人启用说话人分离disabled--pause-segmentation-secondsVAD 停顿超过该阈值秒数后切分稳定边界0禁用5.0--asr-coalesce-min-s累积新音频后再做推理用更新节奏换取更少的编码器调用0--max-buffered-audio每个 ASR/说话人分离阶段可排队的最大音频秒数30--backpressure-timeout等待处理队列腾出空间的超时秒数30--pcm-input接受单声道 16 kHz 有符号 16 位小端 PCM 输入绕过 FFmpegdisabled--api-token要求认证未设置时回退到环境变量WLK_API_TOKENunset--cors-origins允许调用 API 的浏览器来源逗号分隔none--host/--port监听地址localhost/8000参数背后的源码约束几个「表里看不出来」的约束值得专门说明max_buffered_audio与backpressure_timeout必须为有限正数。config.py 的__post_init__会对二者做math.isfinite()且 0的校验非法值直接抛出ValueError。pause_segmentation_seconds必须有限且非负validate_pause_segmentation_secondsconfig.py。.en后缀会强制语言当后端不是funasr且模型名以.en结尾如base.en时配置会自动把lan置为enconfig.py。--backend-policy的数字别名1自动归一为simulstreaming2归一为localagreementconfig.py。FunASR 后端的硬约束FunASR 只支持 LocalAgreement 策略选择它时策略被自动切换或直接报错、只支持{auto, zh, yue, en, ja, ko}语言集合、不支持direct_english_translation、buffer_trimmingsentence时不允许languageautoconfig.py。--sortformer-max-speakers仅在--diarization-backend sortformer下可用取值必须是 14 的整数代表「会话最多有 N 个说话人」超出保留标签的归属行为未定义config.py。CORS 解析parse_cors_origins把逗号分隔字符串拆分为列表空串禁用 CORS*允许所有来源config.py。后端专属的模型路径、语言限制与可选依赖详见 docs/backends.md 与 docs/default_and_custom_models.md。解码与会话上下文SimulStreaming 策略的解码方式按波束数自动选择--beams 1时使用贪心解码greedy更多波束时使用束搜索beam search。--decoder beam或--decoder greedy可覆盖自动选择但greedy 要求波束数必须为 1两者冲突时配置无效。Whisper 上下文由三个参数共同控制--init-prompt初始提示词应使用目标语言书写会随上下文滚动--static-init-prompt静态提示词不参与滚动适合存放全文通用的术语表--max-context-tokens上下文的最大 token 数上限。不同后端的上下文支持能力不同会话建立时服务器会通过context能力字段向客户端声明当前后端是否支持上下文见 basic_server.py 中session_context_capability的调用。不支持的上下文会在处理音频之前被拒绝。会话级参数覆盖原生 WebSocket 端点/asr允许每个会话通过查询参数覆盖服务器默认值源码见 basic_server.pylanguage覆盖源语言target_language覆盖翻译目标语言modefull或diff差分协议见下文context会话级上下文文本。REST 接口则使用language与prompt字段表达同类意图。协议细节见 docs/API.md。若传入的参数非法如后端不支持的语言AudioProcessor构造阶段会抛出ValueError服务器在握手后立刻以4400关闭码 错误消息拒绝该会话而不是等到音频到达才失败basic_server.py。兼容性遗留选项旧的--punctuation-split与--disable-punctuation-split两个开关被保留用于向后兼容但已无任何效果启用时会打印弃用警告。真正的转写边界现在由两件事控制说话人分离的说话人轮次speaker turns与--pause-segmentation-seconds的停顿切分。__post_init__中的警告逻辑见 config.py。长会话与文件请求内存与超时预算转写历史保留retention--retention-seconds设置服务器端保留的转写历史时长。默认行为依赖会话模式modefull无覆盖时保留全部转写历史每次更新向客户端发送完整转写modediff无覆盖时服务器只保留300 秒历史客户端必须自行维护累积转写。显式指定0或负值表示无上限保留。注意 full 模式下设置有限 retention 会有意地从后续响应中移除更早的行。该逻辑在 whisperlivekit/tokens_alignment.py 的resolve_retention_seconds()中集中实现显式值始终优先None时才按模式取默认full 无上限、diff 300 秒。REST 文件请求的硬性边界OpenAI 兼容的 REST 端点/v1/audio/transcriptions对文件请求施加了明确预算编码后的音频最多512 MB_MAX_AUDIO_BYTES 512 * 1024 * 1024见 basic_server.pyPCM 转换后同样最多512 MB超限返回 HTTP413basic_server.py转换过程默认120 秒超时后续流水线预算含喂入与最终排空为max(120 秒, 2.5 × 音频时长)--rest-timeout N把每个阶段的预算统一设为 N 秒超时返回 HTTP408取消与错误会关闭处理器的任务与转换进程。队列背压与超时待处理音频在ASR 队列与说话人分离队列中各自独立地设有上限按秒数计由--max-buffered-audio控制默认 30 秒。当队列满时音频摄入等待腾出空间而不是丢弃采样——这正是「背压」backpressure机制的语义。除了秒数上限处理队列还限制最多 256 个条目含静音与说话人边界翻译队列同样使用该条目上限定义在 whisperlivekit/processing_queue.py 的ProcessingQueue(maxsize256)中。队列在--backpressure-timeout默认 30 秒内无法接收新工作时会话以显式错误终止RESTHTTP503WebSocket错误消息 关闭码1011。触发路径是 processing_queue.py 抛出的PipelineOverloaded异常。慢模型或长推理调用场景应增大该超时值。两个参数都必须为有限正数前文已述。监控指标SESSION_METRICS日志包含两个关键字段计算逻辑见 audio_processor.pypeak_queued_audio_s各音频队列中曾出现的最大排队秒数取所有队列峰值backpressure_wait_s生产者跨处理队列等待的累计时长。这两个指标都排除当前正在处理的批次且不是字级延迟word latency。理解这一点对用日志做容量规划很重要。内存边界的诚实说明上述所有队列上限并不能封顶进程的全部内存。以下部分各自拥有独立的生命周期不受队列限制约束模型缓冲区单个入站网络消息REST 上传内容翻译后端的历史full 模式的完整转写历史。因此部署时必须实际测量工作负载、限制并发会话数具体策略见 docs/deployment.md。将服务器嵌入 Python 应用WhisperLiveKit 支持以 ASGI 应用的形式嵌入宿主程序。关键保证是导入服务器模块不会解析你程序的命令行参数——配置完全由你显式构造。from whisperlivekit import WhisperLiveKitConfig from whisperlivekit.basic_server import create_app app create_app(WhisperLiveKitConfig( backendfaster-whisper, model_sizesmall, lanfr, pcm_inputTrue, ))对应源码中的关键事实模块级默认config WhisperLiveKitConfig()与transcription_engine None仅作兜底basic_server.py模型在应用启动时FastAPI lifespan 中TranscriptionEngine(config...)加载basic_server.py转写引擎在进程内共享需要不同模型配置时必须使用独立进程而不是在同一进程内创建多个引擎便捷入口whisperlivekit.basic_server:app仍然可用它代表默认配置WhisperLiveKitConfig()构建的应用适合快速启动与调试。从 argparse 到 dataclass 的映射机制嵌入路径之所以与 CLI 等价是因为 parse_args.py 的parse_args()最终调用WhisperLiveKitConfig.from_namespace(args)——它只挑出 dataclass 已知字段忽略未知键config.py。如果你在 Python 中手写关键字参数from_kwargs()会在传入未知键时打印警告并忽略config.py。这意味着嵌入时写错的字段名不会静默生效而是会被忽略并给出提示。配置实战从零组合一套服务把前面各节串起来一个「法语流式转写 中文翻译 说话人分离 队列保护」的完整配置示例wlk serve \ --backend faster-whisper \ --model small \ --language fr \ --backend-policy simulstreaming \ --beams 1 \ --diarization \ --diarization-backend sortformer \ --target-language zh \ --translation-backend nllb \ --pause-segmentation-seconds 4.0 \ --asr-coalesce-min-s 1.0 \ --max-buffered-audio 45 \ --backpressure-timeout 60 \ --host 0.0.0.0 --port 8000 \ --api-token ${WLK_API_TOKEN:-$(cat /run/secrets/wlk_token)} \ --cors-origins https://app.example.com各选项的取舍逻辑--beams 1走贪心解码换取最低延迟追求精度时可增大波束数并配合--decoder beam--asr-coalesce-min-s 1.0牺牲少量更新节奏、减少编码器调用攒够 1 秒新音频再推理--max-buffered-audio 45与--backpressure-timeout 60为慢速 GPU 留出更大的排队与等待余量--api-token未设置时自动回退到WLK_API_TOKEN环境变量basic_server.pyWebSocket 客户端可在连接时用?languagefrtarget_languagezhcontext...按会话覆盖前提是后端支持。对应的 Python 嵌入写法即为第四节create_app(WhisperLiveKitConfig(...))的形式字段名与本例选项一一对应backend、model_size、lan、backend_policy、beams、diarization、diarization_backend、target_language、translation_backend、pause_segmentation_seconds、asr_coalesce_min_s、max_buffered_audio、backpressure_timeout、host、port、api_token、cors_origins。总结WhisperLiveKit 的配置体系可以归纳为三个层次入口层CLI--选项与WhisperLiveKitConfig双路径等价、策略层--backend-policy选择 SimulStreaming/LocalAgreement 流式策略--beams/--decoder决定解码方式--pause-segmentation-seconds与说话人轮次决定转写边界、资源层--max-buffered-audio、--backpressure-timeout、--retention-seconds、--rest-timeout共同构成队列、历史与文件请求的边界。理解每层参数的源码级约束有限正数校验、后端专属限制、.en语言推断、会话级覆盖协议是稳定部署长会话流式服务的前提。进一步深入可继续阅读 docs/API.md协议细节、docs/backends.md后端矩阵与 docs/deployment.md生产部署。【免费下载链接】WhisperLiveKitReal-time, local speech-to-text with streaming ASR, speaker diarization, translation, and OpenAI/Deepgram-compatible APIs.项目地址: https://gitcode.com/GitHub_Trending/wh/WhisperLiveKit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考