aggregator/README.md

# 语义聚合控制器 (Semantic Aggregator)

语义聚合控制器是伪流式音频转写系统的核心模块，负责将多个音频片段的转录结果聚合成完整的语义单元（句子），并推送到下游模块（显示和翻译）。

## 主要功能

1. **维护转录片段缓冲池**：收集来自转录模块的片段，直到形成完整语义单元
2. **判断语义完整性**：使用ChatGPT进行few-shot学习，判断多个片段是否组成完整句子
3. **重新转录**：将多个片段的音频合并，进行整体重新转录，提高准确性
4. **推送到下游**：将聚合结果发送到显示模块和翻译模块

## 核心组件

### SentenceCompletionDetector

使用ChatGPT进行few-shot学习，判断文本是否是一个完整的句子。

```python
detector = SentenceCompletionDetector()
is_complete = detector.is_sentence_complete("你会学习到如何使用音频数据集")  # False
is_complete = detector.is_sentence_complete("你会学习到如何使用音频数据集。")  # True
```

### SemanticAggregator

主要聚合控制器，负责缓冲、判断、重新转录和推送。

```python
aggregator = SemanticAggregator(
    on_display=display_callback,  # 显示回调
    on_translate=translate_callback,  # 翻译回调
    transcriber=transcriber,  # 转录器实例
    segments_dir="dataset/audio/segments",  # 音频片段目录
    max_window=5.0,  # 最大聚合时长（秒）
    max_segments=5,  # 最大聚合片段数
    min_gap=0.8,  # 触发聚合的最小间隔（秒）
    force_flush_timeout=3.0  # 强制flush超时时间（秒）
)
```

## 聚合判断逻辑

聚合器使用以下逻辑判断是否应该聚合并输出：

1. **语义完整性**：使用ChatGPT判断当前缓冲区中的文本是否形成完整句子
2. **时间间隔**：如果相邻片段之间的间隔超过阈值，认为是不同的语义单元
3. **最大窗口**：如果聚合的总时长超过阈值，强制聚合
4. **最大片段数**：如果聚合的片段数超过阈值，强制聚合
5. **超时机制**：如果长时间没有新片段，强制输出当前缓冲区内容

## 重新转录流程

1. 获取所有片段的音频数据
2. 合并音频数据
3. 使用转录器重新转录合并后的音频
4. 比较重新转录结果与原始聚合结果
5. 如果有差异，更新显示并发送到翻译模块

## 使用示例

```python
from display.display import OutputRenderer
from translator.translator import NLLBTranslator
from transcribe.transcribe import AudioTranscriber, TranscriptionResult
from aggregator.semantic_aggregator import SemanticAggregator

# 初始化各个模块
renderer = OutputRenderer()
translator = NLLBTranslator()
transcriber = AudioTranscriber(model="small", device="cuda")

# 回调函数
def display_callback(sentence_id, text, state):
    renderer.display(sentence_id, text, state)
    
def translate_callback(sentence_id, text):
    translation = translator.translate(text)
    print(f"[翻译] 句子 {sentence_id}: {translation}")

# 初始化聚合器
aggregator = SemanticAggregator(
    on_display=display_callback,
    on_translate=translate_callback,
    transcriber=transcriber
)

# 添加转录结果
for result in transcription_results:
    aggregator.add_segment(result)

# 最后强制刷新缓冲区
aggregator.flush(force=True)
```

## 测试

可以使用 `test_aggregator.py` 脚本测试聚合器功能：

```bash
# 设置OpenAI API密钥
export OPENAI_API_KEY=your_api_key

# 运行测试脚本
python -m aggregator.test_aggregator
```

## 注意事项

1. 需要设置 `OPENAI_API_KEY` 环境变量才能使用ChatGPT进行句子完整性判断
2. 音频片段目录需要包含所有需要重新转录的音频文件
3. 转录器需要正确初始化，包括模型、设备和计算类型
4. 回调函数需要正确处理聚合结果，包括显示和翻译