Open-source speech recognition toolkit for training, inference, streaming ASR, VAD, punctuation, speaker diarization pipelines, and OpenAI-compatible/MCP serving.
Python asraudiochineseemotion-recognitionfunasrmcp-servermultilingual-asropenai-compatible-apiparaformerpunctuationpytorchreal-time-asrspeaker-diarizationspeech-recognitionspeech-to-textstreaming-asrtranscriptionvllmvoice-activity-detectionwhisper-alternative
docs: make the roadmap actionable
LauraGPT100a5f2e284c
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 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 repoFull 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.mdindex 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.### Nextdiff --git a/docs/repository_roles_zh.md b/docs/repository_roles_zh.mdindex 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.pyindex 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 textassert "v1.3.26" not in textassert "runtime-llamacpp-v0.2.6" in textassert "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 textassert "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 = (