maxkb/MEDIA_ASYNC_GUIDE.md

音视频异步处理使用指南

🎯 概述

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

📋 状态流程

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

🚀 使用方式

1. 上传音视频文件

# 上传时指定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. 查看处理状态

# 获取文档状态
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. 批量处理

# 批量上传多个音视频文件
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. 提供独立的状态追踪

🎛️ 配置选项

处理选项

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

模型配置

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

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

📊 状态说明

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

🔧 错误处理

自动重试

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

失败处理

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

重新处理

# 手动触发重新处理
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. 索引创建失败

   • 检查向量模型配置
   • 验证数据库连接
   • 检查磁盘空间

日志查看

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

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

📝 API示例

上传音视频文件

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
)

查看文档状态

import requests

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

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

🎉 总结

音视频异步处理提供了：

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

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