test/docs/TODO/ENTROPY_REDUCTION_PLAN.md

熵减执行清单

本文档记录本轮已执行的熵减工作。目标是移除不可达路径、兼容占位、隐藏 fallback、重复请求流水线和无用依赖。

范围

• 主范围：app/、根运行配置、公开运行文档。
• 不处理：vendor/qwenasr 内部实现、仅 benchmark 使用且不阻塞主链路的代码。
• 原则：开发中项目不保留废弃接口、旧字段、兼容层或 fallback 逻辑。

P0

• 移除 Qwen3 transformers 后端残留路径。
  • 删除后端选择里的 "transformers" fallback。
  • 删除仅服务该路径的 batch/segment 转换死代码。
  • 不支持的设备显式失败。
• 启动预加载改为 fail-fast。
  • 模型完整性检查或预加载失败时停止 worker。
  • 不再静默降级到首次请求加载。
• 移除被忽略的离线模型兼容参数。
  • 删除 REST model_id 兼容处理。
  • 删除 OpenAI transcription model 兼容处理。
  • 运行时模型选择统一由部署计划和 QWEN3_ASR_MODEL 控制。

P1

• 抽出共享离线转写服务。
  • API 层只处理协议输入和响应格式。
  • 音频准备、OfflineASRRequest、runtime 调用和清理边界集中到服务层。
• 合并音频字节处理逻辑。
  • process_from_request 和 process_upload_file 共享私有 byte 处理 helper。

P2

• 将 .tsscale sidecar 隐式耦合改为显式结构化元数据。
• 拆分 WebSocket 路由和 Qwen3 协议服务。
  • Qwen3 websocket 状态机移出 API route。
  • route 模块仅保留端点注册和 service delegation。
• 删除首轮发现的无用 helper。
• 审计并移除无用直接依赖。
  • 根环境和 CPU 环境移除直接依赖 pydub、httpx。
  • 保留 ModelScope/FunASR 动态 runtime 依赖。
• 继续压缩阿里协议 WebSocket service。
  • 删除大段注释、未使用状态、未使用参数和死函数。
  • 合并重复响应构造。
  • 删除重复音频转换。

验证

• uv run python -m py_compile $(find app -name '*.py' -not -path '*/__pycache__/*') start.py
• uvx pyright
• 变更模块 import smoke check。
• 手工 API smoke plan 已记录：
  • /stream/v1/asr
  • /v1/audio/transcriptions
  • /ws/v1/asr/funasr
  • /ws/v1/asr/qwen

手工 Smoke Plan

启动服务并准备模型后执行：

1. POST /stream/v1/asr，使用小 WAV request body，确认返回 result、segments、duration、processing_time。
2. POST /v1/audio/transcriptions，使用 multipart file 和 response_format=verbose_json，确认返回 OpenAI 风格 text 和 segments。
3. 连接 /ws/v1/asr/funasr，发送阿里兼容 start/audio/stop 消息，确认 sentence 事件仍正常返回。
4. 连接 /ws/v1/asr/qwen，发送 start/audio/stop 消息，确认 partial/final 事件仍正常返回。