Skip to content

Open-source speech recognition toolkit for training, inference, streaming ASR, VAD, punctuation, speaker diarization pipelines, and OpenAI-compatible/MCP serving.

docs: add Colab quickstart troubleshooting notes

zhifu gao5953ad55430b
diff --git a/examples/colab/README.md b/examples/colab/README.md
index 9c8ae73ff..819400f89 100644
--- a/examples/colab/README.md
+++ b/examples/colab/README.md
@@ -21,4 +21,14 @@ Run FunASR in a browser without preparing a local Python environment.
- If you are evaluating production deployment, use the [deployment matrix](../../docs/deployment_matrix.md) after the notebook works.
- For OpenAI-compatible HTTP service testing, use [examples/openai_api](../openai_api/).
+## Troubleshooting
+
+| Symptom | What to try |
+|---|---|
+| Colab runtime disconnects or resets | Reconnect the runtime, rerun the install cell, then rerun the model cell. The notebook does not persist Python packages across runtime resets. |
+| GPU is unavailable | Use `Runtime > Change runtime type > GPU`. If no GPU is assigned, the notebook still works on CPU for a short smoke test. |
+| Model download is slow | Rerun the cell after the network recovers. The first run downloads model files and later runs in the same runtime are faster. |
+| Uploaded audio fails or is too large | Try a short WAV/MP3 first. For long files, trim a representative sample before using Colab. |
+| Output is unexpected | Save the transcript JSON cell output and include it when opening an issue. |
+
Notebook source: [funasr_quickstart.ipynb](https://github.com/modelscope/FunASR/blob/main/examples/colab/funasr_quickstart.ipynb).
diff --git a/examples/colab/README_ja.md b/examples/colab/README_ja.md
index 0b3bae57b..dcc69acdc 100644
--- a/examples/colab/README_ja.md
+++ b/examples/colab/README_ja.md
@@ -21,4 +21,14 @@
- 本番デプロイを評価する場合は、notebook が動いた後に [deployment matrix](../../docs/deployment_matrix.md) を確認してください。
- OpenAI 互換 HTTP サービスを試す場合は [examples/openai_api](../openai_api/README_ja.md) を利用してください。
+## トラブルシューティング
+
+| 症状 | 対処 |
+|---|---|
+| Colab runtime が切断またはリセットされる | runtime に再接続し、install cell を実行してから model cell を再実行します。runtime リセット後は Python パッケージが保持されません。 |
+| GPU が使えない | `Runtime > Change runtime type > GPU` に変更します。GPU が割り当てられない場合でも、短い smoke test は CPU で実行できます。 |
+| モデルのダウンロードが遅い | ネットワークが回復してから cell を再実行します。初回はモデルファイルをダウンロードし、同じ runtime の後続実行は速くなります。 |
+| アップロードした音声が失敗する、または大きすぎる | まず短い WAV/MP3 で確認してください。長い音声は代表的な区間に切り出してから Colab で試します。 |
+| 出力が期待と違う | transcript JSON cell の出力を保存し、issue を作成するときに添付してください。 |
+
Notebook source: [funasr_quickstart.ipynb](https://github.com/modelscope/FunASR/blob/main/examples/colab/funasr_quickstart.ipynb).
diff --git a/examples/colab/README_ko.md b/examples/colab/README_ko.md
index f41ea1e35..cd46207d4 100644
--- a/examples/colab/README_ko.md
+++ b/examples/colab/README_ko.md
@@ -21,4 +21,14 @@
- 프로덕션 배포를 검토하려면 notebook을 먼저 실행한 뒤 [deployment matrix](../../docs/deployment_matrix.md)를 확인하세요.
- OpenAI 호환 HTTP 서비스를 테스트하려면 [examples/openai_api](../openai_api/README_ko.md)를 사용하세요.
+## 문제 해결
+
+| 증상 | 해결 방법 |
+|---|---|
+| Colab runtime이 끊기거나 재설정됨 | runtime에 다시 연결한 뒤 install cell을 먼저 실행하고 model cell을 다시 실행하세요. runtime이 재설정되면 설치된 Python 패키지가 유지되지 않습니다. |
+| GPU를 사용할 수 없음 | `Runtime > Change runtime type > GPU`로 변경하세요. GPU가 배정되지 않아도 짧은 smoke test는 CPU로 실행할 수 있습니다. |
+| 모델 다운로드가 느림 | 네트워크가 안정된 뒤 cell을 다시 실행하세요. 첫 실행은 모델 파일을 다운로드하며, 같은 runtime의 이후 실행은 더 빠릅니다. |
+| 업로드한 오디오가 실패하거나 너무 큼 | 먼저 짧은 WAV/MP3로 확인하세요. 긴 오디오는 대표 구간을 잘라 Colab에서 테스트하는 것이 좋습니다. |
+| 출력이 예상과 다름 | transcript JSON cell 출력을 저장하고 issue를 열 때 함께 첨부하세요. |
+
Notebook source: [funasr_quickstart.ipynb](https://github.com/modelscope/FunASR/blob/main/examples/colab/funasr_quickstart.ipynb).
diff --git a/examples/colab/README_zh.md b/examples/colab/README_zh.md
index e1ef5183c..db2b7420a 100644
--- a/examples/colab/README_zh.md
+++ b/examples/colab/README_zh.md
@@ -21,4 +21,14 @@
- 如果要评估生产部署,先跑通 notebook,再阅读 [部署选型表](../../docs/deployment_matrix_zh.md)。
- 如果要测试 OpenAI 兼容 HTTP 服务,请使用 [examples/openai_api](../openai_api/README_zh.md)。
+## 故障排查
+
+| 现象 | 处理方式 |
+|---|---|
+| Colab runtime 断开或重置 | 重新连接 runtime,先重跑安装单元,再重跑模型单元。runtime 重置后不会保留已安装的 Python 包。 |
+| 没有 GPU | 通过 `Runtime > Change runtime type > GPU` 切换。没有分配到 GPU 时,短音频 smoke test 仍可用 CPU 跑通。 |
+| 模型下载很慢 | 网络恢复后重跑该单元。第一次运行会下载模型文件,同一个 runtime 后续运行会更快。 |
+| 上传音频失败或文件太大 | 先用短 WAV/MP3 验证。长音频建议截取有代表性的片段再放到 Colab。 |
+| 输出不符合预期 | 保存 transcript JSON 单元输出,提交 issue 时一起附上。 |
+
Notebook 源文件:[funasr_quickstart.ipynb](https://github.com/modelscope/FunASR/blob/main/examples/colab/funasr_quickstart.ipynb)。