建议给一个 roadmap

[qiulang]

我读完 community_growth_20k.md 我觉得应该再有一个 roadmap， 制定下一步的发展方向，甚至包括哪些 help wanted .

另外有个小问题，我好像以前也问过，但是看了 community_growth_20k 也没搞懂，就是 FunAudioLLM/Fun-ASR 这个项目的作用, 我能理解 FunAudioLLM 要强调 LLM-ASR model， 但还是搞不太清和 modelscope/FunASR 分工在哪里；另外如果作为使用者，需要知道 FunAudioLLM/Fun-ASR 这个项目吗？

Repository	Role in the ecosystem	Growth surface
modelscope/FunASR	Core toolkit, Python package, runtime services, deployment docs	First-run success, production deployment, issue/PR operations
FunAudioLLM/Fun-ASR	Fun-ASR-Nano model family and LLM-ASR identity	Model cards, Transformers integration, benchmarks, vLLM/GGUF stories

我们关于 Fun-ASR-Nano 问题讨论也都是在 modelscope/FunASR 里不是在 FunAudioLLM/Fun-ASR | Fun-ASR-Nano
然后我读 modelscope/FunASR 的 serve_realtime_ws.py 和 FunAudioLLM的 serve_realtime_ws.py 觉得它们基本一样，但差异的地方又让人糊涂， 比如 modelscope/FunASR 有 get_partial_decode_audio 但 FunAudioLLM 的 没有，可是 get_partial_decode_audio 我们也讨论过几次，为什么 会一个有一个没有？

[LauraGPT]

这个问题提得非常对。当前两个仓库的边界和重复示例没有表达清楚，确实会让使用者困惑；get_partial_decode_audio 的差异也不是有意设计成两套能力，而是 toolkit 侧的长语音/并发修复没有同步到模型仓库。

我们后续按下面的边界维护：

Repository	Canonical responsibility
modelscope/FunASR	Python toolkit、运行时服务、部署、训练/微调能力，以及生产使用问题和 issue/PR
FunAudioLLM/Fun-ASR	Fun-ASR-Nano / MLT 模型家族、checkpoint/model card、模型评测，以及 Transformers、vLLM、GGUF 等模型级集成

因此，普通使用者如果只需要通过 Python 包或服务部署 ASR，关注 modelscope/FunASR 即可；需要选择 Nano/MLT checkpoint、了解模型能力或使用特定推理框架时，再看 FunAudioLLM/Fun-ASR。

对两份 serve_realtime_ws.py，我们会把 toolkit 版本作为生产实现的 canonical source，并推进三件事：

1. 在模型仓库明确链接 canonical 实现，停止把两份独立副本同时当作权威版本。
2. 同步当前缺失的 partial-window、WebSocket 参数和 dtype 等修复，并增加防漂移验证。
3. 优先修复长会话开启 speaker 后状态持续增长的问题，做长时间 soak test 后再推广这条部署路径。

Roadmap 会按 Now / Next / Later 落到仓库文档并拆出 help-wanted：

• Now: realtime speaker 长会话稳定性、版本/发布一致性、Transformers 原生集成收尾。
• Next: 四仓统一 repo-role 表、经过验证的集成矩阵、明确的 issue 路由和 help-wanted。
• Later: 官方可用 demo、容器化及稳定的 headless/API 工作流。

感谢把这个问题具体指出来。这个 issue 保持打开，直到 roadmap 和仓库边界文档真正落地。

[qiulang]

@LauraGPT 我又读了一遍 serve_realtime_ws.py 觉得还是有个隐藏的问题： audio_buffer 会不断增加

# L526 handler:每收到一个二进制帧调用一次
session.add_audio(message)

# L263:
self.audio_buffer = np.concatenate([self.audio_buffer, audio_float])   # ← 整块重拷

session.reset() 只是在 一开始 START 调用一次，所以如果ws一直开着，内存拷贝会out of memory, 比如简单估算 16kHz float32 = 64 KB/s;客户端 100ms 一帧 → 每秒 10 次 np.concatenate,每次拷贝整个已累积 buffer。全程拷贝量 ≈ 32 KB × T² / chunk_sec

我不知道我没有用哪里没看对，你再确认一下

[LauraGPT]

你没有看错。我按当前 main（defff40e）把数据流重新走了一遍，结论是这个问题确实存在，而且比单纯的 audio_buffer 常驻还要严重一些。

1. audio_buffer 只在收到 START 时通过 session.reset() 清空；STOP 只做 final decode 并把 is_active 设为 false，不会释放缓冲区。长连接只发一次 START 时，原始音频会保留整个会话。
2. 每个二进制 WebSocket message 都会执行 np.concatenate([旧 buffer, 新 frame])，因此累计拷贝量是二次方。按 16 kHz、float32、100 ms 一帧计算，30 分钟时 buffer 本体约 115.2 MB，但累计内存拷贝约 1.04 TB；1 小时约 4.15 TB。你的复杂度判断是对的，具体常数取决于客户端每帧时长。
3. partial_window_sec 只限制临时 ASR re-decode 使用的尾部窗口，并没有裁剪 audio_buffer，所以它不能解决这里的内存和拷贝问题。
4. 开启 speaker 后问题会进一步放大：all_chunks 保存的是从 audio_buffer 切出的 NumPy slice；对足够长的 chunk，这些 slice 与当时的完整 buffer 共享内存，可能让旧版本的大 buffer 在后续 concatenate 后仍不能释放。同时 all_embeddings 持续增长，每个新片段都会重新 torch.cat 并聚类全部历史 embedding。
5. locked_sentences 也会一直增长，并在每次 partial response 中完整序列化，不过这通常是次于前两项的放大因素。

所以这不是你漏看了某个清理路径，而是当前实现的真实长会话缺陷，也与 #3101 开启 speaker 后 30-60 分钟断线的复测结果吻合。我会把代码修复继续集中在 #3101：需要同时引入有绝对时间偏移的有界音频存储、不会引用旧大数组的 speaker chunk、以及有界或增量的 speaker 状态，不能只在现有数组上加一个简单 truncate。修复前可靠的规避方式仍是关闭 speaker，或按固定时长 STOP/重新 START 轮换 session。

[qiulang]

从 3101描述那还真是。我最近一个项目做asr，所以就希望能对funasr 也贡献一点力量 （所以这个issue 提了想看看有没有 help wanted我能帮忙的），以后项目可能不做asr，就没精力再做贡献了。

另外我看你的提交代码的密集程度，简直是惊人！ 一方面说明确实是能者多劳，但另一方面也说明可能真的需要有“真人”做 code review

[LauraGPT]

@qiulang 谢谢你愿意在这段时间贡献，也谢谢你明确提醒需要人工 code review。这个方向同意：外部贡献的 PR 会保留给 maintainer 做人工审核，不会自动合并。

我先把这个 issue 标成 help wanted 和 ready for PR。为了不让你被 #3101 的 speaker 状态设计选择卡住，有一个可以独立完成、独立 review 的文档任务：

1. 新增 docs/repository_roles_zh.md 和对应英文 docs/repository_roles.md。
2. 用表格说明 FunASR / Fun-ASR / SenseVoice / FunClip 的 canonical responsibility、用户入口和 issue 路由。
3. 加入 Now / Next / Later roadmap；用现有 issue/PR 链接表达进度，不承诺无法保证的发布日期。
4. 明确 realtime WebSocket 服务以 modelscope/FunASR 版本为 canonical source，模型仓库只链接它，不再把两份副本都描述为权威实现。
5. 从 README.md、README_zh.md 和 CONTRIBUTING.md 加入清晰入口。

验收重点是链接可达、四仓边界一致、没有复制新的服务代码。你如果愿意接这个任务，可以在这里回复“我来做”，或者直接开标题类似 Docs: clarify repository roles and roadmap (#3203) 的 PR。

#3101 的有界音频和 speaker 状态修复继续作为单独技术任务推进，避免一个 PR 同时承担文档治理和高风险实时服务改造。

[qiulang]

这个我可以做，不过我还是想知道funasr下一步方向是什么 ，比如你说的 “Later: 官方可用 demo、容器化及稳定的 headless/API 工作流。“
官方可用dmo, 容器化指什么，example 目录下不是有很多这样的例子吗？

roadmap 我本来想到是 1.4.x 1.5x 主要做什么 2.x又规划做什么

[LauraGPT]

可以，这个文档任务就由你来做；我不会同时另开一份重复 PR。

你指出得对，我前面写的“官方可用 demo、容器化及稳定的 headless/API 工作流”太抽象。examples/ 里确实已经有很多 demo，缺的不是“再多放几个示例”，而是下面这些可验证的产品化入口：

• 官方可用 demo：从顶层 README 能找到一个 canonical 入口；依赖锁定；有固定测试音频和启动 smoke test；CPU/GPU 支持范围写清楚；不是若干脚本都声称自己是推荐入口。
• 容器化：有版本化的 CPU/CUDA 镜像和构建 CI，而不只是 Docker 命令片段；模型缓存、端口、健康检查、GPU 参数和升级方式有稳定约定。
• headless/API：不依赖 Gradio 或浏览器操作的 CLI/HTTP/gRPC/WebSocket 路径；请求/响应可机器解析；有健康检查、错误码和兼容性测试，适合服务与 agent 调用。

关于你说的 1.4.x / 1.5.x / 2.x：我刚核对了当前发布状态。仓库没有已建立的 milestone，GitHub Python tag 到 v1.3.13，PyPI 已是 1.3.14；目前没有经过核心 maintainer 确认的 1.4/1.5/2.0 边界。因此我们不能在文档 PR 里自行承诺版本号或发布日期。

这次 PR 请先写成 directional roadmap，并单独注明 “Versioned release roadmap: pending maintainer confirmation”：

• Now：修复 realtime 长会话有界状态（即時轉錄一段時間後會自行斷線 #3101）；完成 Fun-ASR-Nano Transformers 集成（Add Fun-ASR-Nano model huggingface/transformers#46180）；明确四仓职责和 issue 路由（建议给一个 roadmap #3203）。
• Next：收敛重复 realtime 服务到 canonical source；建立经过 smoke test 的 Python/CLI/WebSocket/容器支持矩阵；补稳定的 headless API 契约和部署入口。
• Later：在上述接口与兼容性测试稳定后，再评估需要 breaking changes 的 2.x；版本号由 core maintainer 通过 milestone/release plan 确认。

每一项尽量链接现有 issue/PR；没有 owner 或验收证据的内容不要写完成日期。你可以按这个范围直接开 Docs: clarify repository roles and roadmap (#3203)，PR 会保留给 maintainer 做人工 review。