xiaobailing-turn-detection/AGENTS.md

该项目为了构建一个旁路分支服务，用来在 ASR–LLM–TTS 的 pipeline 里面添加话轮检测，更好地实现语音交互。

该项目目前聚焦韩泰机器人 EOT 检测准确率问题。

实验机器与目录

按模型使用下面的固定实验环境：

模型	执行机器	实验目录	环境管理
SoulX-Duplug	远程机器 2033lab04ztr	/mnt/58462F4C462F29E8/xiaobailing-turn-detection-experiments	新建独立 Conda 环境
MaAI ch_kyoto	本机 Mac	/Users/wangx/Code/晓白灵智能打断/experiments/maai-ch-kyoto	目录内的独立 uv 环境
Smart Turn v3.2	本机 Mac	/Users/wangx/Code/晓白灵智能打断/experiments/smart-turn-v3.2	目录内的独立 uv 环境

SoulX-Duplug 远程实验

• 项目正式名称为 SoulX-Duplug，官方仓库为 Soul-AILab/SoulX-Duplug，公开模型仓库为 Soul-AILab/SoulX-Duplug-0.6B。这里指该流式语义 VAD／话轮状态预测项目。
• SoulX-Duplug 的环境配置、模型加载、推理和性能测试在 2033lab04ztr 上执行，工作目录使用上表指定的远程路径。
• 使用 Conda 新建专用实验环境，例如 xiaobailing-soulx-duplug，不安装到 base，也不复用其他模型的环境。同一轮实验创建后继续使用该环境；不要重复创建或覆盖已有同名环境。
• Python、PyTorch、CUDA 和其他依赖版本按所选 SoulX-Duplug 模型版本的要求确定；记录实际环境名、依赖版本和安装命令。
• 执行前检查远程 Conda、GPU、显存、驱动和 CUDA 条件。2026-10-13 已通过 SSH 核实：Ubuntu 24.04.3、i5-9400F（6 核）、约 62 GiB 内存、RTX 3090（24 GiB，计算能力 8.6）、NVIDIA 驱动 595.84。当时可用内存约 59 GiB、空闲显存约 23 GiB；这些空闲量随其他任务变化，运行前重新检查。
• 远程 Conda 位于 /home/wangx/miniconda3/bin/conda，版本 4.12.0。专用环境已建立为 /home/wangx/miniconda3/envs/xiaobailing-soulx-duplug：Python 3.10.22、PyTorch 2.6.0+cu124、torchaudio 2.6.0、transformers 4.52.1、ModelScope 1.28.2、FunASR 1.2.6；实际依赖以远程 results/requirements-freeze.txt 为准。使用官方 setuptools 78.1.1，避免新版移除 pkg_resources 导致 ModelScope 加载失败。egospeak 环境仅用于之前的只读硬件探测，不用于本实验。
• 指定实验目录已存在且可写，所在 fuseblk 数据盘当时剩余约 49 GiB。Conda 环境保留在 Linux 文件系统的 /home/wangx/miniconda3/envs，不要把环境本体建在该数据盘上；根盘当时剩余约 26 GiB，避免将模型下载缓存留在默认 home 路径。
• 远程 Hugging Face 直连在本次检查中超时；hf-mirror.com 的模型 API 和权重下载地址 HEAD 请求成功，GitHub、PyTorch CUDA 12.4 下载源、Conda 默认源和 ModelScope 网站可访问。完整权重下载尚未验证。镜像元数据修订 61701c4ab8193cc1ee2220d3848872ac6c720142 的 24 个文件合计约 7.24 GiB，另需为 Paraformer 及依赖预留空间。远程已有 FFmpeg 6.1.1、SoX 14.4.2、Git 和 Git LFS。
• 模型、下载缓存、脚本和原始实验结果保存在上述远程实验目录内；需要本机分析时，将结果另存到本机项目的 experiments 下，并注明远程来源。
• 2026-10-13 已完成真实录音基本推理：官方代码提交 a0b9063843df69619b087b95b74597b2176910b8，权重修订见上文；三个大权重从官方 ModelScope 同名仓库下载，SHA256 与 Hugging Face 固定修订一致。Paraformer、FSMN VAD 和 CT-Transformer 标点模型缓存位于远程 cache/modelscope。配置写 bf16，但当前官方加载器没有转换参数，实际使用 FP32；本次没有另加混合精度，基本运行峰值 GPU 分配约 5.76 GiB。加载时多出的 embed_tokens_func.weight 已验证为嵌入权重的重复别名，没有缺失训练参数。
• 远程实验入口为 scripts/run_experiment.py，在专用环境执行 python scripts/run_experiment.py all，依次进行基本运行、44 点评估和延迟测试；也支持 smoke、evaluate、benchmark 分步运行。用户仅评估 can_reply 时，主分数为 softmax(complete_logit, incomplete_logit)[complete]，默认阈值 0.5；它是条件两类别分数，不是官方校准的 can_reply 概率。原生状态另存作为诊断，不使用服务层超时回复、完成后的重置和最终整句 ASR。每点独立重放最多 20 秒的历史用户声道，仍保留原生推理内部的 Paraformer ASR。
• 2026-10-14 已完成本批 44 点和六段录音的计算延迟评估；每点固定 Python、NumPy、PyTorch 和 CUDA 种子 42，重复测试点的分数和 ASR 输出一致。本机留档在 experiments/soulx-duplug/results，逐点对比为 comparison-points.csv，汇总为 comparison-summary.json，文字分析为 对比分析.txt。补充原生状态转持续 can_reply 的辅助映射：开始为 0，complete 置 1，incomplete/nonidle 置 0，idle/backchannel 保持前值；只处理标注点之前的预测，不加入外部结束信号、超时或音频清空。不能将这种映射或条件分数称为完整官方服务策略。

MaAI 与 Smart Turn 本机实验

• 本机已验证的硬件为 Apple M4 Mac mini、10 核 CPU、16 GB 内存，两个模型当前均使用 CPU 推理。
• 两个实验目录均使用 Python 3.11，各自维护 .venv、pyproject.toml、.python-version 和 uv.lock。
• 保持模型环境独立：MaAI 当前使用 transformers==5.5.3，Smart Turn 使用 transformers==4.48.2，不要混装到同一环境。
• 在对应实验目录使用 uv sync --locked 恢复依赖，使用 uv run --locked python <脚本> 执行实验。
• MaAI 当前锁定 maai==0.2.22，使用 ch_kyoto 降噪 VAP 权重和 CPC 编码器；本机已安装 Homebrew PortAudio 19.7.0，用于 PyAudio 依赖。基本运行命令为 uv run --locked python smoke_run.py。
• Smart Turn 当前使用 smart-turn-v3.2-cpu.onnx。基本运行命令为 uv run --locked python predict.py <音频路径> --start-ms <起点毫秒> --end-ms <判断点毫秒>。
• 两个模型的判断点回测脚本均为各自目录内的 evaluate_can_reply.py；计算延迟测试脚本均为 benchmark_latency.py。
• 模型权重、缓存和结果保留在各自实验目录中。当前人工标注来源为本机项目的 labels/EOT标注/工作数据；预测结果另存，不覆盖人工标注。

实验记录

• 每次实验注明执行机器、硬件、环境管理方式、Python/依赖版本、模型版本与权重校验、输入声道、采样率、上下文长度、判断点与阈值规则。
• MaAI 的 p_now、p_future 是说话活动预测；用于 can_reply 评估时，明确记录映射规则，不将其直接称为原生 EOT 概率。
• 当前工作数据有 6 段录音、44 个判断点（can_reply_now=1/0 各 22 个）。SoulX-Duplug 按用户声道重采样到 16 kHz，记录官方 160 ms 分块、960 ms 后向窗口和 40 ms 前向窗口的时间对齐；只能使用判断时刻已经收到的音频，不能读取标注点之后的音频或使用标注转写作为模型输入。评估 can_reply 时区分模型的完成状态与 max_wait_num 超时触发的 speak，后者不混入当前模型判断指标。
• 计算延迟区分模型加载、特征提取、推理、上下文重放与在线增量更新；跨机器或不同线程数的结果注明配置差异。