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: preserve API signatures and discover AutoModelVLLM
zhifu gaof0728b758c34
diff --git a/.github/workflows/product-site.yml b/.github/workflows/product-site.ymlindex f463aa189..5ee0cb5fa 100644--- a/.github/workflows/product-site.yml+++ b/.github/workflows/product-site.yml@@ -15,6 +15,7 @@ on:- 'examples/openai_api/**/*.md'- 'scripts/gen_api_docs.py'- 'tests/test_*docs*.py'+ - 'tests/test_api_signatures.py'- 'gh-pages-output/**'- 'web-pages/product-site/**'- 'web-pages/scripts/**'@@ -35,6 +36,7 @@ on:- 'examples/openai_api/**/*.md'- 'scripts/gen_api_docs.py'- 'tests/test_*docs*.py'+ - 'tests/test_api_signatures.py'- 'gh-pages-output/**'- 'web-pages/product-site/**'- 'web-pages/scripts/**'@@ -89,6 +91,7 @@ jobs:tests/test_python_api_docs_contract.pytests/test_service_docs_contract.pytests/test_generated_api_docs.py+ tests/test_api_signatures.pytests/test_docs_funasr_install_commands.pytests/test_moss_transcribe_diarize_docs.py-k 'not no_download_toy_against_checkout and not browser_navigation_and_responsive_overflow and not skip_link_preserves_selection_playwright' -qdiff --git a/scripts/gen_api_docs.py b/scripts/gen_api_docs.pyindex c01abe971..9b8aa80f8 100644--- a/scripts/gen_api_docs.py+++ b/scripts/gen_api_docs.py@@ -26,7 +26,10 @@ STYLESHEET = REPO_ROOT / "gh-pages-output" / "api-reference.css"os.chdir(REPO_ROOT)tree_structure = {- "funasr.auto": {"auto_model": "funasr/auto/auto_model.py"},+ "funasr.auto": {+ "auto_model": "funasr/auto/auto_model.py",+ "auto_model_vllm": "funasr/auto/auto_model_vllm.py",+ },"funasr.register": {"register": "funasr/register.py"},"funasr.models": {},"funasr.frontends": {},@@ -115,6 +118,43 @@ def get_source_lines(filepath, node):def github_url(filepath, lineno):return f"{REPO_URL}/blob/{BRANCH}/{filepath}#L{lineno}"+def callable_signature(node, source, bound=False, constructor=False):+ """Render source expressions without importing code or evaluating defaults."""+ def expression(value):+ return ast.get_source_segment(source, value).strip()++ def argument(value, default=None, prefix=""):+ result = prefix + value.arg+ if value.annotation is not None:+ result += ": " + expression(value.annotation)+ if default is not None:+ result += (" = " if value.annotation is not None else "=") + expression(default)+ return result++ args = node.args+ positional = args.posonlyargs + args.args+ defaults = [None] * (len(positional) - len(args.defaults)) + list(args.defaults)+ static = any(isinstance(d, ast.Name) and d.id == "staticmethod"+ for d in node.decorator_list)+ start = 1 if bound and not static and positional else 0+ parts = []+ for index in range(start, len(positional)):+ parts.append(argument(positional[index], defaults[index]))+ if index + 1 == len(args.posonlyargs):+ parts.append("/")+ if args.vararg is not None:+ parts.append(argument(args.vararg, prefix="*"))+ elif args.kwonlyargs:+ parts.append("*")+ parts.extend(argument(value, default) for value, default+ in zip(args.kwonlyargs, args.kw_defaults))+ if args.kwarg is not None:+ parts.append(argument(args.kwarg, prefix="**"))+ signature = "(" + ", ".join(parts) + ")"+ if node.returns is not None and not constructor:+ signature += " -> " + expression(node.returns)+ return signature+# Extract all dataall_data = {}for top_level, sub_modules in tree_structure.items():@@ -136,27 +176,30 @@ for top_level, sub_modules in tree_structure.items():class_doc = ast.get_docstring(node) or ""src, lineno, trunc = get_source_lines(filepath, node)methods = []+ constructor = Nonefor item in node.body:if isinstance(item, (ast.FunctionDef, ast.AsyncFunctionDef)):+ if item.name == "__init__":+ constructor = {+ "signature": callable_signature(item, source, bound=True, constructor=True),+ "doc": ast.get_docstring(item) or "",+ "lineno": item.lineno,+ }if item.name.startswith("_"):continuemdoc = ast.get_docstring(item) or ""- args = [a.arg for a in item.args.args if a.arg != "self"]- if item.args.vararg: args.append("*" + item.args.vararg.arg)- if item.args.kwarg: args.append("**" + item.args.kwarg.arg)msrc, mline, mtrunc = get_source_lines(filepath, item)- methods.append({"name": item.name, "args": args, "doc": mdoc,+ methods.append({"name": item.name,+ "signature": callable_signature(item, source, bound=True), "doc": mdoc,"source": msrc, "lineno": mline, "truncated": mtrunc})entries.append({"type": "class", "name": node.name, "doc": class_doc,- "methods": methods, "source": src, "lineno": lineno,+ "methods": methods, "constructor": constructor, "source": src, "lineno": lineno,"truncated": trunc, "filepath": filepath})elif isinstance(node, ast.FunctionDef) and not node.name.startswith("_"):fdoc = ast.get_docstring(node) or ""- args = [a.arg for a in node.args.args]- if node.args.vararg: args.append("*" + node.args.vararg.arg)- if node.args.kwarg: args.append("**" + node.args.kwarg.arg)fsrc, fline, ftrunc = get_source_lines(filepath, node)- entries.append({"type": "function", "name": node.name, "args": args,+ entries.append({"type": "function", "name": node.name,+ "signature": callable_signature(node, source),"doc": fdoc, "source": fsrc, "lineno": fline,"truncated": ftrunc, "filepath": filepath})if entries:@@ -169,7 +212,20 @@ print(f"Extracted: {len(all_data)} modules, {total_entries} entries")sidebar = ""content = ""overview_links = ""+# Allocate newly documented vLLM entries after legacy entries, even though their+# navigation belongs beside AutoModel. Existing numeric deep links stay stable.+new_module = "funasr.auto.auto_model_vllm"+anchor_modules = [key for key in all_data if key != new_module]+if new_module in all_data:+ anchor_modules.append(new_module)eid = 0+for key in anchor_modules:+ for entry in all_data[key]:+ eid += 1+ entry["anchor"] = f"e{eid}"+ for method in entry.get("methods", []):+ eid += 1+ method["anchor"] = f"e{eid}"for group_index, top_level in enumerate(tree_structure):sub_modules = tree_structure[top_level]@@ -182,23 +238,30 @@ for group_index, top_level in enumerate(tree_structure):module_id = f"{group_id}-module-{module_index}"sidebar += f'<div class="l2"><button type="button" class="l2-title" aria-expanded="true" aria-controls="{module_id}"><span>{esc(sub_name)}</span><span class="arr" aria-hidden="true">▸</span></button><div class="l2-children" id="{module_id}">\n'for entry in all_data[key]:- eid += 1- eid_str = f"e{eid}"+ eid_str = entry["anchor"]filepath = entry.get("filepath", "")if entry["type"] == "class":- if entry["name"] in {"AutoModel", "RegisterTables"}:+ if entry["name"] in {"AutoModel", "AutoModelVLLM", "RegisterTables"}:overview_links += f'<a href="#{eid_str}" class="entry-link">{esc(entry["name"])} <span aria-hidden="true">→</span></a> 'sidebar += f'<a class="l3-item" href="#{eid_str}" data-target="{eid_str}"><span class="mb badge-c" aria-hidden="true">C</span><span>{esc(entry["name"])}</span></a>\n'gh_link = github_url(filepath, entry["lineno"])- content += f'<div class="api-detail" id="{eid_str}"><span class="dtag badge-c">class</span><h2>{esc(entry["name"])}</h2><div class="dmod">{key} · <a href="{gh_link}" target="_blank">View on GitHub ↗</a></div><div class="ddoc">{format_doc(entry["doc"])}</div>'+ title = esc(entry["name"])+ if entry["constructor"] is not None:+ title = '<code>' + esc(entry["name"] + entry["constructor"]["signature"]) + '</code>'+ content += f'<div class="api-detail" id="{eid_str}"><span class="dtag badge-c">class</span><h2>{title}</h2><div class="dmod">{key} · <a href="{gh_link}" target="_blank">View on GitHub ↗</a></div><div class="ddoc">{format_doc(entry["doc"])}</div>'content += f'<details class="src-block"><summary>📄 Source code</summary><pre><code>{esc(entry["source"])}</code></pre>'if entry["truncated"]:content += f'<a href="{gh_link}" target="_blank" class="src-more">View full source on GitHub →</a>'content += '</details>'+ if entry["constructor"] is not None:+ constructor = entry["constructor"]+ constructor_url = github_url(filepath, constructor["lineno"])+ content += f'<h3 class="mt">Constructor</h3><div class="mblk"><a href="{constructor_url}" class="gh-link">L{constructor["lineno"]}</a>'+ content += format_doc(constructor["doc"]) + '</div>'if entry["methods"]:content += '<h3 class="mt">Methods</h3>'for m in entry["methods"]:- sig = f'.{m["name"]}({", ".join(m["args"])})'+ sig = f'.{m["name"]}{m["signature"]}'mgh = github_url(filepath, m["lineno"])content += f'<div class="mblk"><code>{esc(sig)}</code> <a href="{mgh}" target="_blank" class="gh-link">L{m["lineno"]}</a><div class="mdoc">{format_doc(m["doc"])}</div>'content += f'<details class="src-block"><summary>📄 Source</summary><pre><code>{esc(m["source"])}</code></pre>'@@ -207,10 +270,9 @@ for group_index, top_level in enumerate(tree_structure):content += '</details></div>'content += '</div>\n'for m in entry["methods"]:- eid += 1- mid = f"e{eid}"+ mid = m["anchor"]sidebar += f'<a class="l3-item l3m" href="#{mid}" data-target="{mid}"><span class="mb badge-m" aria-hidden="true">M</span><span>.{esc(m["name"])}()</span></a>\n'- sig = f'{entry["name"]}.{m["name"]}({", ".join(m["args"])})'+ sig = f'{entry["name"]}.{m["name"]}{m["signature"]}'mgh = github_url(filepath, m["lineno"])content += f'<div class="api-detail" id="{mid}"><span class="dtag badge-m">method</span><h2><code>{esc(sig)}</code></h2><div class="dmod">{key}.{entry["name"]} · <a href="{mgh}" target="_blank">View on GitHub ↗</a></div><div class="ddoc">{format_doc(m["doc"])}</div>'content += f'<details class="src-block"><summary>📄 Source code</summary><pre><code>{esc(m["source"])}</code></pre>'@@ -218,10 +280,10 @@ for group_index, top_level in enumerate(tree_structure):content += f'<a href="{mgh}" target="_blank" class="src-more">View full source on GitHub →</a>'content += '</details></div>\n'else:- args_str = ", ".join(entry.get("args", []))+ signature = entry["name"] + entry["signature"]gh_link = github_url(filepath, entry["lineno"])sidebar += f'<a class="l3-item" href="#{eid_str}" data-target="{eid_str}"><span class="mb badge-f" aria-hidden="true">F</span><span>{esc(entry["name"])}</span></a>\n'- content += f'<div class="api-detail" id="{eid_str}"><span class="dtag badge-f">function</span><h2><code>{esc(entry["name"])}({esc(args_str)})</code></h2><div class="dmod">{key} · <a href="{gh_link}" target="_blank">View on GitHub ↗</a></div><div class="ddoc">{format_doc(entry["doc"])}</div>'+ content += f'<div class="api-detail" id="{eid_str}"><span class="dtag badge-f">function</span><h2><code>{esc(signature)}</code></h2><div class="dmod">{key} · <a href="{gh_link}" target="_blank">View on GitHub ↗</a></div><div class="ddoc">{format_doc(entry["doc"])}</div>'content += f'<details class="src-block"><summary>📄 Source code</summary><pre><code>{esc(entry["source"])}</code></pre>'if entry["truncated"]:content += f'<a href="{gh_link}" target="_blank" class="src-more">View full source on GitHub →</a>'diff --git a/tests/test_api_signatures.py b/tests/test_api_signatures.pynew file mode 100644index 000000000..d03037b7b--- /dev/null+++ b/tests/test_api_signatures.py@@ -0,0 +1,118 @@+"""Source-only API signatures must describe the callable without importing it."""++import html+from pathlib import Path+import re+import shutil+import subprocess+import sys+import tempfile+import unittest+++ROOT = Path(__file__).resolve().parents[1]+FIXTURE = '''raise RuntimeError("Documentation must never import this module")++class Example:+ def __init__(self, model: str, *, device: str = "cpu"):+ """Construct without loading weights in the documentation builder."""++ def generate(self, input, input_len=None, progress_callback=None, **cfg):+ pass++ def typed(this, value: "Tensor", /, limit: int = 3, *items: str,+ required: bool, label: str = "<tag>", **options: int) -> "Result":+ pass++ @staticmethod+ def static(self: int = 5, *, enabled=False):+ pass++ @classmethod+ def factory(cls, value=None):+ pass++def helper(value=explode(), *, required, optional=None):+ pass+'''+++def headings(page):+ return [html.unescape(re.sub(r"<[^>]*>", "", item))+ for item in re.findall(r"<h2>(.*?)</h2>", page, re.S)]+++class ApiSignatureTests(unittest.TestCase):+ @classmethod+ def setUpClass(cls):+ cls.temp = tempfile.TemporaryDirectory(prefix="funasr-signatures-")+ cls.repo = Path(cls.temp.name)+ for directory in ("scripts", "funasr/auto", "gh-pages-output"):+ (cls.repo / directory).mkdir(parents=True, exist_ok=True)+ shutil.copy2(ROOT / "scripts/gen_api_docs.py", cls.repo / "scripts")+ shutil.copy2(ROOT / "gh-pages-output/api-reference.css", cls.repo / "gh-pages-output")+ (cls.repo / "funasr/auto/auto_model.py").write_text(FIXTURE)+ (cls.repo / "funasr/register.py").write_text("def register(value=None): pass\n")+ shutil.copy2(ROOT / "funasr/auto/auto_model_vllm.py", cls.repo / "funasr/auto")+ result = subprocess.run([sys.executable, str(cls.repo / "scripts/gen_api_docs.py")],+ capture_output=True, text=True, timeout=60)+ if result.returncode:+ raise AssertionError(result.stdout + result.stderr)+ cls.pages = [(cls.repo / "gh-pages-output" / name).read_text()+ for name in ("api.html",)]++ @classmethod+ def tearDownClass(cls):+ cls.temp.cleanup()++ def test_defaults_are_visible_without_evaluation(self):+ for page in self.pages:+ self.assertIn("Example.generate(input, input_len=None, progress_callback=None, **cfg)", headings(page))+ self.assertIn("helper(value=explode(), *, required, optional=None)", headings(page))++ def test_all_argument_kinds_annotations_and_return(self):+ expected = 'Example.typed(value: "Tensor", /, limit: int = 3, *items: str, required: bool, label: str = "<tag>", **options: int) -> "Result"'+ for page in self.pages:+ self.assertIn(expected, headings(page))+ self.assertIn('<tag>', page)+ self.assertNotIn('<tag>', page)++ def test_static_and_classmethod_receivers(self):+ for page in self.pages:+ self.assertIn("Example.static(self: int = 5, *, enabled=False)", headings(page))+ self.assertIn("Example.factory(value=None)", headings(page))++ def test_constructor_is_public_without_a_new_numeric_anchor(self):+ for page in self.pages:+ self.assertIn('Example(model: str, *, device: str = "cpu")', headings(page))+ self.assertIn('Construct without loading weights', page)+ # Adding constructor details and a vLLM module must not move old links.+ old = re.findall(r'class="api-detail"[^>]*id="(e\d+)"[^>]*>.*?<h2>(.*?)</h2>', page, re.S)+ by_id = {key: html.unescape(re.sub(r'<[^>]*>', '', title)) for key, title in old}+ self.assertTrue(by_id['e1'].startswith('Example('))+ self.assertTrue(by_id['e2'].startswith('Example.generate('))+ self.assertTrue(by_id['e6'].startswith('helper('))+ self.assertTrue(by_id['e7'].startswith('register('))++ def test_real_vllm_constructor_and_discovery(self):+ for page in self.pages:+ matches = [h for h in headings(page) if h.startswith('AutoModelVLLM(')]+ self.assertEqual(len(matches), 1)+ self.assertIn('model: str, hub: str = "ms", device: str = "cuda:0"', matches[0])+ self.assertIn('tensor_parallel_size: int = 1', matches[0])+ self.assertIn('enforce_eager: bool = False, **kwargs)', matches[0])+ self.assertRegex(page, r'class="entry-link">AutoModelVLLM ')+ self.assertIn('funasr/auto/auto_model_vllm.py#L', page)++ def test_actual_auto_model_generate_defaults(self):+ with tempfile.TemporaryDirectory(prefix="funasr-signature-real-") as output:+ result = subprocess.run([sys.executable, str(ROOT / 'scripts/gen_api_docs.py'),+ '--output-dir', output], capture_output=True, text=True, timeout=60)+ self.assertEqual(result.returncode, 0, result.stderr)+ for name in ('api.html',):+ self.assertIn('AutoModel.generate(input, input_len=None, progress_callback=None, **cfg)',+ headings((Path(output) / name).read_text()))+++if __name__ == '__main__':+ unittest.main()diff --git a/tests/test_generated_api_docs.py b/tests/test_generated_api_docs.pyindex 7ab9a70a4..bee52c8a1 100644--- a/tests/test_generated_api_docs.py+++ b/tests/test_generated_api_docs.py@@ -194,7 +194,9 @@ console.log('hash routing passed');page = Page((output / "api.html").read_text())entries = page.with_class("api-detail")self.assertGreater(len(entries), 100)- self.assertEqual([attrs["id"] for _, attrs in entries],+ # New modules may be grouped beside old modules in navigation while+ # receiving IDs after legacy entries to preserve existing deep links.+ self.assertEqual(sorted((attrs["id"] for _, attrs in entries), key=lambda value: int(value[1:])),[f"e{i}" for i in range(1, len(entries) + 1)])def test_skip_link_preserves_selection_playwright(self):