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
```
