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](https://github.com/Soul-AILab/SoulX-Duplug)，公开模型仓库为 [Soul-AILab/SoulX-Duplug-0.6B](https://huggingface.co/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`，后者不混入当前模型判断指标。
- 计算延迟区分模型加载、特征提取、推理、上下文重放与在线增量更新；跨机器或不同线程数的结果注明配置差异。