Skip to content

声纹录入与语音激活修复 ​

录入页按资源检查、麦克风试录、正式录入的顺序工作。麦克风运行在浏览器或 Electron 客户端,模型与运行组件安装在实际运行 N.E.K.O 后端的机器上。远程部署时,应在后端机器处理资源故障。

麦克风与试录 ​

允许麦克风权限后,选择输入设备,核对页面显示的实际音轨名称,再检查音量条。输入过弱时检查设备、距离与增益;削波时降低增益。试录采集三秒,其中说「喂喂喂喂」或一句短话即可;降噪处理后需由 Silero 检测到至少 10 个有效人声窗口(约 0.32 秒),静音、噪声和提示音仍不通过。正式声纹录入保留 47 个有效人声窗口(约 1.5 秒)的要求。音量条仅表示收到声音,不代表通过人声检测。

试录前关联采集窗口会停止主语音输入,并等待后端关闭输入路径的确认。试录不会提交给 ASR 或 Omni,也不会保存录音或覆盖声纹档案。结束试录后,由用户重新开启主界面麦克风。

开启主界面语音时,会先取消声纹页的试录或录入、停止音轨、释放试录隔离并关闭声纹页,再向后端请求启动语音会话。Electron 会等待窗口实际销毁及隔离释放确认,网页端会协调关联的声纹子窗口;麦克风刚打开、正在试录或试录已通过时均执行此顺序。清理失败或用户在等待期间取消启动时,不继续启动语音会话。

声纹页关闭钩子的清理等待最多 13 秒,手动关闭也使用这一上限。超时后允许关闭窗口,已发出的 keepalive 清理请求继续执行;超时不代表隔离已释放,也不放行语音启动。

服务器明确拒绝 WebSocket 试录隔离申请后,页面可在服务器确认所有输入均已停止时使用 HTTP 回退。桌面端同步清除这次已被拒绝、未取得令牌的等待标记,避免试录通过后仍阻塞开启语音;应答超时或音轨停止未确认时仍保留隔离保护。

空闲时麦克风面板右上角始终提供「收起」,未通过试录也可关闭,再通过「麦克风设置」重新打开。收起只影响界面,不代替试录或放行录入;正在试录、录入或操作资源时不允许收起。设备变化使试录凭证失效时,仍按既有流程重新提示输入设置。

正式录入保留三段参考录音、一段验证录音及 45 秒总时限。切换设备、增益或降噪配置后需要重新试录,正式录入中的变化会取消整次录入。设备断开后重新连接并再次启用麦克风;失败重录与取消保留已有档案及启用偏好。

安装包资源修复 ​

资源面板分别显示 CAM++、Silero、人声降噪能力、唤醒词模型和唤醒词运行组件。资源准备只是加载检查,不能补回安装包缺失的文件。

「修复资源」常驻显示,直接请求实际后端执行资源修复,并在当前页面显示进度及结果,不再跳转到说明文档或关于面板。Windows x64、Python 3.11 可自动补齐兼容的唤醒运行组件及模型。安装包缺失 CAM++、Silero 或 RNNoise 时,仍需修复实际后端安装包;源码模型修复见下节。修复后仍缺失的必需组件保留具体原因,不会标为全部就绪。修复成功且必需资源全部就绪后,5 秒收起资源详情、结果提示和麦克风面板,保留「资源与唤醒设置」标题、检查/修复按钮及「麦克风设置」入口;再次检查或修复恢复展开内容,麦克风设置可单独重新打开面板。提前关闭完成弹窗不取消此计时,手动重新展开、开始新任务或离开页面则撤销旧计时。资源修复不代替麦克风试录;完成后由用户重新开启麦克风。

单独的唤醒词下载按钮只安装固定模型包;「修复资源」会先修复不兼容或缺失的运行组件,再补模型。两条路径均不执行客户端指定的安装命令,不改变用户的启用偏好。不支持预编译组件的平台仍需安装经过验收的兼容应用版本。

「修复资源」有意不再自动打开「关于」或文档:旧 openRepair() 只打开桌面设置的「关于」页,并不执行安装修复。若安装包中的 CAM++、Silero 或 RNNoise 仍不可用,结果提示会给出手动入口:桌面端「设置 → 关于」检查更新,或重新安装实际运行后端的应用;远程部署由服务维护人员修复后端环境。旧 /resources/repair-guide 接口保留供旧客户端兼容使用,不是本页修复按钮的执行入口。

唤醒偏好损坏或部署开关无效时,不下载可选唤醒组件、不覆盖偏好文件;CAM++、Silero 和降噪仍独立检查或修复。唤醒资源保留「偏好不可用」原因,实际激活继续阻断,不能把未知偏好当成用户关闭。

启用唤醒词后,组件平台不支持、下载失败、缓存容量不足或其他非控制类准备错误会分别记录到唤醒资源,必需的 CAM++、Silero 仍继续修复;声纹资源就绪不等于唤醒修复成功。取消、锁冲突、工作进程未能物理退休及发布确认错误仍中止整个任务。页面修复总等待上限为 16 分钟,覆盖各阶段合计 890 秒与退休、刷新余量;原有各阶段超时不变,进度消息不延长总等待上限。

源码部署 ​

自动修复以前端无法修改的源码清单为准;两份清单均可加载且声明所需模型时才提供入口。源码 checkout 是既有代码信任边界,本流程不接收客户端指定的下载地址或摘要。暂存缓存位于源码 CAM++ 模型目录下的 .voice-model-repair,不复用系统共享临时目录;目录及文件拒绝符号链接、Windows reparse point 和文件硬链接。跨进程锁保护修复,冲突时报告资源操作繁忙。成功后清理暂存模型;失败或被取消的修复最多保留该缓存中的两项模型及各自的下载片段供重试。

源码后端缺少 CAM++ 或 Silero 模型时,可直接点击「修复资源」。后端会在可取消的独立工作进程中,从仓库固定来源下载并校验这两项模型,再重新加载检查;不会向 Python 环境安装包、启动麦克风或改变唤醒词偏好。取消会保留已校验完成的模型,未完成的下载不会替换有效文件。唤醒组件使用下述独立缓存安装流程,RNNoise 缺失仍需同步后端运行环境。

已存在但无法加载的模型也可直接发起修复,由后端校验修复能力;仅凭文件发现阶段的下载提示为关闭,不再将点击转为文档跳转。试录凭证只由发起试录的采集窗口管理,其他 Electron 窗口收到共享的控制回执时不会提前释放它;本窗口超时后迟到的有效凭证仍会释放。

资源任务的 progress_detail 回传当前资源、下载/校验/加载阶段、实际读取的字节数、可用的总字节数及尝试次数。CAM++ 总大小来自固定清单;Silero 和唤醒词归档仅在有效的 Content-Length 可用时显示下载百分比,否则只显示已下载大小和动态进度条。progress 表示当前文件的下载比例,下载完成不代表校验、加载或整个修复成功;已有有效文件直接校验,不为展示进度重新下载。重试从本次传输的零字节重新计数,并显示尝试次数。

进度沿既有工作进程管道回传,页面沿用每秒一次的任务查询。进度消息不延长任务截止时间;取消、关闭和操作接管后,旧消息不能更新已退休任务或新任务,原有工作进程终止与资源发布边界保持一致。

声纹模型自动修复仅在两份准备脚本与模型清单均存在时提供。Windows x64、Python 3.11 另支持预编译唤醒组件修复,无需用户安装编译工具。下载 CAM++ 时按清单中的精确大小限制流量,Silero 单次下载上限为 16 MiB,超过上限立即停止,已有有效模型保持不变。

在后端仓库根目录使用其 Python 环境执行:

powershell
uv run python scripts/prepare_speaker_model.py
uv run python scripts/prepare_voice_turn_assets.py

两个脚本使用项目固定来源与摘要,准备 CAM++ 及语音端点检测资产。准备完成后回到资源面板执行加载检查。RNNoise 能力来自项目的音频运行依赖:用项目锁文件同步后端环境,再检查资源状态;模型下载不能修复 RNNoise 运行组件缺失。

唤醒词需要定制的 1.13.8+neko.kws2 运行组件。用户启用唤醒词后,点击「修复资源」会依次检查并补齐运行组件、唤醒模型,再执行资源加载检查。组件从固定版本的项目 Release 下载,校验固定大小与 SHA256,在独立工作进程中验证 Python/native 双版本;退休工作进程后,当前操作才发布私有缓存指针。不会向运行中的 Python 环境执行 pip 安装,不会改变唤醒开关或覆盖已加载的 DLL。唤醒词关闭时不安装可选组件。

组件保留至多三份不可变版本,损坏时发布新版本并保留旧文件;达到容量上限停止修复。下载进度显示真实字节数与百分比,校验和加载阶段不伪造百分比。取消发生在发布期间时,等待当前有界原子步骤结束,随后停止,不继续下载其他资源或发布就绪状态。源码维护者也可按照 唤醒运行组件安装说明 构建并安装兼容 wheel,然后执行:

powershell
uv run --no-sync python scripts/provision_wake_word_model.py --model-dir .wake-word-model

脚本下载完整包、校验、真实试加载成功后才发布 current.json,并输出实际版本目录。显式设置 NEKO_WAKE_WORD_MODEL_DIR 时应指向该输出的 versions/<version> 目录。缓存根目录本身不是模型目录。已有显式配置优先于缓存发现。

未显式配置时,页面下载使用后端用户的受控缓存。用户主动启用唤醒词后,后端会发现并加载验证通过的当前版本;缓存存在与下载成功均不会自动启用唤醒词。禁用时保持纯声纹激活。已启用但资源异常时,语音门控保持阻断并显示原因。

当前打包流水线的唤醒组件针对 Windows x64、Python 3.11,包含固定源码、补丁、版本检查和冻结程序实际加载检查。其他平台需具备经过验收的兼容组件;不支持的平台会报告能力不可用。

激活与重试 ​

声纹录入与质量检查不依赖独立 ASR。普通 ASR 与 Omni 都经过统一激活门控:本人声纹或已启用且就绪的唤醒词可激活;激活后沿用会话输入行为,30 秒无人声回到等待状态。

主界面显示准备中、等待激活、已激活或不可用及原因。资源可用、档案已保存与当前会话已激活是不同状态。停止、断连或切换会话后,旧状态不能更新新会话。

重试只作用于当前采集连接与会话,先退休旧实例,再准备新实例;恢复前不放行下游音频。资源修复会重新装配激活资源。交付结果不确定的旧音频不会重新投递。

等待激活时,客户端到 N.E.K.O 后端仍可能传输音频;门控控制后端向下游 ASR 与 Omni 的递交。

两仓库版本依赖与回退 ​

N.E.K.O 的资源与试录接口、voice_identity_control 控制消息,需与 N.E.K.O.-PC 的 nekoVoiceEnrollment 桥接配套部署。桌面端保留 Session 与 partition 隔离,由实际采集窗口打开录入子窗口;不同 partition 的设备编号不会同步。

回退应用代码不会改写既有档案格式或启用偏好。模型版本目录保持不可变,发布失败与取消保留原有效指针。损坏版本通过发布新完整版本修复;达到受控缓存容量上限时停止安装并报告原因,避免删除正在使用的模型文件。

缓存容量达到上限时,只能由实际运行后端机器的维护人员进行受控维护:先停止使用该缓存的所有后端进程,保留当前完整有效版本与 current.json,再清理本功能明确拥有且已不再使用的历史版本。页面不会自动删除已发布版本;不要删除用户声纹档案或启用偏好,也不要按设备名称推测其他机器的缓存位置。

唤醒运行组件的默认 Windows 目录为 %LOCALAPPDATA%/N.E.K.O/voice-resources/wake-runtime(后端运行用户的目录),模型缓存为相邻的 wake-word;非 Windows 模型缓存使用 $XDG_CACHE_HOME/N.E.K.O/voice-resources/wake-word,未设置时为 ~/.cache/N.E.K.O/voice-resources/wake-word。容量上限统一返回 resource_cache_full,与路径或链接不安全的错误区分。运行组件只允许维护固定摘要前缀的历史版本目录:停止所有使用该缓存的后端后,先备份并读取 current.json,保留其指向的目录、已校验 wheel、install.lock 和唤醒启用偏好;确认其他历史目录已无人使用后再清理,腾出至少一个名额,然后启动后端重试。当前目录即使已损坏也先保留,由下一次修复发布新的完整版本。无法确认目录归属或进程是否停止时,不删除,交由部署维护人员处理。仅持有 install.lock 或目录不等于当前指针,均不能证明旧 DLL 未被其他进程加载,因此本次不加入自动回收。

下载在工作进程中校验并试加载完整资源,先安装不可变版本目录,再由当前操作提交 current.json。提交前取消保留旧指针;提交开始后取消会等待实际发布及运行时刷新结果。接口的 committed 字段说明是否已确认发布,已发布但刷新失败时仍显示失败原因;预检结果只在刷新完成且配置未变化后标记就绪。