modelscope/FunASR
1
0
Fork 0
mirror of https://github.com/modelscope/FunASR.git synced 2026-10-11 22:39:57 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: add community growth and contribution guides

Browse Source 
Merge pull request #2863 from codex/growth-20k
This commit is contained in:
zhifu gao
2026-05-24 20:29:56 +08:00
committed by GitHub
parent 006d1d7856
commit ba2b488e17
11 changed files with 396 additions and 91 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.github/ISSUE_TEMPLATE/ask_questions.md
+26 -23
View File
@@ -1,38 +1,41 @@
---
name: ❓ Questions/Help
about: If you have questions, please first search existing issues and docs
about: Ask for help after checking existing issues and docs
labels: 'question, needs triage'
---
Notice: In order to resolve issues more efficiently, please raise issue following the template.
（注意：为了更加高效率解决您遇到的问题，请按照模板提问，补充细节）
Notice: In order to resolve issues efficiently, please follow the template.
（注意：为了更加高效率解决您遇到的问题，请按照模板提问，补充细节。）
## ❓ Questions and Help
## Before asking
1. Search existing issues: https://github.com/modelscope/FunASR/issues
2. Search the docs: https://modelscope.github.io/FunASR/
3. Check the README quick start and deployment section.
### Before asking:
1. search the issues.
2. search the docs.
## Question
<!-- If you still can't find what you need: -->
<!-- What are you trying to do, and where are you blocked? -->
#### What is your question?
## Code or command
#### Code
```bash
<!-- Please paste a code snippet if your question requires it! -->
```
#### What have you tried?
## What have you tried?
#### What's your environment?
<!-- Include links to docs or examples you followed, plus the exact error/result. -->
- OS (e.g., Linux):
- FunASR Version (e.g., 1.0.0):
- ModelScope Version (e.g., 1.11.0):
- PyTorch Version (e.g., 2.0.0):
- How you installed funasr (`pip`, source):
- Python version:
- GPU (e.g., V100M32)
- CUDA/cuDNN version (e.g., cuda11.7):
- Docker version (e.g., funasr-runtime-sdk-cpu-0.4.1)
- Any other relevant information:
## Environment
- OS:
- Python version:
- FunASR version:
- ModelScope version:
- PyTorch / torchaudio version:
- Install method (`pip`, source, Docker):
- Device (`cuda`, `cpu`, `mps`):
- GPU model:
- CUDA/cuDNN version:
- Docker image tag, if used:
.github/ISSUE_TEMPLATE/bug_report.md
+43 -26
View File
@@ -1,47 +1,64 @@
---
name: 🐛 Bug Report
about: Submit a bug report to help us improve
about: Submit a reproducible bug report to help us improve FunASR
labels: 'bug, needs triage'
---
Notice: In order to resolve issues more efficiently, please raise issue following the template.
（注意：为了更加高效率解决您遇到的问题，请按照模板提问，补充细节）
Notice: In order to resolve issues efficiently, please follow the template and include reproducible details.
（注意：为了更加高效率解决您遇到的问题，请按照模板提问，补充可复现细节。）
## 🐛 Bug
<!-- A clear and concise description of what the bug is. -->
<!-- A clear and concise description of the bug. -->
### To Reproduce
## To Reproduce
Steps to reproduce the behavior (**always include the command you ran**):
Steps to reproduce the behavior. Always include the exact command you ran.
1. Run cmd '....'
2. See error
1. Install with: `...`
2. Run: `...`
3. See error: `...`
<!-- If you have a code sample, error messages, stack traces, please provide it here as well -->
## Code sample
<!-- Paste the smallest code sample that still reproduces the issue. -->
#### Code sample
<!-- Ideally attach a minimal code sample to reproduce the decried issue.
Minimal means having the shortest code but still preserving the bug. -->
```python
### Expected behavior
```
## Expected behavior
<!-- A clear and concise description of what you expected to happen. -->
### Environment
## Error logs
- OS (e.g., Linux):
- FunASR Version (e.g., 1.0.0):
- ModelScope Version (e.g., 1.11.0):
- PyTorch Version (e.g., 2.0.0):
- How you installed funasr (`pip`, source):
- Python version:
- GPU (e.g., V100M32)
- CUDA/cuDNN version (e.g., cuda11.7):
- Docker version (e.g., funasr-runtime-sdk-cpu-0.4.1)
- Any other relevant information:
<!-- Paste the full traceback or relevant logs. Remove private tokens and paths. -->
### Additional context
```text
<!-- Add any other context about the problem here. -->
```
## Environment
- OS:
- Python version:
- FunASR version:
- ModelScope version:
- PyTorch / torchaudio version:
- Install method (`pip`, source, Docker):
- Device (`cuda`, `cpu`, `mps`):
- GPU model:
- CUDA/cuDNN version:
- Docker image tag, if used:
## Audio details
If the audio cannot be shared, please describe:
- Duration:
- Sample rate:
- Format:
- Language/dialect:
- Speaker count:
- Background noise/music:
.github/ISSUE_TEMPLATE/config.yaml
+11 -1
View File
@@ -1 +1,11 @@
blank_issues_enabled: false
blank_issues_enabled: false
contact_links:
- name: FunASR documentation
url: https://modelscope.github.io/FunASR/
about: Read installation, tutorial, deployment, benchmark, and API docs.
- name: GitHub Discussions
url: https://github.com/modelscope/FunASR/discussions
about: Share ideas, showcase usage, and ask open-ended community questions.
- name: Hugging Face models
url: https://huggingface.co/funasr
about: Browse FunASR checkpoints on Hugging Face.
.github/ISSUE_TEMPLATE/deployment_help.md
+45
View File
@@ -0,0 +1,45 @@
---
name: 🚀 Deployment Help
about: Get help with API server, WebSocket, Docker, vLLM, Triton, Android, or agent integration
labels: 'deployment, needs triage'
---
## Deployment target
- [ ] OpenAI-compatible API server
- [ ] WebSocket streaming service
- [ ] Docker runtime
- [ ] vLLM acceleration
- [ ] Triton
- [ ] Android / mobile
- [ ] Browser / Web UI
- [ ] MCP / agent integration
- [ ] Other:
## Goal
<!-- What user-facing service or workflow are you trying to deploy? -->
## Command or config
```bash
```
## Error or unexpected behavior
```text
```
## Environment
- OS:
- Python version:
- FunASR version:
- Install method (`pip`, source, Docker):
- Device (`cuda`, `cpu`, `mps`):
- GPU model and memory:
- CUDA/cuDNN version:
- Docker image tag, if used:
- Network endpoint / port:
.github/ISSUE_TEMPLATE/feature_request.md
+27
View File
@@ -0,0 +1,27 @@
---
name: ✨ Feature Request
about: Suggest a model, language, runtime, deployment, benchmark, or documentation improvement
labels: 'enhancement, needs triage'
---
## Use case
<!-- What are you trying to build, deploy, evaluate, or research with FunASR? -->
## Proposed solution
<!-- Describe the desired model/API/runtime/doc/benchmark behavior. -->
## Alternatives or workarounds
<!-- What workaround are you using today? What other tools did you consider? -->
## Expected impact
<!-- Who benefits: new users, production deployers, researchers, agent builders, educators, etc.? -->
## Willing to contribute?
- [ ] I can submit a PR
- [ ] I can help test
- [ ] I can provide data, logs, or benchmark results
.github/PULL_REQUEST_TEMPLATE.md
+28
View File
@@ -0,0 +1,28 @@
## Summary
<!-- What changed and why? -->
## Type of change
- [ ] Bug fix
- [ ] Documentation
- [ ] Example or demo
- [ ] Runtime or deployment
- [ ] Benchmark or evaluation
- [ ] Model/training change
## Validation
<!-- Commands run, logs, screenshots, benchmark results, or why validation is not applicable. -->
- [ ] `python -m compileall funasr examples tests`
- [ ] Docs or links checked
- [ ] Runtime/deployment command tested
## User impact
<!-- Who benefits from this change? New users, production deployers, researchers, agent builders, etc. -->
## Notes for reviewers
<!-- Compatibility notes, risks, follow-up work, or review focus. -->
CONTRIBUTING.md
+55
View File
@@ -0,0 +1,55 @@
# Contributing to FunASR
Thanks for helping improve FunASR. We especially welcome contributions that make the first successful transcription faster, improve deployment reliability, or make benchmarks easier to reproduce.
## High-impact areas
- **Quick start reliability:** installation notes, CPU/GPU/MPS compatibility, dependency fixes, and runnable examples.
- **Deployment recipes:** OpenAI-compatible API, WebSocket streaming, Docker, vLLM, Triton, Android, browser, and agent integration.
- **Benchmarks:** reproducible speed, WER/CER, memory, and hardware comparison scripts.
- **Model examples:** multilingual ASR, speaker diarization, punctuation, VAD, emotion recognition, hotwords, timestamps, and fine-tuning.
- **Documentation:** shorter paths from README to working code, clearer troubleshooting, and verified links.
## Development setup
```bash
git clone https://github.com/modelscope/FunASR.git
cd FunASR
python -m venv .venv
source .venv/bin/activate
pip install -e ./
```
For docs work:
```bash
pip install -U "funasr[docs]"
cd docs
make html
```
## Before opening a pull request
Run the checks that match your change. For Python-only changes, start with:
```bash
python -m compileall funasr examples tests
```
For docs-only changes, preview the Markdown or generated HTML and verify relative links. For runtime changes, include the exact command, image tag, device, and endpoint you validated.
## Pull request checklist
- The PR has a focused scope and explains the user-facing value.
- New examples include command lines and the expected output shape.
- Bug fixes include reproduction steps or a short failure-mode explanation.
- Deployment docs list hardware, OS, Python/CUDA versions, and network endpoints.
- Large model, dataset, audio, or video files are not committed directly.
## Issue reports
Please use the templates and include environment details, exact commands, logs, and whether the audio can be shared. If audio is private, describe duration, sample rate, language, speaker count, format, and noise level.
## Maintainer focus for 20k+ stars
When reviewing changes, prioritize work that helps new users reach a good result in under five minutes, helps teams deploy FunASR privately, or gives external writers a clear story to share.
Contribution.md
+10 -39
View File
@@ -1,46 +1,17 @@
# Contributing to FunASR
First off, thanks for taking the time to contribute! 🎉
Thanks for taking the time to contribute to FunASR.
The following is a set of guidelines for contributing to FunASR. These are mostly guidelines, not rules. Use your best judgment, and feel free to propose changes to this document in a pull request.
The canonical contribution guide is now [CONTRIBUTING.md](./CONTRIBUTING.md). It covers the development setup, high-impact contribution areas, validation expectations, pull request checklist, and issue-reporting guidance.
## How Can I Contribute?
## Quick links
### Reporting Bugs
- [Bug reports](https://github.com/modelscope/FunASR/issues/new?template=bug_report.md)
- [Questions and help](https://github.com/modelscope/FunASR/issues/new?template=ask_questions.md)
- [Documentation fixes](https://github.com/modelscope/FunASR/issues/new?template=error_docs.md)
- [Feature requests](https://github.com/modelscope/FunASR/issues/new?template=feature_request.md)
- [Pull requests](https://github.com/modelscope/FunASR/pulls)
This section guides you through submitting a bug report for FunASR. Following these guidelines helps maintainers and the community understand your report, reproduce the behavior, and find related reports.
## Maintainer priorities
- **Ensure the bug was not already reported** by searching on GitHub under Issues.
- If you're unable to find an open issue addressing the problem, open a new one. Be sure to include a **title and clear description**, as much relevant information as possible, and a **code sample** or an **executable test case** demonstrating the expected behavior that is not occurring.
### Suggesting Enhancements
This section guides you through submitting an enhancement suggestion for FunASR, including completely new features and minor improvements to existing functionality.
- **Ensure the enhancement was not already suggested** by searching on GitHub under Issues.
- If you find an enhancement that matches your suggestion, feel free to add your comments to the existing issue.
- If you don't find an existing issue, you can open a new one. Be sure to include a **title and clear description**, as much relevant information as possible, and a **code sample** or an **executable test case** demonstrating the expected behavior.
### Pull Requests
The process described here has several goals:
- Maintain FunASR's quality
- Fix problems that are important to users
- Engage the community in working toward the best possible FunASR
Please follow these steps to have your contribution considered by the maintainers:
1. **Fork** the repository.
2. **Clone** your fork: `git clone https://github.com/alibaba/FunASR.git`
3. **Create a branch** for your changes: `git checkout -b my-new-feature`
4. **Make your changes**.
5. **Commit your changes**: `git commit -am 'Add some feature'`
6. **Push to the branch**: `git push origin my-new-feature`
7. **Create a new Pull Request**.
### Code of Conduct
This project and everyone participating in it is governed by the FunASR Code of Conduct. By participating, you are expected to uphold this code.
Thank you for contributing to FunASR!
The most valuable contributions help new users reach a successful transcription quickly, make private deployment easier, or make benchmark results easier to reproduce.
README.md
+2 -1
View File
@@ -21,7 +21,7 @@
</p>
<p align="center">
<a href="#quick-start">Quick Start</a> · <a href="#benchmark">Benchmark</a> · <a href="#model-zoo">Models</a> · <a href="https://modelscope.github.io/FunASR/agent.html">Agent Integration</a> · <a href="https://modelscope.github.io/FunASR/">Docs</a>
<a href="#quick-start">Quick Start</a> · <a href="#benchmark">Benchmark</a> · <a href="#model-zoo">Models</a> · <a href="https://modelscope.github.io/FunASR/agent.html">Agent Integration</a> · <a href="https://modelscope.github.io/FunASR/">Docs</a> · <a href="./CONTRIBUTING.md">Contribute</a>
</p>
---
@@ -194,6 +194,7 @@ docker pull registry.cn-hangzhou.aliyuncs.com/funasr_repo/funasr:funasr-runtime-
|---|---|
| 📖 [Documentation](https://modelscope.github.io/FunASR/) | 🐛 [Issues](https://github.com/modelscope/FunASR/issues) |
| 💬 [Discussions](https://github.com/modelscope/FunASR/discussions) | 🤗 [HuggingFace](https://huggingface.co/funasr) |
| 🤝 [Contributing](./CONTRIBUTING.md) | 📈 [20k growth plan](./docs/community_growth_20k.md) |
## Star History
README_zh.md
+2 -1
View File
@@ -21,7 +21,7 @@
</p>
<p align="center">
<a href="#快速开始">快速开始</a> · <a href="#性能评测">性能评测</a> · <a href="#模型列表">模型列表</a> · <a href="https://modelscope.github.io/FunASR/agent.html">Agent 集成</a> · <a href="https://modelscope.github.io/FunASR/zh/">文档</a>
<a href="#快速开始">快速开始</a> · <a href="#性能评测">性能评测</a> · <a href="#模型列表">模型列表</a> · <a href="https://modelscope.github.io/FunASR/agent.html">Agent 集成</a> · <a href="https://modelscope.github.io/FunASR/zh/">文档</a> · <a href="./CONTRIBUTING.md">贡献</a>
</p>
---
@@ -193,6 +193,7 @@ docker pull registry.cn-hangzhou.aliyuncs.com/funasr_repo/funasr:funasr-runtime-
|---|---|
| 📖 [文档](https://modelscope.github.io/FunASR/zh/) | 🐛 [问题反馈](https://github.com/modelscope/FunASR/issues) |
| 💬 [讨论](https://github.com/modelscope/FunASR/discussions) | 🤗 [HuggingFace](https://huggingface.co/funasr) |
| 🤝 [贡献指南](./CONTRIBUTING.md) | 📈 [20k 增长计划](./docs/community_growth_20k.md) |
## Star 趋势
docs/community_growth_20k.md
+147
View File
@@ -0,0 +1,147 @@
# FunASR Community Growth Plan: 20,000+ GitHub Stars
Baseline on 2026-05-24: `modelscope/FunASR` has about 16.2k GitHub stars. The next target is 20k+ stars, which means earning roughly 3.8k additional stars through better onboarding, stronger proof, and repeatable launches.
This plan focuses on useful adoption work rather than vanity marketing: if more users can install, evaluate, deploy, and share FunASR successfully, stars follow naturally.
## North-star metrics
- GitHub stars: 20,000+
- Monthly PyPI downloads: sustained growth after each release
- README quick-start success: first transcription in under 5 minutes
- Deployment success: API server, WebSocket, Docker, and vLLM examples verified on fresh machines
- Community throughput: faster issue triage, more external PRs, more user showcases
## Audience segments
| Audience | What they need | Repository surface that should serve them |
|---|---|---|
| ASR developers | Fast local transcript, model choice, Python API | README quick start, tutorial, model zoo |
| Production teams | Private deployment, streaming, API compatibility, Docker | runtime docs, OpenAI API example, vLLM guide |
| Agent builders | Speech input to Claude/Cursor/LangChain/Dify/AutoGen | MCP server and OpenAI API examples |
| Researchers | Benchmarks, reproducibility, citations, model details | benchmark report, docs, model cards |
| Chinese users | Chinese docs, ModelScope path, deployment in China | README_zh, docs/zh, ModelScope links |
| International users | English docs, Hugging Face path, comparison with Whisper | README, HF models, benchmark story |
## Workstream 1: Convert first-time visitors
- Keep the README first screen focused on speed, supported tasks, one-call usage, and links to docs.
- Keep the benchmark table close to the quick start, with exact benchmark scope and full report link.
- Maintain a short model-selection table: SenseVoice, Paraformer, Fun-ASR-Nano, Qwen3-ASR, GLM-ASR, streaming, punctuation, VAD, speaker, emotion.
- Add visible links to deployment, agent integration, contribution, and discussions.
- Avoid burying install and first inference behind long research history.
## Workstream 2: Make deployment shareable
- Verify `funasr-server --device cuda` on a clean GPU machine and publish the exact command/output.
- Add curl examples for `/v1/audio/transcriptions` and WebSocket streaming.
- Keep Docker image tags explicit and document CPU/GPU differences.
- Add a small deployment decision table: Python API vs OpenAI API vs WebSocket vs Docker vs vLLM vs Triton.
- Turn common deployment failures into FAQ entries.
## Workstream 3: Launch content that earns stars
Use one release note or article per clear story:
- "FunASR is 170x realtime and CPU viable for long audio."
- "Self-hosted OpenAI-compatible speech transcription with one command."
- "Streaming ASR with VAD, punctuation, and speaker diarization."
- "MCP speech input for Claude/Cursor and agent workflows."
- "vLLM acceleration for Fun-ASR-Nano."
- "Chinese dialect, accent, meeting, and industrial ASR examples."
For each launch, prepare:
- GitHub release notes with GIF/screenshot or terminal output
- README update and docs link
- Hugging Face and ModelScope model-card update
- Homepage update on `modelscope.github.io/FunASR`
- Short posts for developer communities
- A pinned GitHub discussion for feedback
## Workstream 4: Community operations
- Use issue templates to collect reproducible environment, audio, and deployment details.
- Triage issues weekly with labels: bug, question, documentation, deployment, enhancement, good first issue.
- Convert repeated support answers into docs within 48 hours.
- Keep 5-10 `good first issue` tasks ready for contributors.
- Thank external contributors in release notes.
## Workstream 5: External proof
- Publish reproducible benchmark scripts and raw configuration for the 184-file benchmark.
- Encourage users to share production stories, dashboards, or public demos.
- Add third-party integrations and community projects to README when they are maintained and runnable.
- Keep citations and paper links visible for researchers.
## 30-day execution checklist
### Week 1: Repository conversion
- [ ] Verify README quick start on clean CPU and GPU environments.
- [ ] Verify all README links and docs links.
- [ ] Add or refresh CONTRIBUTING, PR template, and issue templates.
- [ ] Add a short FAQ for install/deployment failures.
- [ ] Confirm GitHub repo description and topics mention ASR, speech-recognition, streaming, diarization, OpenAI-compatible API, MCP, and vLLM.
### Week 2: Deployment proof
- [ ] Publish API server curl examples.
- [ ] Publish WebSocket streaming examples.
- [ ] Validate Docker CPU and GPU images.
- [ ] Validate vLLM guide on one GPU server.
- [ ] Record concise terminal outputs for release notes.
### Week 3: Launch package
- [ ] Create a GitHub release focused on one sharp value proposition.
- [ ] Update PyPI release description if needed.
- [ ] Update Hugging Face organization/model cards.
- [ ] Update ModelScope model cards and demos.
- [ ] Update homepage hero and docs entry points.
### Week 4: Distribution and feedback
- [ ] Share the release in relevant developer communities.
- [ ] Pin a GitHub discussion for the release.
- [ ] Triage all new issues within 48 hours.
- [ ] Convert top 3 support questions into docs.
- [ ] Track stars, PyPI downloads, issue volume, and docs traffic.
## Release-note template
````markdown
## Why this release matters
FunASR now lets you ...
## Try it in 60 seconds
```bash
pip install -U funasr
funasr-server --device cuda
```
## Highlights
- ...
- ...
- ...
## Verified environments
- GPU:
- CPU:
- Docker:
## Links
- Quick start:
- Deployment guide:
- Benchmark:
- Discussion:
````
## 中文摘要
目标不是单纯“求 Star”，而是让更多用户能更快完成安装、转写、部署和分享。FunASR 距离 20k stars 还需要约 3.8k 增量，最有效的抓手是：首屏转化、可复现 benchmark、OpenAI 兼容 API/流式/vLLM/Docker 部署闭环、HF/ModelScope/官网同步更新，以及高效的 issue/PR 社区运营。