Merge pull request #3711 from modelscope/codex/sensevoice-punctuation-doc-20260915

docs(punctuation): clarify SenseVoice postprocessing

.github/workflows/test-punctuation-docs.yml

@@ -0,0 +1,32 @@
+name: Validate punctuation documentation
+
+on:
+  pull_request:
+    paths:
+      - 'funasr/models/ct_transformer/model.py'
+      - 'tests/test_ct_transformer_docs.py'
+      - '.github/workflows/test-punctuation-docs.yml'
+  push:
+    branches: [main]
+    paths:
+      - 'funasr/models/ct_transformer/model.py'
+      - 'tests/test_ct_transformer_docs.py'
+      - '.github/workflows/test-punctuation-docs.yml'
+
+permissions:
+  contents: read
+
+jobs:
+  docs-contract:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.pull_request.head.sha || github.sha }}
+          persist-credentials: false
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - name: Check punctuation guidance without model dependencies
+        run: python tests/test_ct_transformer_docs.py -v

funasr/models/ct_transformer/model.py

@@ -46,8 +46,9 @@ class CTTransformer(torch.nn.Module):
     Output: {"key": "...", "text": "punctuated text", "punc_array": Tensor}
     punc_array encoding: 1=none, 2=comma(，), 3=period(。), 4=question(？)
 
-    Note: Not needed for Fun-ASR-Nano/SenseVoice/Qwen3-ASR (they output punctuation natively).
-    Only required for Paraformer models.
+    For unpunctuated SenseVoiceSmall or Paraformer output, configure punc_model
+    when punctuation is needed. Models that already emit punctuation may not
+    need this postprocessor.
 
     Author: Speech Lab of DAMO Academy, Alibaba Group
     CT-Transformer: Controllable time-delay transformer for real-time punctuation prediction and disfluency detection

tests/test_ct_transformer_docs.py

@@ -0,0 +1,25 @@
+"""Check punctuation API guidance without importing the model or its dependencies."""
+
+import ast
+from pathlib import Path
+import unittest
+
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+class CTTransformerDocsContract(unittest.TestCase):
+    def test_unpunctuated_sensevoice_output_can_use_punctuation_model(self):
+        path = ROOT / "funasr/models/ct_transformer/model.py"
+        tree = ast.parse(path.read_text(encoding="utf-8"))
+        model = next(node for node in tree.body
+                     if isinstance(node, ast.ClassDef) and node.name == "CTTransformer")
+        doc = " ".join(ast.get_docstring(model).split())
+        self.assertIn("unpunctuated SenseVoiceSmall", doc)
+        self.assertIn("configure punc_model", doc)
+        self.assertIn("when punctuation is needed", doc)
+        self.assertNotIn("Only required for Paraformer", doc)
+
+
+if __name__ == "__main__":
+    unittest.main()