LocalAI 的 Kokoro TTS 后端一个 82M 参数轻量级多语种语音合成 gRPC 服务实战解析【免费下载链接】LocalAILocalAI is the open-source AI engine. Run any model - LLMs, vision, voice, image, video - on any hardware. No GPU required.项目地址: https://gitcode.com/GitHub_Trending/lo/LocalAIKokoro TTS 是一个参数仅 8200 万、采用 Apache 许可权重的轻量级文本转语音TTS模型。本文基于 LocalAI 仓库中 backend/python/kokoro/README.md 及其目录下的完整实现深入讲解 Kokoro 如何在 LocalAI 中以独立 gRPC 后端进程的形式落地从环境搭建、服务启动、单测验证到底层Health/LoadModel/TTS三个 RPC 方法的具体实现细节。读完本文你将掌握如何安装、运行、测试该后端并能根据仓库源码理解其配置项语言码、voice、并发度等如何被解析与生效。后端定位Kokoro TTS 在 LocalAI 中的角色LocalAI 采用核心 后端backend的可组合架构语音类能力以独立的 on-demand 后端进程接入。Kokoro 后端即为其中之一它运行在一个独立的 Python 进程中以 gRPC 协议与 LocalAI 核心通信。仓库根目录 Makefile 中登记后端类型的行BACKEND_KOKORO kokoro|python|.|false|true表明kokoro被注册为 Python 类型的后端同时 Makefile 的REALTIME_BACKEND_NAMES中也包含了kokoro说明它与 whisper、silero-vad、llama-cpp 一样被纳入实时realtime语音管线的候选后端集合。依据 backend/python/kokoro/README.md 的 Features 说明该后端具备以下核心特征轻量级 TTS 模型参数量仅 8200 万82 million parametersApache 许可证权重Apache-licensed weights可自由用于商业与开源项目速度快、成本低Fast and cost-efficient对无 GPU 的部署环境友好支持多语言Multi-language support提供多种音色选项Multiple voice options。需要特别说明的是仓库中另存在一个 Rust 实现的kokoros后端见 backend/rust/kokoros 与 gallery/kokoros.yaml其登记行为kokoros|rust|.|false|trueMakefile。本文讨论的对象是 Python 实现的kokoro后端即 backend/python/kokoro 目录。环境准备与安装安装命令进入后端目录后通过该目录下的 Makefile 触发安装cd backend/python/kokoro make kokoro该目标实际执行bash install.sh即 install.sh。安装脚本做了什么install.sh 的关键逻辑如下引入公共后端脚本脚本先查找common/libbackend.sh优先当前目录下、否则上一级即backend/python/common/libbackend.sh。其中提供的installRequirements、startBackend、runUnittests等函数被后续步骤复用。这保证了所有 Python 后端的虚拟环境创建、依赖安装与启动方式保持一致。针对 Intel 环境的 pip 索引修复脚本注释解释了 Intel pip 源对所有包名都返回 HTTP 200 但不返回包链接导致uv误判包存在而不再回落到 PyPI。因此当BUILD_PROFILE为intel时会追加--upgrade --index-strategyunsafe-first-match让uv继续向 PyPI 回退并允许把 torch 降级到 Intel pip 源中提供的版本。L4TJetson环境强制使用 pip当BUILD_PROFILE为l4t12时设置USE_PIPtrue。调用installRequirements安装依赖。预下载 spaCy 英文模型注释明确指出spaCy是misakiKokoro 用于英文音素化 phonemization 的依赖的依赖项由于运行时使用的便携 Python 环境没有pip/uvspacy的自动下载会失败因此必须在安装阶段预先执行python -m spacy download en_core_web_sm。分平台依赖清单仓库为 Kokoro 后端准备了多份 requirements 文件对应不同推理加速环境由BUILD_PROFILE决定实际选用哪一份文件目标环境requirements-cpu.txt纯 CPU通过--extra-index-url https://download.pytorch.org/whl/cpu拉取 CPU 版 torchrequirements-cublas12.txtNVIDIA CUDA 12.xcuBLASrequirements-cublas13.txtNVIDIA CUDA 13.xcuBLASrequirements-hipblas.txtAMD ROCm / HIPrequirements-intel.txtIntel 扩展与 oneAPI 生态requirements-l4t12.txtNVIDIA Jetson L4T 12.xrequirements-mps.txtApple SiliconMPSrequirements.txtgRPC/协议基础依赖grpcio、protobuf 等供测试与协议层使用以 CPU 环境为例requirements-cpu.txt 的核心依赖为torch、transformers、accelerate、kokoro、soundfile。也就是说模型推理与分词由kokoroPython 包及其KPipeline完成torch负责张量计算soundfile负责把音频写入 WAV/FLAC 等文件。启动 gRPC 服务与运行自测启动服务make run其等价于依次执行bash install.sh与bash run.sh见 Makefile 中run: kokoro依赖而 run.sh 最终调用公共脚本中的startBackend来拉起后端进程。后端主程序是 backend.py。它支持用命令行参数指定监听地址python3 backend.py --addr localhost:50051不传参时默认绑定localhost:50051backend.py。服务成功启动后会在 stderr 打印Server started. Listening on: address并对SIGINT/SIGTERM信号做优雅停机处理。运行单元测试make testtest目标同样先执行install.sh再运行bash test.shtest.sh调用公共脚本的runUnittests执行 test.py 中基于unittest的用例。这三个用例覆盖了 gRPC 后端的完整生命周期是验证本地环境是否可用的最快途径test_server_startup启动子进程服务后通过grpc.insecure_channel(localhost:50051)调用Health断言返回消息为bOKtest_load_model调用LoadModel断言返回successTrue且消息为Kokoro TTS pipeline loaded successfullytest_tts先LoadModel再以textKokoro is an open-weight TTS model with 82 million parameters.、voiceaf_heart、dsttest_output.wav调用TTS断言生成成功。三个用例都在setUp中先sleep(30)等待服务与模型完成初始化在tearDown中终止子进程。测试覆盖了 LocalAI 对该类 Python 语音后端最关心的三类 RPC。gRPC 服务实现原理三大核心方法backend.py 实现了BackendServicer与 LocalAI 侧的 pkg/grpc/interface.go 所定义的语音后端接口对应。服务端通过futures.ThreadPoolExecutor处理请求并将 gRPC 消息上下限均设置为 50MBgrpc.max_message_length/grpc.max_send_message_length/grpc.max_receive_message_length以便容纳较长的合成语音数据。此外服务端通过公共模块的get_auth_interceptors()挂载鉴权拦截器与 LocalAI 核心通信时支持共享密钥认证from grpc_auth import get_auth_interceptors路径在 backend.py。Health健康检查def Health(self, request, context): return backend_pb2.Reply(messagebytes(OK, utf-8))这是 LocalAI 探测后端是否存活的约定方法直接返回固定字符串OK不依赖模型是否已加载。LoadModel加载 Kokoro 推理管线LoadModel是理解整个后端配置机制的关键。它把请求中携带的Options一组optname:optvalue形式的字符串列表解析成字典并保存self.options {} options request.Options for opt in options: if : not in opt: continue key, value opt.split(:) self.options[key] value lang_code self.options.get(lang_code, KOKORO_LANG_CODE) self.pipeline KPipeline(lang_codelang_code)这里揭示了两个可配置项lang_code语言码既可以通过 LocalAI 模型加载时传入的选项lang_code指定例如lang_code:a也可以由环境变量兜底。默认语言码常量在启动时从环境变量读取KOKORO_LANG_CODE os.environ.get(KOKORO_LANG_CODE, a)即环境变量KOKORO_LANG_CODE未设置时默认使用a英文。Kokoro 的语言码通常按字母归类如a表示英语最终会传递给KPipeline(lang_code...)决定采用哪个语言的路由与音素表。选项解析约定形如key:value的字符串会被按第一个冒号切分为键值对不含冒号的项会被忽略。这与 LocalAI 其他 Python 后端在LoadModel阶段的选项传递方式一致。加载成功后self.pipeline即为可用的KPipeline实例任何异常都会被捕获并转换为Result(successFalse, message...)返回。TTS文本转语音的完整生成链路TTS方法是本后端的功能核心其流程可分为三步# 1. 选择音色 voice request.voice if request.voice else af_heart # 2. 生成分段音频 generator self.pipeline(request.text, voicevoice) speechs [] for i, (gs, ps, audio) in enumerate(generator): speechs.append(audio) print(fGenerated audio segment {i}: gs{gs}, ps{ps}, filesys.stderr) # 3. 拼接并写盘 speech torch.cat(speechs, dim0) sf.write(request.dst, speech, 24000)要点如下音色选择voice直接从请求中获取对应 LocalAI 语音接口中的 voice 参数若为空则回退到默认音色af_heart。Kokoro 的音色命名遵循语言字母性别字母_名字的规律例如af_heart为英语女性a American English,f female。模型支持多音色的能力正是通过向KPipeline传入不同 voice 名实现的。分段式流式生成self.pipeline(text, voicevoice)返回一个生成器逐段产出三元组(gs, ps, audio)其中audio为各段的张量后端把每段 append 后统一torch.cat拼接成完整波形避免了长文本一次性生成带来的内存与对齐问题。写盘与采样率最终调用soundfile.write(request.dst, speech, 24000)固定以24000 Hz采样率把拼接后的浮点音频写入请求指定的目标路径dst例如test_output.wav。因此 Kokoro 的默认输出采样率就是 24kHz。整个过程中任何异常同样会被捕获并作为Result(successFalse, ...)返回保证失败时 LocalAI 核心能拿到明确的错误信息而不是 gRPC 层静默断开。面向接入方的关键参数速查综合源码接入方在配置该后端时主要涉及以下参数/环境变量名称来源默认值作用与说明addr命令行--addrlocalhost:50051gRPC 服务监听地址LocalAI 通过该地址连接后端lang_codeLoadModel的 Options 中lang_code项环境变量KOKORO_LANG_CODE未设置时为a传给KPipeline(lang_code...)的语言码决定使用的语言/音素路由voiceTTS请求的voice字段af_heart合成音色多音色能力由此选择textTTS请求的text字段无待合成的文本dstTTS请求的dst字段无音频输出文件路径采样率固定为 24000 HzPYTHON_GRPC_MAX_WORKERS环境变量1gRPCThreadPoolExecutor的并发 worker 数MAX_WORKERS int(os.environ.get(PYTHON_GRPC_MAX_WORKERS, 1))KOKORO_LANG_CODE环境变量aLoadModel未显式传lang_code时的全局兜底语言码从源码结构看后端生命周期与集成方式Kokoro 后端遵循 LocalAI Python 后端的一贯生命周期LocalAI 核心Go按模型配置找到kokoro后端通过 gRPC 调用Health探活调用LoadModel把模型侧配置如lang_code等键值对以 Options 列表形式下发后端据此创建KPipeline单例当用户在/v1/audio/speech之类的语音合成接口提交请求时核心把text、voice等参数组装成TTSRequest并转发给后端后端返回执行成功与否进程退出时由信号处理优雅关闭。仓库中BackendServicer的TTS返回体仅含success布尔与可选错误消息见 backend.py而音频文件由后端直接写到request.dst指定路径。这一后端落盘、核心读文件的模式是 LocalAI 各 TTS 后端的通用设计例如语音生成链路由 core/backend/soundgeneration.go 统一编排后端加载选项、gRPC 调用与错误处理则集中在 core/backend/options.go 与 core/backend/tts.go 中读者可以对照这三份源码进一步追踪一个 TTS 请求从 HTTP 到模型进程的完整调用链。需要留意仓库的 test.py 直接以grpc.insecure_channel调LoadModel与TTS说明该后端在鉴权拦截器启用前或本地直连时也能以明文通道独立运行与联调而在被 LocalAI 核心托管时则会按核心配置启用认证拦截器。常见运维注意事项清理与重新生成协议桩目录 Makefile 提供make clean删除 venv、__pycache__与生成的backend_pb2_grpc.py/backend_pb2.py以及make protogen-clean。若协议桩缺失或与 backend/backend.proto 版本不一致需要在构建阶段重新生成后再启动。首次加载耗时较长KPipeline初始化需要下载/加载模型权重与音素表test.py中setUp预留了 30 秒等待时间在冷启动场景下尤其是 CPU 或首次联网拉取模型应适当放宽健康检查超时。并发与性能默认PYTHON_GRPC_MAX_WORKERS1即单 worker 串行处理。若需要更高吞吐可通过该环境变量调大 worker 数但需注意单个KPipeline在 torch 下的并发安全边界通常更稳妥的做法是依赖 LocalAI 核心侧的模型实例级并发策略。无 pip 的便携运行时由于运行时 Python 环境缺少pip/uv所有依赖含 spaCy 英文模型en_core_web_sm必须在install.sh阶段预装完毕否则运行期misaki的音素化流程会因无法自动下载而失败。小结Kokoro TTS 后端是 LocalAI 语音能力矩阵中一个兼顾轻量与多语种的 Python gRPC 后端。它用约 8200 万参数的 Apache 许可权重通过KPipeline以固定 24kHz 采样率完成从文本到 WAV 的分段合成并借助lang_code、voice等参数实现多语言与多音色切换。本文从 backend/python/kokoro/README.md 出发结合目录内 backend.py、install.sh、test.py 与各平台 requirements 文件完整还原了该后端的安装、运行、测试与底层 RPC 语义。若你想在其上做二次开发建议以make kokoro make run拉起服务再用make test中的三个用例作为最小联调模板开始改造。【免费下载链接】LocalAILocalAI is the open-source AI engine. Run any model - LLMs, vision, voice, image, video - on any hardware. No GPU required.项目地址: https://gitcode.com/GitHub_Trending/lo/LocalAI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考