maxkb/MEDIA_ASYNC_GUIDE.md

# 音视频异步处理使用指南

## 🎯 概述

音视频处理现已完全异步化，提供详细的状态追踪和更好的用户体验。

## 📋 状态流程

```
📋 排队中 (PENDING) 
    ↓
🔄 生成中 (STARTED) 
    ↓
📚 索引中 (STARTED) 
    ↓
✅ 完成 (SUCCESS)
    ↓
💥 失败 (FAILURE)
```

## 🚀 使用方式

### 1. 上传音视频文件

```python
# 上传时指定STT和LLM模型
document_data = {
    'name': '会议录音.mp3',
    'source_file_id': file_id,
    'stt_model_id': 'whisper-large',  # 必需
    'llm_model_id': 'gpt-4',         # 可选，用于文本优化
}

# 系统会自动：
# 1. 创建文档
# 2. 设置状态为"排队中"
# 3. 提交异步任务
```

### 2. 查看处理状态

```python
# 获取文档状态
document = Document.objects.get(id=document_id)
status = Status(document.status)
embedding_status = status[TaskType.EMBEDDING]

# 状态映射
status_map = {
    '0': '排队中',
    '1': '生成中/索引中',
    '2': '完成',
    '3': '失败',
    '4': '已取消'
}

current_status = status_map.get(embedding_status.value, '未知')
print(f"当前状态: {current_status}")
```

### 3. 批量处理

```python
# 批量上传多个音视频文件
documents = [
    {'name': '录音1.mp3', 'stt_model_id': 'whisper-large'},
    {'name': '视频1.mp4', 'stt_model_id': 'whisper-large'},
    {'name': '录音2.mp3', 'stt_model_id': 'whisper-large'},
]

# 系统会：
# 1. 为每个文档创建独立的异步任务
# 2. 并行处理多个文件
# 3. 提供独立的状态追踪
```

## 🎛️ 配置选项

### 处理选项
```python
options = {
    'enable_punctuation': True,    # 启用标点符号优化
    'enable_summary': True,        # 启用摘要生成
    'language': 'auto',            # 语言检测
    'segment_duration': 300,       # 分段时长（秒）
    'async_processing': True       # 异步处理（默认启用）
}
```

### 模型配置
```python
# STT模型（必需）
stt_model_id = 'whisper-large'  # 语音转写模型

# LLM模型（可选）
llm_model_id = 'gpt-4'         # 文本优化和摘要生成
```

## 📊 状态说明

| 状态 | 代码 | 描述 | 用户可见 |
|------|------|------|----------|
| 排队中 | PENDING | 任务已提交，等待处理 | ✅ |
| 生成中 | STARTED | 正在转写音视频内容 | ✅ |
| 索引中 | STARTED | 正在创建段落和索引 | ✅ |
| 完成 | SUCCESS | 处理完成 | ✅ |
| 失败 | FAILURE | 处理失败 | ✅ |
| 已取消 | REVOKE | 任务已取消 | ✅ |

## 🔧 错误处理

### 自动重试
- 网络错误自动重试
- 模型调用失败自动重试
- 最多重试3次

### 失败处理
```python
# 检查失败原因
if embedding_status == State.FAILURE:
    # 查看错误日志
    # 检查模型配置
    # 手动重新处理
```

### 重新处理
```python
# 手动触发重新处理
from knowledge.tasks.media_learning import media_learning_by_document
media_learning_by_document.delay(
    document_id, knowledge_id, workspace_id, 
    stt_model_id, llm_model_id
)
```

## 📈 性能优化

### 并发处理
- 多个工作线程并行处理
- 每个音视频文件独立处理
- 支持批量上传和处理

### 资源管理
- 自动清理临时文件
- 内存使用优化
- 处理超时保护

### 队列管理
- 任务队列优先级
- 失败任务重试队列
- 任务状态监控

## 🎯 最佳实践

### 1. 文件准备
- 使用支持的音频格式：MP3, WAV, M4A
- 使用支持的视频格式：MP4, AVI, MOV
- 确保文件大小在合理范围内

### 2. 模型选择
- 根据语言选择合适的STT模型
- 根据需求选择是否使用LLM优化
- 测试模型性能和准确性

### 3. 批量处理
- 合理控制批量上传的数量
- 监控系统资源使用情况
- 避免在高峰期大量上传

### 4. 状态监控
- 定期检查处理状态
- 及时处理失败的任务
- 记录处理统计信息

## 🔍 故障排除

### 常见问题

1. **任务卡在排队中**
   - 检查Celery服务是否运行
   - 检查任务队列是否正常
   - 查看系统资源使用情况

2. **转写质量差**
   - 检查音频质量
   - 尝试不同的STT模型
   - 调整语言设置

3. **处理失败**
   - 查看详细错误日志
   - 检查模型配置
   - 验证文件格式

4. **索引创建失败**
   - 检查向量模型配置
   - 验证数据库连接
   - 检查磁盘空间

### 日志查看
```bash
# 查看异步任务日志
tail -f /var/log/celery/worker.log

# 查看应用日志
tail -f /var/log/maxkb/application.log
```

## 📝 API示例

### 上传音视频文件
```python
import requests

# 上传文件
files = {'file': open('meeting.mp3', 'rb')}
data = {
    'name': '会议录音',
    'stt_model_id': 'whisper-large',
    'llm_model_id': 'gpt-4'
}

response = requests.post(
    'http://localhost:8000/api/knowledge/{knowledge_id}/document/',
    files=files,
    data=data
)
```

### 查看文档状态
```python
import requests

# 获取文档状态
response = requests.get(
    f'http://localhost:8000/api/knowledge/document/{document_id}/'
)

document = response.json()
status = document['status']
print(f"文档状态: {status}")
```

## 🎉 总结

音视频异步处理提供了：
- ✅ 完全异步化的处理流程
- ✅ 详细的状态追踪和反馈
- ✅ 强大的错误处理和重试机制
- ✅ 高性能的并发处理能力
- ✅ 灵活的配置选项
- ✅ 完善的监控和日志

这大大提升了用户体验和系统稳定性！