# 语音歧义消解 Agent

**Repository Path**: WS3269864565/AI_coding_program

## Basic Information

- **Project Name**: 语音歧义消解 Agent
- **Description**:  面向语音歧义消解的主动工具调用式 Audio Agent——自动调用7个语音分析工具，在噪声和多人重叠场景中识别目标说话人。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-05-12
- **Last Updated**: 2026-07-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Audio Agent — 面向语音歧义消解的主动工具调用系统

在嘈杂环境中（背景噪声 + 多人重叠说话），给定单声道音频和自然语言查询，自主检测歧义类型、调用 7 个专用语音分析工具、融合证据，最终输出目标说话人的准确转录。

## 关键结果

| Benchmark | 样本 | 场景 | Mean WER |
|:---|:--:|:---|:--:|
| 合成 | 35 | 理想条件（数字混音） | **4.3%** (Rule Controller) / 11.3% (Fixed) |
| LibriCSS | 174 | 真实房间声学 | **52.0%** (Fixed 管线) |
| AMI Corpus | 720 | 真实会议对话 | **19.7%** (Fixed 管线) |
| Spatial Audio | 20 | 双耳空间方位 | **74.0%** (Fixed 管线) |

**核心结论**：Rule Controller 全面优于 LLM Agent（WER 4.3% vs 100%，延迟 6.7s vs ~30s），确定性规则在语音分析任务上比 LLM 推理更可靠。

## 提交内容

本压缩包包含实验代码和全部实验数据（~820 MB），仅不含模型权重（约 2.5 GB，需单独下载）。

| 内容 | 说明 | 状态 |
|------|------|:--:|
| `src/` | 全部源代码（Agent / 7 工具 / Benchmark / 微调） | ✅ |
| `tests/` | 单元测试（71 + 37 项） | ✅ |
| `data/benchmark/` | 合成 benchmark（45 条 WAV + manifest + results） | ✅ |
| `data/benchmark_libricss/` | LibriCSS 真实声学（60 segments + manifest + results） | ✅ |
| `data/benchmark_ami/` | AMI Corpus 真实对话（18 段 segments + manifest + results） | ✅ |
| `data/benchmark_spatial/` | Spatial Audio 双耳空间（20 条 WAV + manifest + results） | ✅ |
| `data/finetune_ami/` | MossFormer2 AMI 微调（训练数据 + checkpoint，707 MB） | ✅ |
| `docs/` | 项目文档（3 份，详见下方文档导航） | ✅ |
| `requirements.txt` | Python 依赖清单（版本已锁定） | ✅ |
| `models/` | 模型权重 | ❌ 不包含（约 2.5 GB） |

## 系统架构

```
音频 + Query → [ASR 预处理] → 歧义检测 → 工具选择 → 工具调用 → 证据融合 → 最终答案
                                   │
                      ┌────────────┼────────────┐
                      ▼            ▼            ▼
                5 类歧义规则   7 工具映射表   加权裁决融合
```

## 7 个音频工具

| 工具 | 模型 | 用途 |
|------|------|------|
| speech_enhancement | ClearVoice FRCRN_SE_16K | 去背景噪声 |
| speech_separation | MossFormer2 + SepFormer + TIGER + TF-GridNet | 分离重叠说话人（多模型并行+声纹优选） |
| guided_separation | Diarization 引导分离 | 仅分离重叠区间 |
| speaker_diarization | pyannote.audio 4.0.4 | 谁在什么时候说话 |
| asr_timestamp | WhisperX large-v3 + wav2vec2 | 语音转文本 + 词级时间戳 |
| speaker_verification | ECAPA-TDNN | 判断两段音频是否同一人 |
| spatial_analysis | SRP-PHAT + KEMAR HRTF | 双耳空间方向 + 距离估计 |

## 快速开始

```bash
# 一键复现全部实验（配好环境后直接跑）
bash run_all.sh

# 环境
source venv_audio_agent/bin/activate
export HF_TOKEN=<your_hf_token>   # 必须！用于 pyannote diarization

# LLM Agent 端到端（如果配置了 LLM）
python -m src.agent.runner --audio data/audio/overlap_2spk_50.wav --query "主要说话人说了什么？"

# 跑四模式对比实验
python -m src.agent.experiment

# 跑五模式对比（含 LLM Agent）
python -m src.benchmark.compare_all_modes

# 评估 Fixed 管线
python -m src.benchmark.evaluate                    # 合成 benchmark（35 条）
python -m src.benchmark.evaluate_libricss --overlap-only  # LibriCSS（174 条）
python -m src.benchmark.ami_evaluate                # AMI Corpus（720 条）

# 单元测试
python tests/run_tests.py                           # 71 项
pytest tests/test_controller.py -v                  # 37 项
```

## 项目结构

```
├── src/
│   ├── agent/         # Agent Controller + LLM runner + 实验
│   ├── tools/         # 7 个音频工具
│   ├── benchmark/     # 数据生成 + 评估
│   ├── finetune/      # MossFormer2 AMI 微调
│   └── vendor/        # TIGER 模型依赖
├── tests/             # 单元测试 (71+37 项)
├── docs/              # 文档
├── data/              # 音频 + benchmark（合成/LibriCSS/AMI/Spatial）
├── models/            # 模型权重
├── run_all.sh         # 一键复现全部实验
└── requirements.txt   # Python 依赖
```

## 文档导航

| 文件 | 内容 |
|------|------|
| [docs/reproduction.md](docs/reproduction.md) | 复现指南 — 环境配置、数据准备、一键运行 |
| [docs/project-status.md](docs/project-status.md) | 项目快照 — 最新结果、工具状态、已知限制 |
| [docs/faq.md](docs/faq.md) | 常见问题 — Bug 记录与解决方案 |