WebSocketAPI参考

WebSocket API 参考

WebSocket 端点提供任务状态的全双工同步与实时流式传输。客户端连接后接收服务器推送的 JSON 消息，以获取细粒度的进度与数据流。

---

连接端点

端点	说明
ws://{host}:{port}/ws/progress/{task_id}	订阅指定任务的实时进度

参数: task_id — 由 POST /api/task/execute 返回的 UUID 字符串

认证: 无需认证（内网部署场景）

---

消息枚举

通用消息结构

{
  "status": "<StatusT>",
  "step": "<StepT>",
  "message": "<string>"
}

StatusT 枚举

值	含义	触发条件
"processing"	任务正在执行中	Worker 在处理某个步骤时持续推送
"completed"	任务全部步骤成功完成	最后一个 Worker 完成工作
"error"	任务执行失败	任意 Worker 捕获异常

StepT 枚举

值	含义	推送来源
"extract_audio"	正在从视频中提取音频	workers/extract.py
"downloading"	正在下载 Whisper 模型	workers/transcribe.py
"transcribing"	正在执行语音识别	workers/transcribe.py
"translating"	正在执行 LLM 翻译	workers/translate.py
"done"	任务完成	各 Worker 结束信号

---

各阶段消息详情

1. 音频提取阶段

{
  "status": "processing",
  "step": "extract_audio",
  "extracted_time": 120.5
}

字段	类型	说明
extracted_time	float	当前已提取的音频时长（秒），由 FFmpeg 进度回调提供

2. 模型下载阶段

{
  "status": "processing",
  "step": "downloading",
  "downloaded_mb": 1536.2
}

字段	类型	说明
downloaded_mb	float	已下载的模型文件大小（MB）

3. 语音识别阶段

{
  "status": "processing",
  "step": "transcribing",
  "progress": "00:01:00,000 -> 00:01:05,500",
  "text": "Hello world, this is a test."
}

字段	类型	说明
progress	string	当前识别的字幕时间区间（SRT 格式）
text	string	该时间段识别出的文本内容

4. LLM 翻译阶段

{
  "status": "processing",
  "step": "translating",
  "message": "⚡ 正在全速并发翻译中... (已完成 3/10 批)"
}

字段	类型	说明
message	string	翻译进度描述（含批次计数）

5. 任务完成

{
  "status": "completed",
  "step": "done",
  "message": "全量任务流水线完美收官！"
}

6. 任务错误

{
  "status": "error",
  "message": "音频提取失败: 缺少视频源文件..."
}

字段	类型	说明
message	string	具体错误描述（从异常对象提取）

---

错误码参考

WebSocket 本身不定义 HTTP 状态码。错误通过消息中的 status: "error" 和 message 字段传递。

常见错误场景：

错误信息模式	可能原因	解决建议
"音频提取失败: ..."	FFmpeg 无法处理输入文件	检查视频格式是否受支持
"模型下载失败: ..."	HF_TOKEN 无效或网络不通	配置代理或检查 HuggingFace Token
"语音识别失败: ..."	模型未下载或显存不足	使用更小模型（tiny/base）
"翻译失败: ..."	LLM API Key 无效或超时	检查 API Key 和网络连通性
"当前选定的模型 [xxx] 正在后台下载中"	重复提交了依赖同模型的任务	等待首次下载完成后再提交

---

前端消费示例

WebSocket 连接

const ws = new WebSocket(`ws://${location.host}/ws/progress/${taskId}`);

ws.onmessage = (event) => {
    const msg = JSON.parse(event.data);

    switch (msg.status) {
        case "processing":
            updateProgressBar(msg.step, msg);
            break;
        case "completed":
            markTaskDone(taskId);
            ws.close();
            break;
        case "error":
            showError(msg.message);
            ws.close();
            break;
    }
};

ws.onerror = () => {
    console.error("WebSocket 连接失败");
};

---

连接管理注意事项

1. 心跳保活: 客户端不需要主动发送心跳；服务器端 while True: await websocket.receive_text() 循环持续等待客户端消息，连接断开时自动触发 WebSocketDisconnect 清理
2. 一对多广播: 同一 task 支持多个 WebSocket 连接同时订阅（如多标签页），每条消息会广播给所有订阅者
3. 自动清理: 发送失败（客户端已断开）的连接会自动从活跃列表中移除
4. 无会话保持: WebSocket 连接不要求认证，适合内网/本地部署场景

---

相关文档

• REST API 参考 — HTTP 端点完整文档
• WebSocket 通信架构 — 底层实现原理