服务启动与运行配置

1. 职责与边界

本模块负责进程入口、配置加载、App 初始化、Worker 与设备分配，以及 CLI 的服务管理。模型组件的具体加载方式见模型与参考音色，部署命令与配置用法见配置与部署。

主要源码：cli.py、config.py、app.py。

2. 输入与输出

项目	内容
配置来源	CLI 的配置路径、CONFIG_PATH 环境变量、YAML 与 Python 配置类默认值
配置分组	app、buffer、realtime_vc、models
初始化结果	绑定有效配置、转换实例和会话数据读取管理器，并注册路由的 FastAPI App
运行结果	Uvicorn 服务进程，以及供 CLI 查询和停止服务使用的 PID 记录

Config 是进程内单例。首次构造时读取配置，get_config() 返回已经加载的对象；当前没有配置热更新流程。

3. 关键流程

3.1 配置解析与生效

serve -c 将配置路径写入 CONFIG_PATH。Config 构造器优先使用显式传入的路径，其次读取该环境变量；均未提供时使用 ConfigData 默认值。指定 YAML 中未填写的字段由对应配置类补齐。

配置文件不存在、YAML 解析失败或加载过程中发生异常时，当前实现记录日志后回退到整套类默认值。配置路径日志本身不能证明文件成功生效，需要结合加载结果和有效参数核对。

类默认值与 prod.yaml 存在差异，例如音高开关、扩散步数、RMS 比例和参考路径。模块文档引用运行参数时注明来源，完整用法由操作指南维护。

3.2 启动顺序

1. CLI 读取服务配置，以端口定位 PID 文件，检查已记录的主进程并写入本次服务信息。
2. app.main() 读取监听地址、端口和 Worker 数，通过 uvicorn.run(..., factory=True) 使用 create_app() 工厂。
3. 各运行进程的 create_app() 获取配置和 Worker 标识，初始化日志与 FastAPI App。
4. App 创建 SessionDataManager，按 Worker 标识从设备列表中循环选择设备，再创建 RealtimeVoiceConversion。
5. 转换实例加载模型、计算流式参数及参考条件；完成后 App 注册基础、WebSocket 和工具路由。

转换实例初始化失败会重新抛出异常，当前 App 初始化无法完成。首次模型下载和参考条件计算属于启动过程，应与请求处理耗时分别记录。

3.3 Worker 与设备

Worker 标识优先从 multiprocessing 的进程名称提取，不能提取时使用 PID。设备选择采用 (worker_id - 1) % len(device)；空设备列表不满足该实现的要求。

每个 Worker 持有独立模型与参考条件，会话在该 Worker 内复用这些资源。设备选择、Worker 数与显存驻留的关系见总体设计；当前没有跨 Worker 的共享模型服务或动态推理批处理。

3.4 进程管理

CLI 在仓库 temp/ 下使用按端口命名的 PID 文件记录主进程、端口、Worker 数和配置路径。status 读取记录并检查进程；stop 根据记录向目标进程及子进程发送信号。未指定端口或配置时，stop 会遍历已记录实例。

serve 的退出清理会删除对应 PID 文件，并尝试删除按端口命名的连接文件。WebSocket 连接监控实际使用公共文件，两者并未完全对应，详见运行文件与连接统计。

4. 约束与关联文档

模型缓存的相对路径在模型工厂中按仓库根目录解析；参考音频、输出和日志等相对路径通常依赖进程工作目录。操作指南统一从仓库根目录启动。

代码中的 CPU 设备选择不等于实时 CPU 性能已验证；原生 Windows 还受 fcntl 等依赖影响。环境准备、服务停止和清理命令的使用边界见配置与部署，当前设计不增加平台支持或容量承诺。