feat(server): add --model-path and --hub options to funasr-server

[liudonghua123]

• Add --model-path argument for local model or model ID override
• Add --hub argument to specify model hub (ms for ModelScope, hf for HuggingFace)
• Support custom model loading via AutoModel with specified path and hub
• Update API endpoints to handle 'custom' model type

Summary

Type of change

• Bug fix
• Documentation
• Example or demo
• Runtime or deployment
• Benchmark or evaluation
• Model/training change

Validation

• python -m compileall funasr examples tests
• Docs or links checked
• Runtime/deployment command tested

User impact

Nothing.

Notes for reviewers

[gemini-code-assist]

Code Review

This pull request adds support for custom local model paths and model hubs (ModelScope or HuggingFace) to the FunASR server by introducing --model-path and --hub CLI arguments. The review feedback highlights critical issues where loading a custom model via the fallback mechanism would crash due to missing configuration keys, and default models would fail to load because the hub defaults to ModelScope instead of HuggingFace when no custom path is specified.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

If a custom model_path is provided, the model name (e.g., "custom" or "fun-asr-nano") might not be present in FALLBACK_CONFIGS. Currently, _load_fallback will return None for any name not in FALLBACK_CONFIGS, causing a crash when attempting to load or run the custom model. We should allow fallback loading for custom models by returning {} from FALLBACK_CONFIGS and only returning None if app.state.model_path is not set.

Suggested change

	return None
	from funasr import AutoModel
	cfg = FALLBACK_CONFIGS[name].copy()
	if not app.state.model_path:
	return None
	from funasr import AutoModel
	cfg = FALLBACK_CONFIGS.get(name, {}).copy()

[gemini-code-assist]

The default hub for the fun-asr-nano model is "hf" (HuggingFace). Since app.state.hub defaults to "ms" (ModelScope), if the user does not provide a custom model_path, the server will attempt to load the default "FunAudioLLM/Fun-ASR-Nano-2512" model from ModelScope, which will fail. We should only use app.state.hub if a custom model_path is provided.

Suggested change

	vllm_hub = app.state.hub if app.state.hub else "hf"
	vllm_hub = app.state.hub if app.state.model_path else "hf"

[gemini-code-assist]

Similar to the vLLM loader, the fallback loader for fun-asr-nano should only use app.state.hub if a custom model_path is provided, to avoid attempting to load the default HuggingFace model from ModelScope.

Suggested change

	"hub": app.state.hub if app.state.hub else "hf",
	"hub": app.state.hub if app.state.model_path else "hf",

[LauraGPT]

Thanks for the contribution. I think this needs one more pass before merge: the new custom model path does not appear to load correctly when users run the documented command with only --model-path.

In create_app(..., preload_model="auto", model_path=...), the preload branch calls _load_fallback(preload_model if preload_model != "auto" else "custom"), but custom is not in FALLBACK_CONFIGS. That means _load_fallback("custom") will not have a config to copy. Later, a request with model=custom calls _process_fallback(preload_model, ...), which is still auto for the documented command, so it also does not map cleanly to a loaded model.

Could you add a small test or manual validation log for the two intended paths?

1. funasr-server --model-path /path/to/model --hub ms
2. funasr-server --model-path FunAudioLLM/Fun-ASR-Nano-2512 --hub hf --model fun-asr-nano

A simpler implementation may be to choose the serving id explicitly when model_path is set, store the custom model under that id, and make /v1/models plus model=custom resolve to the same loaded entry.

[LauraGPT]

Maintainer follow-up pushed in 1dbf9bfc and synced with current main in 05bc48a9.

This addresses the blocking server-loader review items:

• default fun-asr-nano now keeps using the Hugging Face hub unless a custom --model-path is provided;
• AutoModel fallback for default fun-asr-nano uses the same hub rule;
• custom model paths can load through an empty fallback config and are cached under the custom key.

Validation on ind-gpu8:

• python3 -m py_compile funasr/bin/_server_app.py funasr/bin/server.py tests/test_server_app_openai_segments.py
• python3 -m pytest -q tests/test_cli.py tests/test_server_app_openai_segments.py -q -> 8 passed
• git diff --check