Skip to content

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

docs: make the roadmap actionable

LauraGPT100a5f2e284c
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 7c61430a3..a659d519a 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -17,6 +17,14 @@ FunASR spans four repositories. Before opening an issue or PR, check which repo
Full details: [Repository roles & roadmap](./docs/repository_roles.md) ([中文](./docs/repository_roles_zh.md))
+## Find a task
+
+- [good first issue](https://github.com/modelscope/FunASR/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) lists bounded work with a clear starting point.
+- [help wanted](https://github.com/modelscope/FunASR/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) lists work that needs community hardware, domain knowledge, or implementation capacity.
+- [ready for PR](https://github.com/modelscope/FunASR/issues?q=is%3Aissue+is%3Aopen+label%3A%22ready+for+PR%22) lists work whose expected behavior and acceptance evidence are defined.
+
+Read the complete issue timeline and comment before starting so work is not duplicated. An issue marked `needs feedback` is waiting for reporter or hardware validation; a related PR may merge while the issue remains open. The roadmap's [contributor table](./docs/repository_roles.md#contribute-to-the-roadmap) lists current hardware and upstream-review needs.
+
## High-impact areas
- **Quick start reliability:** installation notes, CPU/GPU/MPS compatibility, dependency fixes, and runnable examples.
diff --git a/docs/repository_roles.md b/docs/repository_roles.md
index ed2a4ff22..ccc07cbcd 100644
--- a/docs/repository_roles.md
+++ b/docs/repository_roles.md
@@ -5,7 +5,7 @@ This document explains the responsibility boundaries, user entry points, and iss
> **Directional roadmap, not a release promise.**
> This document records shipped capabilities and active work, but does not commit to
> future version numbers or dates. The current Python release is
-> [`funasr==1.4.9`](https://github.com/modelscope/FunASR/releases/tag/v1.4.9).
+> [`funasr==1.4.11`](https://github.com/modelscope/FunASR/releases/tag/v1.4.11).
> Any future breaking release still requires a maintainer-approved milestone and
> migration plan.
@@ -37,7 +37,7 @@ The four repositories share models and tooling but their responsibility boundari
|---|---|
| Use Python for speech recognition / training / fine-tuning | [modelscope/FunASR](https://github.com/modelscope/FunASR) |
| Deploy a realtime streaming ASR service, recommend **Fun-ASR-Nano + vLLM** | [modelscope/FunASR/fun_asr_nano](https://github.com/modelscope/FunASR/tree/main/examples/industrial_data_pretraining/fun_asr_nano) — **canonical implementation, see below** |
-| Transcribe long multi-speaker audio with timestamps and speaker identities in one model pass | [MOSS-Transcribe-Diarize deployment guide](./moss_transcribe_diarize.md) — an OpenMOSS model integrated with FunASR through local Transformers or vLLM, and independently available through native SGLang Omni; no separate external VAD or speaker model |
+| Transcribe long multi-speaker audio with timestamps and anonymous speaker labels in one model pass | [MOSS-Transcribe-Diarize deployment guide](./moss_transcribe_diarize.md) — an OpenMOSS model integrated with FunASR through local Transformers or vLLM, and independently available through native SGLang Omni; no separate external VAD or speaker model |
| Understand Fun-ASR-Nano / MLT capabilities, checkpoints, benchmarks, or use Transformers / vLLM / GGUF integrations | [QwenAudio/Fun-ASR](https://github.com/QwenAudio/Fun-ASR) |
| Use emotion recognition / audio event detection | [QwenAudio/SenseVoice](https://github.com/QwenAudio/SenseVoice) |
| Generate video subtitles / clip videos | [modelscope/FunClip](https://github.com/modelscope/FunClip) |
@@ -75,6 +75,37 @@ The four repositories share models and tooling but their responsibility boundari
---
+## Contribute to the roadmap
+
+The roadmap is a queue of testable outcomes, not a list reserved for maintainers. Use the live [help wanted](https://github.com/modelscope/FunASR/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) and [ready for PR](https://github.com/modelscope/FunASR/issues?q=is%3Aissue+is%3Aopen+label%3A%22ready+for+PR%22) queries instead of copying a static task list. Smaller bounded tasks are listed under [good first issue](https://github.com/modelscope/FunASR/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22).
+
+| Label | What it means |
+|---|---|
+| `good first issue` | The scope is bounded and maintainers can point to the relevant code or documentation. |
+| `help wanted` | The outcome matters, but maintainer hardware, domain knowledge, or implementation capacity is missing. |
+| `ready for PR` | The expected behavior and acceptance evidence are clear enough to implement. Comment before starting so work is not duplicated. |
+| `needs feedback` | A reporter or hardware owner is validating an outcome. A merged PR or release alone is not a reason to close the issue. |
+
+### Work that needs contributors now
+
+| Area | Current question | Acceptance evidence | Especially useful contribution |
+|---|---|---|---|
+| [Realtime preview efficiency on L20-class GPUs](https://github.com/modelscope/FunASR/issues/3528) | After matching the number of partial messages, which refresh interval and partial window provide the best latency/throughput trade-off without silently skipping previews? | Client JSONL and `--log-decode-profile` server logs from the exact commit, with SPK, ping, audio, concurrency, partial window, and partial-message count held constant | Reproduction on L20, L4, A10, or other non-H100 GPUs; analysis of queue, encoder, and engine time |
+| [AMD Windows Vulkan stability](https://github.com/modelscope/FunASR/issues/3479) | Does the current runtime reach model initialization and transcription on the reporter's AMD GPU, and where is the last successful initialization boundary if it does not? | Exact archive name and SHA256, GPU/driver/Windows versions, full initialization log, and a reporter hardware retest | AMD Windows hardware owners and Vulkan/llama.cpp contributors |
+| [Complete public checkpoint functionality](https://github.com/modelscope/FunASR/issues/3496) | How should the missing CTC tensors be published from an authorized model-owner account and validated after upload? | Immutable model revision, file hashes, public clean-cache download, and real timestamp/diarization inference | Model owners with Hugging Face write access and checkpoint validation experience |
+| [Upstream model integrations](https://github.com/huggingface/transformers/pull/46180) | Can Fun-ASR-Nano remain compatible with upstream Transformers while preserving pinned model-card and regression-test boundaries? | Exact-head upstream CI, focused local tests, model-card review, and maintainer review | Transformers reviewers and users who can test downstream loading before merge |
+
+### Before claiming an item
+
+1. Read the complete issue timeline and confirm that no contributor is already working on it.
+2. Comment with the environment or part you can own and the evidence you plan to produce.
+3. Base conclusions on an exact commit, immutable model revision or release asset, and include the command needed to reproduce them.
+4. Keep issue and PR closure separate: implementation can merge while reporter validation remains open.
+
+Contributions and issue evidence may be written in Chinese or English. A roadmap or repository-role change should update both this file and [`repository_roles_zh.md`](./repository_roles_zh.md) in the same PR.
+
+---
+
## Roadmap (directional)
> Each item links to an existing issue or PR where available. Items without an owner or acceptance evidence do not have completion dates.
@@ -91,7 +122,8 @@ The four repositories share models and tooling but their responsibility boundari
- **Fun-ASR-Nano native Transformers integration** — [huggingface/transformers#46180](https://github.com/huggingface/transformers/pull/46180) is in review; use the PR's exact-head CI and review state as the source of truth.
- **Restore complete public checkpoint functionality** — [#3496](https://github.com/modelscope/FunASR/issues/3496) tracks missing CTC tensors needed by timestamp and diarization paths in the Hugging Face checkpoint.
-- **Realtime concurrency regression** — [#3528](https://github.com/modelscope/FunASR/issues/3528) remains open for reproducible load-test evidence and a bounded fix.
+- **Realtime preview efficiency and L20 validation** — [#3528](https://github.com/modelscope/FunASR/issues/3528) established that v1.3.9 appeared faster by silently skipping most partial previews while its event loop was blocked. The issue remains open for equal-work L20 profiling and a deliberate refresh/window policy; it is not treated as a resolved throughput regression.
+- **Qwen3-ASR offline vLLM workflow** — [#3592](https://github.com/modelscope/FunASR/pull/3592) adds a tested native `Qwen3ASRModel.LLM` example. [#3419](https://github.com/modelscope/FunASR/issues/3419) remains open until the reporter's 8–9% CER result can be reproduced with an exact model revision, service configuration, and scoring script.
- **AMD Windows Vulkan validation** — [#3479](https://github.com/modelscope/FunASR/issues/3479) remains open for reporter hardware retesting against `runtime-llamacpp-v0.2.6`; publication of the archive is not evidence that the hardware crash is fixed.
### Next
diff --git a/docs/repository_roles_zh.md b/docs/repository_roles_zh.md
index 0a77cfb1a..034a883ed 100644
--- a/docs/repository_roles_zh.md
+++ b/docs/repository_roles_zh.md
@@ -4,7 +4,7 @@
> **方向性路线图,不是版本承诺。**
> 本文档记录已交付能力与正在推进的工作,但不承诺未来版本号或日期。当前 Python
-> 版本是 [`funasr==1.4.9`](https://github.com/modelscope/FunASR/releases/tag/v1.4.9)。
+> 版本是 [`funasr==1.4.11`](https://github.com/modelscope/FunASR/releases/tag/v1.4.11)。
> 任何未来的 breaking release 仍需 maintainer 确认 milestone 与迁移方案。
---
@@ -35,7 +35,7 @@
|---|---|
| 用 Python 做语音识别 / 训练 / 微调 | [modelscope/FunASR](https://github.com/modelscope/FunASR) |
| 部署实时流式 ASR 服务,推荐 Fun-ASR-Nano + vLLM 做实时识别 | [modelscope/FunASR/fun_asr_nano](https://github.com/modelscope/FunASR/tree/main/examples/industrial_data_pretraining/fun_asr_nano) —— **推荐实现,见下节** |
-| 用一个模型完成长音频多人转写、时间戳与说话人身份识别 | [MOSS-Transcribe-Diarize 部署指南](./moss_transcribe_diarize_zh.md) —— OpenMOSS 模型通过本地 Transformers 或 vLLM 接入 FunASR,也可通过原生 SGLang Omni 独立服务,不需要额外的外部 VAD 或说话人模型 |
+| 用一个模型完成长音频多人转写、时间戳与匿名说话人标签 | [MOSS-Transcribe-Diarize 部署指南](./moss_transcribe_diarize_zh.md) —— OpenMOSS 模型通过本地 Transformers 或 vLLM 接入 FunASR,也可通过原生 SGLang Omni 独立服务,不需要额外的外部 VAD 或说话人模型 |
| 了解 Fun-ASR-Nano / MLT 的能力范围、权重、评测,或使用 Transformers / vLLM / GGUF 集成 | [QwenAudio/Fun-ASR](https://github.com/QwenAudio/Fun-ASR) |
| 需要情感识别 / 音频事件检测 | [QwenAudio/SenseVoice](https://github.com/QwenAudio/SenseVoice) |
| 做视频字幕 / 剪辑 | [modelscope/FunClip](https://github.com/modelscope/FunClip) |
@@ -73,6 +73,37 @@
---
+## 参与路线图
+
+路线图是一组可验收的结果,不是只有维护者才能处理的愿望清单。请从实时的 [help wanted](https://github.com/modelscope/FunASR/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) 和 [ready for PR](https://github.com/modelscope/FunASR/issues?q=is%3Aissue+is%3Aopen+label%3A%22ready+for+PR%22) 查询中选择任务,避免复制很快过期的静态清单。范围较小的任务位于 [good first issue](https://github.com/modelscope/FunASR/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)。
+
+| 标签 | 含义 |
+|---|---|
+| `good first issue` | 范围已有边界,维护者可以指出相关代码或文档。 |
+| `help wanted` | 结果重要,但仍缺维护者没有的硬件、领域知识或实现精力。 |
+| `ready for PR` | 预期行为和验收证据已经足够明确,可以开始实现;动手前先留言,避免重复劳动。 |
+| `needs feedback` | 正等待报告者或硬件所有者验证结果。仅有 PR 合并或版本发布不能作为关闭 issue 的理由。 |
+
+### 当前需要贡献者的工作
+
+| 方向 | 当前问题 | 验收证据 | 特别有价值的贡献 |
+|---|---|---|---|
+| [L20 等 GPU 上的实时预览效率](https://github.com/modelscope/FunASR/issues/3528) | 对齐 partial 消息数量后,怎样选择刷新间隔和 partial window,才能在不静默跳过预览的前提下取得合适的延迟/吞吐平衡? | 基于 exact commit 的客户端 JSONL 和 `--log-decode-profile` 服务端日志;固定 SPK、ping、音频、并发数、partial window 与 partial 消息数量 | 在 L20、L4、A10 或其他非 H100 GPU 上复现,并分析 queue、encoder 与 engine 时间 |
+| [AMD Windows Vulkan 稳定性](https://github.com/modelscope/FunASR/issues/3479) | 当前 runtime 能否在报告者的 AMD GPU 上完成模型初始化和转写;若不能,最后成功的初始化边界在哪里? | 精确压缩包名称和 SHA256、GPU/驱动/Windows 版本、完整初始化日志,以及报告者硬件复测 | AMD Windows 硬件所有者和 Vulkan/llama.cpp 贡献者 |
+| [恢复公开 checkpoint 的完整能力](https://github.com/modelscope/FunASR/issues/3496) | 如何从有权限的模型所有者账号发布缺失 CTC tensors,并在上传后完成验证? | 不可变模型 revision、文件哈希、公开 clean-cache 回下载和真实时间戳/说话人推理 | 有 Hugging Face 写权限的模型所有者和 checkpoint 验证贡献者 |
+| [上游模型集成](https://github.com/huggingface/transformers/pull/46180) | 如何让 Fun-ASR-Nano 保持 Transformers 上游兼容,同时保留固定的 model card 和回归测试边界? | exact-head 上游 CI、聚焦本地测试、model card review 与维护者 review | Transformers reviewer,以及能在合并前验证下游加载的用户 |
+
+### 认领前
+
+1. 读完 issue 的完整时间线,确认没有其他贡献者正在处理。
+2. 留言说明可以负责的环境或模块,以及计划提供的证据。
+3. 结论必须基于 exact commit、不可变模型 revision 或 release asset,并附可复现命令。
+4. 区分 issue 与 PR 的关闭条件:实现可以合并,但报告者验证仍可保持开放。
+
+贡献和 issue 证据可以使用中文或英文。路线图或仓库职责变更应在同一个 PR 中同步更新本文与 [`repository_roles.md`](./repository_roles.md)。
+
+---
+
## 路线图(方向性)
> 每一项均链接到现有 issue / PR。没有 owner 或验收证据的条目不写完成日期。
@@ -89,7 +120,8 @@
- **Fun-ASR-Nano 的 Transformers 原生集成** —— [huggingface/transformers#46180](https://github.com/huggingface/transformers/pull/46180) 正在审查;以该 PR 的 exact-head CI 与 review 状态为准。
- **恢复公开 checkpoint 的完整能力** —— [#3496](https://github.com/modelscope/FunASR/issues/3496) 跟踪 Hugging Face checkpoint 缺少时间戳与说话人路径所需 CTC tensors 的问题。
-- **实时并发性能回归** —— [#3528](https://github.com/modelscope/FunASR/issues/3528) 保持开放,等待可复现的压测证据与有边界的修复。
+- **实时预览效率与 L20 验证** —— [#3528](https://github.com/modelscope/FunASR/issues/3528) 已确认 v1.3.9 看似更快,是因为事件循环阻塞时静默跳过了大部分 partial 预览。该 issue 继续开放,用于等工作量的 L20 profiling 和明确的刷新/window 策略;不能把它当成已经解决的吞吐回退。
+- **Qwen3-ASR 离线 vLLM 工作流** —— [#3592](https://github.com/modelscope/FunASR/pull/3592) 增加经过验证的原生 `Qwen3ASRModel.LLM` 示例。[#3419](https://github.com/modelscope/FunASR/issues/3419) 继续开放,直到能用精确模型 revision、服务配置和评分脚本复现报告者的 8–9% CER。
- **AMD Windows Vulkan 验证** —— [#3479](https://github.com/modelscope/FunASR/issues/3479) 保持开放,等待报告者在 `runtime-llamacpp-v0.2.6` 上进行硬件复测;发布压缩包不等于硬件崩溃已经修复。
### 下一步
diff --git a/tests/test_docs_funasr_install_commands.py b/tests/test_docs_funasr_install_commands.py
index 74dcfbbfd..18f6ef3ba 100644
--- a/tests/test_docs_funasr_install_commands.py
+++ b/tests/test_docs_funasr_install_commands.py
@@ -371,7 +371,7 @@ def test_repository_roadmap_tracks_current_delivery_and_open_work():
]
for text in docs:
- assert "1.4.9" in text
+ assert "1.4.11" in text
assert "v1.3.26" not in text
assert "runtime-llamacpp-v0.2.6" in text
assert "MOSS-Transcribe-Diarize" in text
@@ -380,6 +380,36 @@ def test_repository_roadmap_tracks_current_delivery_and_open_work():
assert "https://github.com/modelscope/FunASR/issues/3479" in text
assert "https://github.com/huggingface/transformers/pull/46180" in text
+ assert "speaker identities" not in docs[0]
+ assert "说话人身份识别" not in docs[1]
+
+
+def test_repository_roadmap_exposes_live_contribution_entry_points():
+ docs = [
+ (ROOT / "docs/repository_roles.md").read_text(),
+ (ROOT / "docs/repository_roles_zh.md").read_text(),
+ ]
+ live_queries = [
+ "is%3Aissue+is%3Aopen+label%3A%22help+wanted%22",
+ "is%3Aissue+is%3Aopen+label%3A%22ready+for+PR%22",
+ ]
+
+ for text in docs:
+ for query in live_queries:
+ assert query in text
+ assert "needs feedback" in text
+
+ assert "exact commit" in docs[0]
+ assert "acceptance evidence" in docs[0]
+ assert "exact commit" in docs[1]
+ assert "验收证据" in docs[1]
+
+ contributing = (ROOT / "CONTRIBUTING.md").read_text()
+ assert "## Find a task" in contributing
+ for query in live_queries:
+ assert query in contributing
+ assert "needs feedback" in contributing
+
def test_realtime_demo_documents_partial_and_hotword_boundaries():
text = (