fasr-service-fastapi 0.5.2__tar.gz

fasr_service_fastapi-0.5.2/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.3
+Name: fasr-service-fastapi
+Version: 0.5.2
+Summary: FastAPI service plugin for fasr
+Author: osc
+Author-email: osc <790990241@qq.com>
+Requires-Dist: fasr>=0.5.1
+Requires-Dist: fastapi>=0.115.4
+Requires-Dist: uvicorn>=0.32.0
+Requires-Python: >=3.10, <3.13
+Description-Content-Type: text/markdown
+
+# fasr-service-fastapi
+
+FastAPI service plugin for fasr. This package provides the concrete online
+service implementation while the core `fasr` package keeps only service base
+classes and registries.
+
+## Features
+
+- Demo web page:
+  - `GET /` (same as `GET /demo`)
+- Optional batch transcription HTTP endpoints:
+  - `POST /transcribe`
+  - `POST /inference`
+- Optional realtime websocket endpoints:
+  - `GET /v1/realtime`
+  - `GET /api-ws/v1/realtime`
+- Health endpoint:
+  - `GET /health`
+- Config-driven model and router initialization through fasr registries
+
+## Registered entry points
+
+| Group | Name | Entry point |
+|---|---|---|
+| `fasr_services` | `fastapi.v1` | `fasr_service_fastapi.service:FastAPIASRService` |
+| `fasr_service_routers` | `transcribe.v1` | `fasr_service_fastapi.routers.transcribe:transcribe_entrypoint` |
+| `fasr_service_routers` | `realtime.v1` | `fasr_service_fastapi.routers.realtime:realtime_entrypoint` |
+
+## Configuration
+
+The service owns model instances under `[service.models]`. Each router owns its
+own `model_map`, which maps router argument names to model names from
+`[service.models]`. Routers are enabled only when their config block exists, so
+omitting `[service.transcribe_router]` skips batch HTTP routes and omitting
+`[service.realtime_router]` skips realtime websocket routes.
+Configuring neither router is invalid and `fasr serve` will fail fast with a
+clear error.
+
+```toml
+[service]
+@services = "fastapi.v1"
+debug_logging = false
+
+[service.models.qwen3_asr]
+@asr_models = "qwen3asr"
+size = "small"
+
+[service.models.marblenet]
+@vad_models = "marblenet"
+
+[service.models.fsmn_online]
+@vad_models = "fsmn_online"
+
+[service.transcribe_router]
+@service_routers = "transcribe.v1"
+
+[service.transcribe_router.model_map]
+vad_model = "marblenet"
+asr_model = "qwen3_asr"
+
+[service.realtime_router]
+@service_routers = "realtime.v1"
+
+[service.realtime_router.model_map]
+vad_model = "fsmn_online"
+asr_model = "qwen3_asr"
+```
+
+Set `debug_logging = true` if you want to keep the service's `DEBUG` logs
+during development.
+
+For a transcribe-only service, remove the realtime router block:
+
+```toml
+[service]
+@services = "fastapi.v1"
+
+[service.models.paraformer]
+@asr_models = "paraformer"
+
+[service.models.marblenet]
+@vad_models = "marblenet"
+
+[service.models.ct_transformer]
+@punc_models = "ct_transformer"
+
+[service.transcribe_router]
+@service_routers = "transcribe.v1"
+
+[service.transcribe_router.model_map]
+vad_model = "marblenet"
+asr_model = "paraformer"
+punc_model = "ct_transformer"
+```
+
+Router entry points are factory functions. For example, `transcribe_entrypoint`
+creates default `AudioLoader`, `VoiceDetector`, and `SpeechRecognizer`
+instances when the config only provides `model_map`. This avoids requiring users
+to spell out internal router components in simple service configs. When
+`punc_model` is present in the transcribe router `model_map`, the router also
+creates a default `SpeechSentencizer` and adds it after the recognizer.
+
+## CLI
+
+Install the service plugin through the root project extra:
+
+```bash
+uv sync --extra service
+```
+
+Generate and run a default config:
+
+```bash
+fasr init --cfg run.cfg
+fasr serve --cfg run.cfg
+```
+
+Inspect or write the default config without starting the server:
+
+```bash
+fasr serve --print_default_config true
+fasr serve --write_default_config run.cfg
+```
+
+The same default config is available from:
+
+```python
+from fasr_service_fastapi import FastAPIASRService
+
+config = FastAPIASRService.model_construct().get_default_config()
+```
+
+## Development
+
+Install from the repository root:
+
+```bash
+uv sync
+```
+
+Run service tests:
+
+```bash
+uv run pytest tests/test_online_service.py -q
+```
+
+Build the plugin:
+
+```bash
+uv build --package fasr-service-fastapi
+```

fasr_service_fastapi-0.5.2/README.md

@@ -0,0 +1,151 @@
+# fasr-service-fastapi
+
+FastAPI service plugin for fasr. This package provides the concrete online
+service implementation while the core `fasr` package keeps only service base
+classes and registries.
+
+## Features
+
+- Demo web page:
+  - `GET /` (same as `GET /demo`)
+- Optional batch transcription HTTP endpoints:
+  - `POST /transcribe`
+  - `POST /inference`
+- Optional realtime websocket endpoints:
+  - `GET /v1/realtime`
+  - `GET /api-ws/v1/realtime`
+- Health endpoint:
+  - `GET /health`
+- Config-driven model and router initialization through fasr registries
+
+## Registered entry points
+
+| Group | Name | Entry point |
+|---|---|---|
+| `fasr_services` | `fastapi.v1` | `fasr_service_fastapi.service:FastAPIASRService` |
+| `fasr_service_routers` | `transcribe.v1` | `fasr_service_fastapi.routers.transcribe:transcribe_entrypoint` |
+| `fasr_service_routers` | `realtime.v1` | `fasr_service_fastapi.routers.realtime:realtime_entrypoint` |
+
+## Configuration
+
+The service owns model instances under `[service.models]`. Each router owns its
+own `model_map`, which maps router argument names to model names from
+`[service.models]`. Routers are enabled only when their config block exists, so
+omitting `[service.transcribe_router]` skips batch HTTP routes and omitting
+`[service.realtime_router]` skips realtime websocket routes.
+Configuring neither router is invalid and `fasr serve` will fail fast with a
+clear error.
+
+```toml
+[service]
+@services = "fastapi.v1"
+debug_logging = false
+
+[service.models.qwen3_asr]
+@asr_models = "qwen3asr"
+size = "small"
+
+[service.models.marblenet]
+@vad_models = "marblenet"
+
+[service.models.fsmn_online]
+@vad_models = "fsmn_online"
+
+[service.transcribe_router]
+@service_routers = "transcribe.v1"
+
+[service.transcribe_router.model_map]
+vad_model = "marblenet"
+asr_model = "qwen3_asr"
+
+[service.realtime_router]
+@service_routers = "realtime.v1"
+
+[service.realtime_router.model_map]
+vad_model = "fsmn_online"
+asr_model = "qwen3_asr"
+```
+
+Set `debug_logging = true` if you want to keep the service's `DEBUG` logs
+during development.
+
+For a transcribe-only service, remove the realtime router block:
+
+```toml
+[service]
+@services = "fastapi.v1"
+
+[service.models.paraformer]
+@asr_models = "paraformer"
+
+[service.models.marblenet]
+@vad_models = "marblenet"
+
+[service.models.ct_transformer]
+@punc_models = "ct_transformer"
+
+[service.transcribe_router]
+@service_routers = "transcribe.v1"
+
+[service.transcribe_router.model_map]
+vad_model = "marblenet"
+asr_model = "paraformer"
+punc_model = "ct_transformer"
+```
+
+Router entry points are factory functions. For example, `transcribe_entrypoint`
+creates default `AudioLoader`, `VoiceDetector`, and `SpeechRecognizer`
+instances when the config only provides `model_map`. This avoids requiring users
+to spell out internal router components in simple service configs. When
+`punc_model` is present in the transcribe router `model_map`, the router also
+creates a default `SpeechSentencizer` and adds it after the recognizer.
+
+## CLI
+
+Install the service plugin through the root project extra:
+
+```bash
+uv sync --extra service
+```
+
+Generate and run a default config:
+
+```bash
+fasr init --cfg run.cfg
+fasr serve --cfg run.cfg
+```
+
+Inspect or write the default config without starting the server:
+
+```bash
+fasr serve --print_default_config true
+fasr serve --write_default_config run.cfg
+```
+
+The same default config is available from:
+
+```python
+from fasr_service_fastapi import FastAPIASRService
+
+config = FastAPIASRService.model_construct().get_default_config()
+```
+
+## Development
+
+Install from the repository root:
+
+```bash
+uv sync
+```
+
+Run service tests:
+
+```bash
+uv run pytest tests/test_online_service.py -q
+```
+
+Build the plugin:
+
+```bash
+uv build --package fasr-service-fastapi
+```

fasr_service_fastapi-0.5.2/pyproject.toml

@@ -0,0 +1,28 @@
+[project]
+name = "fasr-service-fastapi"
+version = "0.5.2"
+description = "FastAPI service plugin for fasr"
+readme = "README.md"
+authors = [
+    { name = "osc", email = "790990241@qq.com" }
+]
+requires-python = ">=3.10, <3.13"
+dependencies = [
+    "fasr>=0.5.1",
+    "fastapi>=0.115.4",
+    "uvicorn>=0.32.0",
+]
+
+[tool.uv.sources]
+fasr = { workspace = true }
+
+[project.entry-points."fasr_services"]
+"fastapi.v1" = "fasr_service_fastapi.service:FastAPIASRService"
+
+[project.entry-points."fasr_service_routers"]
+"transcribe.v1" = "fasr_service_fastapi.routers.transcribe:transcribe_entrypoint"
+"realtime.v1" = "fasr_service_fastapi.routers.realtime:realtime_entrypoint"
+
+[build-system]
+requires = ["uv_build>=0.10.11,<0.11.0"]
+build-backend = "uv_build"

fasr_service_fastapi-0.5.2/src/fasr_service_fastapi/__init__.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from fastapi import FastAPI
+
+from fasr.model import ASRModel, VADModel
+from fasr_service_fastapi.routers.realtime import (
+    RealtimeRouter,
+    RealtimeWebSocketHandler,
+)
+
+from .service import FastAPIASRService, configure_service_logging
+
+
+def create_realtime_app(
+    *,
+    vad_model: VADModel,
+    asr_model: ASRModel,
+    sample_rate: int = 16000,
+    vad_chunk_size_ms: int = 100,
+    vad_model_name: str = "fsmn_online",
+    asr_model_name: str = "stream_qwen3_0_6b",
+    debug_logging: bool = False,
+) -> FastAPI:
+    configure_service_logging(debug_logging)
+    handler = RealtimeWebSocketHandler(
+        sample_rate=sample_rate,
+        chunk_size_ms=vad_chunk_size_ms,
+        model_name=asr_model_name,
+    )
+    router = RealtimeRouter(
+        handler=handler,
+        model_map={
+            "vad_model": "vad_model",
+            "asr_model": "asr_model",
+        },
+    )
+    router.setup(
+        service_id="realtime_test",
+        models={
+            "vad_model": vad_model,
+            "asr_model": asr_model,
+        },
+    )
+
+    app = FastAPI(title="fasr realtime asr service")
+    app.include_router(router.create_router())
+
+    @app.get("/health")
+    async def health() -> dict[str, object]:
+        return {
+            "status": "ok",
+            "vad_model": vad_model_name,
+            "asr_model": asr_model_name,
+            "models_loaded": handler.vad_model is not None
+            and handler.asr_model is not None,
+        }
+
+    return app
+
+
+__all__ = ["FastAPIASRService", "create_realtime_app"]

fasr_service_fastapi-0.5.2/src/fasr_service_fastapi/asr_scheduler.py

@@ -0,0 +1,147 @@
+from __future__ import annotations
+
+from concurrent.futures import Future
+from dataclasses import dataclass
+from itertools import count
+import os
+from queue import PriorityQueue
+import threading
+from typing import Callable, List, TypeVar
+
+from loguru import logger
+from pydantic import Field
+
+from fasr.config import Config
+from fasr.data.audio import AudioChunk, AudioSpan
+from fasr.model import ASRModel
+
+T = TypeVar("T")
+
+ASR_PRIORITY_REALTIME = 0
+ASR_PRIORITY_TRANSCRIBE = 10
+
+
+@dataclass
+class ASRInferenceTask:
+    fn: Callable[[], object]
+    future: Future[object]
+    label: str
+
+
+class ASRInferenceScheduler:
+    """Single-worker scheduler for shared ASR model inference calls."""
+
+    def __init__(self, service_id: str = "") -> None:
+        self.service_id = service_id
+        self._tasks: PriorityQueue[tuple[int, int, ASRInferenceTask]] = PriorityQueue()
+        self._task_sequence = count()
+        self._worker: threading.Thread | None = None
+
+    def start(self) -> None:
+        if self._worker is not None and self._worker.is_alive():
+            return
+        self._worker = threading.Thread(
+            target=self._worker_loop,
+            name="asr-inference-worker",
+            daemon=True,
+        )
+        self._worker.start()
+        logger.info(
+            "ASR inference scheduler started: service_id={}, pid={}, thread={}",
+            self.service_id,
+            os.getpid(),
+            self._worker.name,
+        )
+
+    def submit_sync(
+        self,
+        label: str,
+        fn: Callable[[], T],
+        priority: int = ASR_PRIORITY_TRANSCRIBE,
+    ) -> T:
+        self.start()
+        future: Future[object] = Future()
+        self._tasks.put(
+            (
+                priority,
+                next(self._task_sequence),
+                ASRInferenceTask(fn=fn, future=future, label=label),
+            )
+        )
+        logger.debug(
+            "ASR inference task queued: service_id={}, pid={}, label={}, priority={}, queue_size={}",
+            self.service_id,
+            os.getpid(),
+            label,
+            priority,
+            self._tasks.qsize(),
+        )
+        return future.result()  # type: ignore[return-value]
+
+    def _worker_loop(self) -> None:
+        while True:
+            priority, _, task = self._tasks.get()
+            logger.debug(
+                "ASR inference task started: service_id={}, pid={}, thread={}, label={}, priority={}, queue_size={}",
+                self.service_id,
+                os.getpid(),
+                threading.current_thread().name,
+                task.label,
+                priority,
+                self._tasks.qsize(),
+            )
+            try:
+                result = task.fn()
+            except Exception as exc:
+                task.future.set_exception(exc)
+            else:
+                task.future.set_result(result)
+            finally:
+                logger.debug(
+                    "ASR inference task finished: service_id={}, pid={}, thread={}, label={}",
+                    self.service_id,
+                    os.getpid(),
+                    threading.current_thread().name,
+                    task.label,
+                )
+                self._tasks.task_done()
+
+
+class ScheduledASRModel(ASRModel):
+    """ASR model wrapper that serializes calls to a shared model instance."""
+
+    model: ASRModel = Field(..., exclude=True)
+    scheduler: ASRInferenceScheduler = Field(..., exclude=True)
+
+    def load_checkpoint(self, checkpoint_dir: str | None):
+        return None
+
+    def get_config(self) -> Config:
+        return self.model.get_config()
+
+    def transcribe(
+        self,
+        batch: List[AudioSpan],
+        **kwargs,
+    ) -> List[AudioSpan]:
+        return self.scheduler.submit_sync(
+            f"{type(self.model).__name__}.transcribe",
+            lambda: self.model.transcribe(batch, **kwargs),
+            priority=ASR_PRIORITY_TRANSCRIBE,
+        )
+
+    def push_chunk(self, chunk: AudioChunk) -> AudioSpan | None:
+        return self.scheduler.submit_sync(
+            f"{type(self.model).__name__}.push_chunk",
+            lambda: self.model.push_chunk(chunk),
+            priority=ASR_PRIORITY_REALTIME,
+        )
+
+    def reset(self):
+        return self.model.reset()
+
+    def remove_state(self, key: str):
+        return self.model.remove_state(key)
+
+    def get_state(self, key: str):
+        return self.model.get_state(key)

fasr_service_fastapi-0.5.2/src/fasr_service_fastapi/routers/__init__.py

@@ -0,0 +1,10 @@
+from .realtime import RealtimeRouter, RealtimeWebSocketHandler, realtime_entrypoint
+from .transcribe import TranscribeRouter, transcribe_entrypoint
+
+__all__ = [
+    "RealtimeRouter",
+    "RealtimeWebSocketHandler",
+    "TranscribeRouter",
+    "realtime_entrypoint",
+    "transcribe_entrypoint",
+]

fasr_service_fastapi-0.5.2/src/fasr_service_fastapi/routers/realtime/__init__.py

@@ -0,0 +1,28 @@
+from .handler import RealtimeWebSocketHandler
+from .protocol import (
+    create_error_event,
+    create_session_created_event,
+    create_session_finished_event,
+    create_session_updated_event,
+    create_speech_started_event,
+    create_speech_stopped_event,
+    create_transcription_completed_event,
+    create_transcription_text_event,
+)
+from .router import RealtimeRouter, realtime_entrypoint
+from .session import ASRSession
+
+__all__ = [
+    "RealtimeRouter",
+    "realtime_entrypoint",
+    "RealtimeWebSocketHandler",
+    "ASRSession",
+    "create_error_event",
+    "create_session_created_event",
+    "create_session_finished_event",
+    "create_session_updated_event",
+    "create_speech_started_event",
+    "create_speech_stopped_event",
+    "create_transcription_completed_event",
+    "create_transcription_text_event",
+]