Add ASR diagnostic workflow and deployment guide

app.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import json
 import math
+import shutil
 import subprocess
 import sys
 import time
@@ -196,6 +197,17 @@ def history_summary(history: dict[str, Any]) -> list[str]:
     if output_files:
         lines.append("outputs:")
         lines.extend(output_files)
+    text_outputs = []
+    for node_output in outputs.values():
+        for key in ("text", "string"):
+            values = node_output.get(key, []) or []
+            if isinstance(values, str):
+                values = [values]
+            text_outputs.extend(str(value) for value in values)
+    if text_outputs:
+        lines.append("text_outputs:")
+        for value in text_outputs:
+            lines.append(value[:2000])
     return lines
 
 
@@ -269,6 +281,66 @@ def voxcpm_tts_workflow(prefix: str) -> dict[str, Any]:
     }
 
 
+def copy_audio_to_comfy_input(audio_path: str | Path, prefix: str) -> str:
+    source = Path(audio_path)
+    if not source.exists():
+        raise FileNotFoundError(f"Uploaded audio does not exist: {source}")
+    suffix = source.suffix or ".wav"
+    filename = f"{prefix}_{uuid.uuid4().hex[:8]}{suffix}"
+    COMFY_INPUT_DIR.mkdir(parents=True, exist_ok=True)
+    shutil.copyfile(source, COMFY_INPUT_DIR / filename)
+    return filename
+
+
+def asr_workflow(audio_filename: str, prefix: str) -> dict[str, Any]:
+    return {
+        "1": {
+            "class_type": "LoadAudio",
+            "inputs": {"audio": audio_filename, "audioUI": ""},
+        },
+        "2": {
+            "class_type": "VoiceBridgeASRLoader",
+            "inputs": {
+                "repo_id": "Qwen/Qwen3-ASR-1.7B",
+                "source": "HuggingFace",
+                "precision": "bf16",
+                "attention": "sdpa",
+                "max_new_tokens": 256,
+                "forced_aligner": "Qwen/Qwen3-ForcedAligner-0.6B",
+                "local_model_path_asr": "",
+                "local_model_path_fa": "",
+            },
+        },
+        "3": {
+            "class_type": "VoiceBridgeASRTranscribe",
+            "inputs": {
+                "model_key": ["2", 0],
+                "audio": ["1", 0],
+                "language": "auto",
+                "context": "",
+                "return_timestamps": True,
+            },
+        },
+        "4": {
+            "class_type": "GenerateSRT",
+            "inputs": {
+                "forced_aligns": ["3", 0],
+                "text": ["3", 1],
+                "language": ["3", 2],
+                "save_srt": True,
+                "filename_prefix": f"VoiceBridge/{prefix}",
+            },
+        },
+        "5": {
+            "class_type": "easy showAnything",
+            "inputs": {
+                "text": "",
+                "anything": ["4", 0],
+            },
+        },
+    }
+
+
 def prepare_runtime() -> str:
     global PREPARE_PROCESS
 
@@ -278,7 +350,7 @@ def prepare_runtime() -> str:
         return "\n".join(lines)
     BOOTSTRAP_LOG.parent.mkdir(parents=True, exist_ok=True)
     log = BOOTSTRAP_LOG.open("ab")
-    command = [sys.executable, str(ROOT / "scripts" / "bootstrap_comfy.py")]
+    command = [sys.executable, str(ROOT / "scripts" / "bootstrap_comfy.py"), "--with-models"]
     PREPARE_PROCESS = subprocess.Popen(
         command,
         cwd=ROOT,
@@ -379,8 +451,33 @@ def voxcpm_tts_gpu_test() -> str:
     return "\n".join(lines)
 
 
+@spaces.GPU(duration=1800)
+def asr_gpu_test(audio_path: str | None) -> str:
+    lines = gpu_status_lines()
+    started = time.time()
+    try:
+        if not audio_path:
+            raise ValueError("Please upload an audio file before running ASR.")
+        ensure_comfy(lines)
+        prefix = f"asr_gpu_{uuid.uuid4().hex[:8]}"
+        audio_filename = copy_audio_to_comfy_input(audio_path, prefix)
+        lines.append(f"input_audio={audio_filename}")
+        prompt_id = submit_prompt(asr_workflow(audio_filename, prefix))
+        lines.append(f"prompt_id={prompt_id}")
+        history = wait_for_history(prompt_id, timeout=1800)
+        lines.extend(history_summary(history))
+        lines.append(f"elapsed_sec={time.time() - started:.1f}")
+    except Exception as exc:
+        lines.append(f"error={type(exc).__name__}: {exc}")
+        if COMFY_LOG.exists():
+            lines.append("comfy_log_tail:")
+            lines.extend(COMFY_LOG.read_text(encoding="utf-8", errors="replace").splitlines()[-180:])
+    return "\n".join(lines)
+
+
 with gr.Blocks(title="VoiceGate") as demo:
     gr.Markdown("# VoiceGate")
+    asr_audio = gr.Audio(label="ASR test audio", type="filepath")
     with gr.Row():
         prepare_run = gr.Button("Prepare")
         prepare_status_run = gr.Button("Prepare Status")
@@ -388,6 +485,7 @@ with gr.Blocks(title="VoiceGate") as demo:
         comfy_run = gr.Button("ComfyUI")
         melband_run = gr.Button("MelBand")
         voxcpm_run = gr.Button("VoxCPM TTS")
+        asr_run = gr.Button("ASR")
     output = gr.Textbox(label="Status", lines=28)
     prepare_run.click(fn=prepare_runtime, outputs=output)
     prepare_status_run.click(fn=prepare_status, outputs=output)
@@ -395,6 +493,7 @@ with gr.Blocks(title="VoiceGate") as demo:
     comfy_run.click(fn=comfy_runtime_test, outputs=output)
     melband_run.click(fn=melband_gpu_test, outputs=output)
     voxcpm_run.click(fn=voxcpm_tts_gpu_test, outputs=output)
+    asr_run.click(fn=asr_gpu_test, inputs=asr_audio, outputs=output)
 
 
 if __name__ == "__main__":

docs/hf-space-comfyui-step-by-step.zh.md

@@ -0,0 +1,372 @@
+# 从零部署 ComfyUI Workflow 到 Hugging Face Space 的操作指南
+
+本文是 VoiceGate 部署过程沉淀出来的通用指南。目标是：从一个本地
+ComfyUI workflow 出发，快速构建一个 Hugging Face Space，用 Gradio 做
+前端，用 ComfyUI 做后端，并尽量避开已经踩过的坑。
+
+## 1. 先确定部署形态
+
+推荐形态：
+
+- Space SDK：Gradio。
+- GPU：ZeroGPU，适合按需调用。
+- ComfyUI：不要直接提交整个 ComfyUI 目录到 git。
+- Custom nodes：用 bootstrap 脚本按 pinned commit 拉取。
+- 大模型：放在 Space persistent storage，例如 `/data/project_models`。
+- Secrets：只放 Hugging Face Space Secrets，不写进代码或 workflow JSON。
+
+不推荐：
+
+- 把模型权重提交到 Space git。
+- 把 API key 写进 workflow。
+- 依赖 Dev Mode 里的手动修改作为最终状态。
+- 假设 SSH 能看到 ZeroGPU CUDA。
+
+## 2. 创建 Space
+
+在 Hugging Face 创建 Space：
+
+- SDK 选择 `Gradio`。
+- Hardware 选择 ZeroGPU，例如 `zero-a10g`。
+- 如果需要持久化模型，开启 persistent storage。
+- 如果 Space 是组织名下项目，确认 token 有该组织的 Space 写权限。
+
+本地登录：
+
+```powershell
+huggingface-cli login
+huggingface-cli whoami
+```
+
+添加 Space git remote：
+
+```powershell
+git remote add space https://huggingface.co/spaces/<org>/<space-name>
+git push space main
+```
+
+## 3. 推荐目录结构
+
+```text
+project-hf/
+|-- app.py
+|-- README.md
+|-- requirements.txt
+|-- packages.txt
+|-- scripts/
+|   |-- bootstrap_comfy.py
+|   |-- run_comfy.py
+|   `-- workflow_client.py
+|-- workflows/
+|   |-- workflow_api.json
+|   `-- workflow_ui.json
+|-- docs/
+|   |-- deployment-plan.md
+|   |-- dependency-inventory.md
+|   |-- ssh-runbook.md
+|   |-- todo.md
+|   `-- work-log.md
+`-- assets/
+```
+
+本地可以保留上游项目 checkout，例如 `VoiceGate/`，但要加入 `.gitignore`。
+它只作为参考，不作为 Space runtime 内容。
+
+## 4. 先做 workflow 和依赖盘点
+
+从 ComfyUI 导出两个文件：
+
+- API workflow：用于 `/prompt` 调用。
+- UI workflow：用于人工参考节点布局。
+
+检查 API workflow：
+
+```powershell
+python -m json.tool workflows\workflow_api.json > $null
+```
+
+列出所有 `class_type`：
+
+```powershell
+python -c "import json; w=json.load(open('workflows/workflow_api.json',encoding='utf-8')); print('\n'.join(sorted({v['class_type'] for v in w.values()})))"
+```
+
+为每个 custom node 找到：
+
+- GitHub repo URL。
+- 可用 commit。
+- requirements.txt。
+- 额外系统包。
+- 模型路径约定。
+
+把这些写进 `docs/dependency-inventory.md`。
+
+## 5. 写 bootstrap 脚本
+
+`scripts/bootstrap_comfy.py` 应该是幂等的：
+
+- 如果 ComfyUI 不存在，clone。
+- 如果 custom node 不存在，clone。
+- 每个 repo checkout 到固定 commit。
+- 安装 ComfyUI requirements。
+- 安装 custom node requirements。
+- 创建模型目录和 symlink。
+- 可选下载模型。
+
+模型不要默认每次下载。建议做成：
+
+```bash
+python scripts/bootstrap_comfy.py
+python scripts/bootstrap_comfy.py --with-models
+```
+
+持久化模型路径建议：
+
+```text
+/data/project_models
+```
+
+再 symlink 到 ComfyUI 需要的位置，例如：
+
+```text
+ComfyUI/models/voxcpm/VoxCPM2
+  -> /data/project_models/voxcpm/VoxCPM2
+```
+
+## 6. 写最小 Gradio 入口
+
+ZeroGPU Space 启动时必须能发现至少一个 `@spaces.GPU` 函数，否则可能报：
+
+```text
+No @spaces.GPU function detected during startup
+```
+
+最小形式：
+
+```python
+import gradio as gr
+import spaces
+import torch
+
+@spaces.GPU(duration=60)
+def gpu_smoke_test():
+    return f"cuda_available={torch.cuda.is_available()}"
+
+with gr.Blocks() as demo:
+    button = gr.Button("GPU")
+    output = gr.Textbox()
+    button.click(gpu_smoke_test, outputs=output)
+
+demo.launch()
+```
+
+先推送这个版本，确认 Space 能运行。
+
+## 7. 正确理解 ZeroGPU、SSH、Dev Mode
+
+关键结论：
+
+- SSH 只适合诊断容器文件和 CPU 模式。
+- SSH 里通常看不到 ZeroGPU CUDA。
+- 真正的 GPU 工作必须从 Gradio 的 `@spaces.GPU(...)` 函数触发。
+- Dev Mode 开启后，运行容器可能停留在旧 commit。
+
+SSH 只在 Dev Mode 开启时可用：
+
+```powershell
+ssh -i "$env:USERPROFILE\.ssh\<key_name>" <space-user>@ssh.hf.space
+```
+
+如果 Space 一直不更新到最新 commit：
+
+- 关闭 Dev Mode。
+- push 一个新 commit 或 factory reboot。
+- 用 HF API 确认 runtime sha。
+
+## 8. 不要在 Gradio 请求里同步做重 bootstrap
+
+踩过的坑：
+
+```text
+Gradio click -> bootstrap_comfy.py -> clone -> pip install -> start ComfyUI
+```
+
+这种请求可能在几分钟后被外层 queue 中断，只看到：
+
+```text
+event: error
+data: {"error": null}
+```
+
+推荐：
+
+- `Prepare` 按钮：非 GPU，启动后台 bootstrap 进程。
+- `Prepare Status` 按钮：读取 `/tmp/bootstrap.log`。
+- GPU 按钮：只启动 ComfyUI、���交 workflow、等待结果。
+
+这样不会把 ZeroGPU 时间浪费在安装依赖上，也更容易看到真实错误。
+
+## 9. 启动 ComfyUI 并通过 API 测试
+
+ComfyUI 启动命令：
+
+```bash
+python main.py --listen 127.0.0.1 --port 8188
+```
+
+先测：
+
+```text
+GET /system_stats
+```
+
+再测最小 workflow：
+
+```text
+LoadAudio -> SaveAudioMP3
+```
+
+常用 API：
+
+- `POST /upload/image`：上传 input 文件，音频也可用这个入口。
+- `POST /prompt`：提交 API workflow。
+- `GET /history/{prompt_id}`：取执行结果。
+
+音频上传要注意二进制安全。不要用会破坏字节流的 PowerShell 文本管道。
+上传后最好校验 sha256 或至少确认 `file` 识别为音频。
+
+## 10. 分阶段测试 workflow
+
+不要一上来跑完整 workflow。推荐顺序：
+
+1. GPU smoke test：确认 CUDA 可用。
+2. ComfyUI runtime test：确认 `@spaces.GPU -> ComfyUI -> /system_stats`。
+3. Load/Save audio：确认 ComfyUI API 和音频文件路径。
+4. LLM-only：确认 secret 和外部 API。
+5. MelBand-only：确认模型加载和音频输出。
+6. TTS-only：确认 TTS 模型能进 GPU。
+7. ASR-only：确认 ASR 模型、aligner、SRT 输出。
+8. SRT split/merge。
+9. 完整短音频 workflow。
+10. 最后再做正式 Gradio UI。
+
+每一步都要记录：
+
+- 输入文件。
+- prompt id。
+- status_str。
+- outputs。
+- elapsed_sec。
+- 错误日志尾部。
+
+## 11. Secrets 的安全配置
+
+API key 放在 HF Space Secrets，例如：
+
+```text
+DEEPSEEK_API_KEY
+```
+
+代码里只读环境变量：
+
+```python
+import os
+api_key = os.environ.get("DEEPSEEK_API_KEY")
+```
+
+不要打印 key。检查时只输出：
+
+- 是否存在。
+- 长度。
+- 前后缀也尽量不要输出。
+
+## 12. 常见坑和解决办法
+
+### `No @spaces.GPU function detected`
+
+原因：ZeroGPU Space 启动时没有发现 `@spaces.GPU`。
+
+解决：在 `app.py` 保留至少一个 GPU 函数。
+
+### SSH 里 `torch.cuda.is_available()` 是 False
+
+这是正常的。SSH 不代表 ZeroGPU 执行环境。
+
+解决：从 Gradio `@spaces.GPU` 函数里测 CUDA。
+
+### Dev Mode 里代码不是最新
+
+Dev Mode 容器可能停留在旧 commit。
+
+解决：关闭 Dev Mode，重新 rebuild，或 push 新 commit。
+
+### Custom node import failed
+
+先看 ComfyUI 启动日志，通常是缺 Python 包或系统包。
+
+VoiceGate 遇到过：
+
+```text
+SoX could not be found
+ModuleNotFoundError: sounddevice
+OSError: PortAudio library not found
+ModuleNotFoundError: easydict
+ModuleNotFoundError: pytorch_lightning
+```
+
+对应修复：
+
+```text
+packages.txt: sox, libportaudio2, portaudio19-dev
+requirements.txt: sounddevice, easydict, pytorch-lightning
+```
+
+### Runtime pip install 改变 torch 版本
+
+如果 Gradio 进程已经 import torch，再在运行时 pip install/upgrade torch，
+Gradio 进程和后续子进程可能看到不同 torch 版本。
+
+解决：生产版本尽量把重依赖放进 build 阶段，并显式 pin 版本。
+
+### 模型下载 CLI 不稳定
+
+`huggingface-cli download` 或 `hf download` 可能因为版本兼容问题失败。
+
+解决：用 `huggingface_hub` 的 Python API 下载模型。
+
+### TTS/ASR 冷启动很慢
+
+大模型第一次加载会非常慢。VoiceGate 的 VoxCPM2 TTS-only 冷启动约 766 秒。
+
+解决方向：
+
+- 缩短测试文本。
+- 避免每个 GPU 调用重复启动 ComfyUI。
+- 尽量复用模型进程。
+- 先做子流程验证，再优化 UX。
+
+## 13. 最终正式化建议
+
+诊断阶段可以把很多按钮放在 `app.py` 里。正式阶段建议拆分：
+
+```text
+app.py
+scripts/bootstrap_comfy.py
+voicegate_runtime/
+|-- comfy_server.py
+|-- workflows.py
+|-- files.py
+`-- ui.py
+```
+
+正式 Gradio UI 至少提供：
+
+- 音频上传。
+- 目标语言。
+- 运行状态。
+- 生成音频下载。
+- SRT 下载。
+- 错误日志摘要。
+- 文件类型和时长限制。
+
+先限制短音频，等完整链路稳定后再支持视频和更长输入。

docs/work-log.md

@@ -19,6 +19,32 @@ and how they were resolved.
 Do not commit API keys, model weights, uploaded media, generated outputs, or the
 local `VoiceGate/` upstream checkout.
 
+## Executive Summary
+
+The Space is no longer just a blank scaffold. It can now run Gradio, invoke
+ZeroGPU, prepare a ComfyUI runtime, start ComfyUI from a GPU-backed Gradio
+function, and submit several segmented ComfyUI workflows.
+
+Confirmed working:
+
+- Hugging Face Space git push and normal rebuild flow.
+- Dev Mode SSH for CPU/container diagnostics.
+- ZeroGPU invocation from Gradio through `@spaces.GPU`.
+- ComfyUI startup from inside a `@spaces.GPU` function.
+- ComfyUI API calls from the Gradio process.
+- DeepSeek-compatible LLM node with the Space secret.
+- MelBand RoFormer smoke tests in CPU mode and ZeroGPU mode.
+- VoxCPM2 TTS-only smoke test in ZeroGPU mode.
+- Persistent model storage for VoxCPM2 and MelBand under `/data`.
+
+Not yet confirmed at the start of 2026-06-06:
+
+- VoiceBridge ASR-only workflow.
+- Qwen ASR and Qwen forced aligner model download/cache behavior in the Space.
+- SRT split -> VoxCPM -> SRT merge.
+- Full short-audio VoiceGate workflow.
+- Final user-facing Gradio upload/download UI.
+
 ## Repository Setup Completed
 
 - Created and pushed the Space wrapper repository.
@@ -161,6 +187,18 @@ def placeholder():
     ...
 ```
 
+Later this placeholder was replaced by real diagnostic functions:
+
+```python
+@spaces.GPU(duration=60)
+def gpu_smoke_test():
+    ...
+
+@spaces.GPU(duration=900)
+def comfy_runtime_test():
+    ...
+```
+
 ### SSH Does Not Expose ZeroGPU CUDA
 
 Starting ComfyUI normally through SSH failed with:
@@ -181,6 +219,52 @@ CPU diagnostic command:
 python scripts/run_comfy.py --cpu
 ```
 
+### Gradio Request Timeout During Bootstrap
+
+Long bootstrap work should not run synchronously inside a Gradio request. The
+first attempt did this:
+
+```text
+Gradio click -> bootstrap_comfy.py -> clone repos -> pip install -> start ComfyUI
+```
+
+The request was interrupted by Gradio/ZeroGPU's outer queue after roughly 2.5
+minutes and returned:
+
+```text
+event: error
+data: {"error": null}
+```
+
+Fix:
+
+- Add a non-GPU `Prepare` action that starts `scripts/bootstrap_comfy.py` as a
+  background process.
+- Add `Prepare Status` to poll `/tmp/voicegate_bootstrap.log`.
+- Keep GPU actions focused on starting ComfyUI and running actual CUDA work.
+
+This avoids wasting ZeroGPU time on clone/install steps and prevents the request
+from being killed before diagnostics can return useful logs.
+
+### Runtime Pip Install Pitfall
+
+The background bootstrap installed a large dependency set and upgraded the
+on-disk Torch package. The already-running Gradio process continued to report:
+
+```text
+torch=2.11.0+cu130
+```
+
+while the ComfyUI subprocess started afterwards reported:
+
+```text
+pytorch_version=2.12.0+cu130
+```
+
+This is workable for diagnostics, but final production should avoid heavy
+runtime `pip install` where possible. Prefer moving stable dependencies into
+Space build-time requirements or explicitly controlling pins.
+
 ## Dependency Pitfalls and Fixes
 
 `ComfyUI_AudioTools` initially failed to import.

scripts/bootstrap_comfy.py

@@ -95,11 +95,13 @@ CUSTOM_NODE_REPOS = [
 MODEL_LINKS = {
     "voxcpm2": COMFY_DIR / "models" / "voxcpm" / "VoxCPM2",
     "melband": COMFY_DIR / "models" / "diffusion_models" / "MelBandRoFormer_comfy",
+    "qwen3_asr": COMFY_DIR / "models" / "Qwen3-ASR",
 }
 
 MODEL_DIRS = {
     "voxcpm2": Path("voxcpm") / "VoxCPM2",
     "melband": Path("diffusion_models") / "MelBandRoFormer_comfy",
+    "qwen3_asr": Path("Qwen3-ASR"),
 }
 
 
@@ -197,6 +199,11 @@ def download_models(dry_run: bool = False) -> None:
             "+ hf_hub_download "
             f"Kijai/MelBandRoFormer_comfy/MelBandRoformer_fp32.safetensors -> {model_target('melband')}"
         )
+        print(f"+ snapshot_download Qwen/Qwen3-ASR-1.7B -> {model_target('qwen3_asr') / 'Qwen3-ASR-1.7B'}")
+        print(
+            "+ snapshot_download "
+            f"Qwen/Qwen3-ForcedAligner-0.6B -> {model_target('qwen3_asr') / 'Qwen3-ForcedAligner-0.6B'}"
+        )
         return
 
     from huggingface_hub import hf_hub_download, snapshot_download
@@ -212,6 +219,16 @@ def download_models(dry_run: bool = False) -> None:
         local_dir=model_target("melband"),
         token=token,
     )
+    snapshot_download(
+        repo_id="Qwen/Qwen3-ASR-1.7B",
+        local_dir=model_target("qwen3_asr") / "Qwen3-ASR-1.7B",
+        token=token,
+    )
+    snapshot_download(
+        repo_id="Qwen/Qwen3-ForcedAligner-0.6B",
+        local_dir=model_target("qwen3_asr") / "Qwen3-ForcedAligner-0.6B",
+        token=token,
+    )
 
 
 def print_summary() -> None: