From 100a5f2e284c7e8596e191ed7bb2513b1c27ddd7 Mon Sep 17 00:00:00 2001 From: LauraGPT <18321252+LauraGPT@users.noreply.github.com> Date: Mon, 31 Aug 2026 07:24:21 +0000 Subject: [PATCH] docs: make the roadmap actionable Signed-off-by: LauraGPT <18321252+LauraGPT@users.noreply.github.com> --- CONTRIBUTING.md | 8 +++++ docs/repository_roles.md | 38 ++++++++++++++++++++-- docs/repository_roles_zh.md | 38 ++++++++++++++++++++-- tests/test_docs_funasr_install_commands.py | 32 +++++++++++++++++- 4 files changed, 109 insertions(+), 7 deletions(-) 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 = (