From 364781d5a5c94f632d4d948748c0103111a03868 Mon Sep 17 00:00:00 2001
From: Eike Haller <58111764+eksrha@users.noreply.github.com>
Date: Tue, 3 Nov 2026 09:08:53 +0000
Subject: [PATCH] docs: rewrite README, add logo and banner, move tuning and
configuration into docs
---
AGENTS.md | 11 +-
README.md | 501 +++++++++++-----------------------------
assets/banner.png | Bin 0 -> 80595 bytes
assets/icon-tile.svg | 2 +
assets/icon.svg | 2 +
assets/lockup-dark.svg | 2 +
assets/lockup-light.svg | 2 +
assets/logo.svg | 2 +
docs/configuration.md | 60 +++++
docs/tuning.md | 220 ++++++++++++++++++
10 files changed, 432 insertions(+), 370 deletions(-)
create mode 100644 assets/banner.png
create mode 100644 assets/icon-tile.svg
create mode 100644 assets/icon.svg
create mode 100644 assets/lockup-dark.svg
create mode 100644 assets/lockup-light.svg
create mode 100644 assets/logo.svg
create mode 100644 docs/configuration.md
create mode 100644 docs/tuning.md
diff --git a/AGENTS.md b/AGENTS.md
index b521405..14a4165 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -101,7 +101,7 @@ Key details:
### Whisper (Standalone)
-Model is baked directly into the image at build time. No init container, no PVC needed. The image runs `deploy/whisper/server.py`, which speaks the OpenAI audio API itself (the router forwards paths unchanged). `/health` does not queue behind inference. Pin `av` (see Containerfile) — newer PyAV majors break faster-whisper. Each request logs one JSON line (`whisper_request`, timings, RTF; never prompt/transcript text). `WHISPER_INITIAL_PROMPT` / `WHISPER_HOTWORDS` are server-side defaults (see README). Tests: `pytest deploy/whisper` (stubbed model).
+Model is baked directly into the image at build time. No init container, no PVC needed. The image runs `deploy/whisper/server.py`, which speaks the OpenAI audio API itself (the router forwards paths unchanged). `/health` does not queue behind inference. Pin `av` (see Containerfile) — newer PyAV majors break faster-whisper. Each request logs one JSON line (`whisper_request`, timings, RTF; never prompt/transcript text). `WHISPER_INITIAL_PROMPT` / `WHISPER_HOTWORDS` are server-side defaults (see docs/tuning.md). Tests: `pytest deploy/whisper` (stubbed model).
### Router (Go Proxy)
@@ -137,7 +137,7 @@ make docker/whisper # whisper
## Tech Stack & Constraints
-- **Go 1.24+** — no generics workarounds needed
+- **Go 1.26** (see `go.mod`)
- **`net/http/httptest`** for all tests — no external test frameworks (no testify, no gomock)
- **`go.uber.org/zap`** for structured logging
- **`github.com/prometheus/client_golang`** for metrics
@@ -228,7 +228,7 @@ It exposes `/health`, `/v1/models`, and the backend-specific inference endpoints
- `promauto` metrics panic on double-registration. If you add a new metric, add it to `internal/metrics/metrics.go` as a package-level var, not inside a function.
- `health.Checker` must be initialised with `health.New(cfg.EnabledBackends(), log)` — passing `cfg.ActiveBackends()` will include disabled backends and skew the health response.
- The `statusWriter` wrapper in `proxy.go` must set `status = 200` lazily (in `Write`) to handle the case where `WriteHeader` is never called explicitly.
-- TEI does **not** support reranking — the reranker uses FlagEmbedding, not TEI.
+- Reranking runs on TEI (ONNX, see `docs/ADR-001-tei-for-reranking.md`). `deploy/Containerfile.reranker-server` and `deploy/reranker/` are the legacy FlagEmbedding server and are not released any more.
- Some CSI volumes don't support timestamp preservation — always use `rsync -rlgoDv`, never `rsync -a`.
- Pod `fsGroup: 1000` is required for init containers to write to PVCs (CSI provisions volumes as root).
@@ -250,8 +250,11 @@ It exposes `/health`, `/v1/models`, and the backend-specific inference endpoints
| `EMBEDDING_URL` | — | Base URL for TEI embedding |
| `EMBEDDING_TIMEOUT` | `60s` | Per-request timeout |
| `RERANKER_ENABLED` | `false` | Enable reranker backend |
-| `RERANKER_URL` | — | Base URL for FlagEmbedding reranker |
+| `RERANKER_URL` | — | Base URL for the TEI reranker |
| `RERANKER_TIMEOUT` | `30s` | Per-request timeout |
| `WHISPER_ENABLED` | `false` | Enable Whisper backend |
| `WHISPER_URL` | — | Base URL for Whisper |
| `WHISPER_TIMEOUT` | `300s` | Per-request timeout |
+| `EMBEDDING_MAX_CONCURRENT` / `RERANKER_MAX_CONCURRENT` / `WHISPER_MAX_CONCURRENT` | `20` / `20` / `8` | Concurrency bound per backend; above it the router answers `503` + `Retry-After` |
+
+User-facing documentation: `README.md`, `docs/configuration.md`, `docs/tuning.md`.
diff --git a/README.md b/README.md
index bf115c8..d508a68 100644
--- a/README.md
+++ b/README.md
@@ -1,124 +1,150 @@
-# inference-stack
-
-[](https://github.com/layer87-labs/inference-stack/actions/workflows/ci.yml)
-[](LICENSE)
-
-Unified CPU-based inference stack — serving embeddings, reranking and transcription behind a single OpenAI-compatible API.
+
+
+
-## Components
+
+
+
+
+
+
-| Component | Runtime | Model | Purpose |
-| -------------------- | ---------------------------------------------------------------------- | ----------------------- | --------------------------------------- |
-| **inference-router** | Go | — | Unified OpenAI-compatible reverse proxy |
-| **embedding** | [TEI](https://github.com/huggingface/text-embeddings-inference) (Rust) | BAAI/bge-m3 | Dense + sparse embeddings |
-| **reranker** | [TEI](https://github.com/huggingface/text-embeddings-inference) (Rust, ONNX) | mmarco-mMiniLMv2-L12-H384-v1 (default), bge-reranker-v2-m3 (option) | Cross-encoder reranking |
-| **whisper** | [faster-whisper](https://github.com/SYSTRAN/faster-whisper) (Python) | large-v3-turbo | Audio transcription (ASR) |
+# inference-stack
-All backends are disabled by default and enabled selectively via Helm values or env vars.
+**inference-stack** is a small OpenAI-compatible router in front of CPU-only inference backends. One endpoint
+gives you **embeddings** (`BAAI/bge-m3` via [TEI](https://github.com/huggingface/text-embeddings-inference)),
+**reranking** (a cross-encoder via TEI/ONNX) and **speech-to-text** (Whisper `large-v3-turbo` via
+[faster-whisper](https://github.com/SYSTRAN/faster-whisper)). It runs on plain CPU and RAM. No GPU needed.
+
+**Why it exists.** Search, RAG and transcription should not need a GPU budget or a pile of glue code. We
+([Layer87](https://github.com/layer87-labs)) needed exactly this in our own applications, built it, run it ourselves
+and open-sourced it. It ships with hardened container images, a Helm chart and signed releases.
+
+## Highlights
+
+- **One API, three capabilities.** `/v1/embeddings`, `/v1/rerank`, `/v1/audio/transcriptions`, plus a merged `/v1/models`
+ that also reports the backends' request limits.
+- **CPU only.** Sized and measured on CPU; the numbers (latency per rerank request, memory, real-time factor) are in
+ [docs/tuning.md](docs/tuning.md).
+- **Backends are optional.** All are off by default; enable only what you need.
+- **Backpressure instead of pile-ups.** Per-backend concurrency bound; above it the router answers `503` with
+ `Retry-After` right away ([details](docs/configuration.md#backpressure)).
+- **Observable.** Prometheus metrics on a separate port, JSON logs, optional `ServiceMonitor` and `NetworkPolicy`.
+- **Signed images.** Released images are signed keyless with [cosign](https://github.com/sigstore/cosign) via GitHub
+ OIDC ([verify](#security)).
+- **Hardened by default.** Non-root containers, no privilege escalation, all capabilities dropped, `RuntimeDefault`
+ seccomp, executable-stack flag cleared on the ONNX Runtime libraries of the TEI base image.
+- **Offline at runtime.** Models are baked into images (`HF_HUB_OFFLINE=1`); model volumes are mounted read-only.
+- **Pinned build inputs.** The Whisper image pins its base image by digest, all Python dependencies, the model
+ revision and the model file's SHA-256; the build fails if any of them changes.
+- **Per-component CalVer releases.** Router, TEI images, models, Whisper and the Helm chart are released
+ independently with [relctl](https://github.com/layer87-labs/relctl).
-## Quick Start
+## Architecture
-### Local Development
+```
+ ┌──────────────────────────────────────┐
+ your app ──HTTP──▶ │ inference-router (Go, :8080) │ ─▶ :9090/metrics
+ OpenAI-style API └───────┬───────────────┬──────────────┘
+ │ │ │
+ /v1/embeddings /v1/rerank /v1/audio/transcriptions
+ ▼ ▼ ▼
+ ┌────────────┐ ┌────────────┐ ┌──────────────────┐
+ │ TEI │ │ TEI (ONNX) │ │ faster-whisper │
+ │ bge-m3 │ │ cross-enc. │ │ large-v3-turbo │
+ └─────▲──────┘ └─────▲──────┘ └──────────────────┘
+ │ /model (ro) │ /model (ro) model baked into image
+ model-init (rsync) model-init (rsync)
+```
-```bash
-# Run unit tests
-make test
+The router is a pure reverse proxy: it routes by path, bounds concurrency, probes backend health and exports
+metrics. It contains no model logic. The TEI backends read their model from a volume that an init container
+fills from a model baked into its image (idempotent, `rsync --ignore-existing`); Whisper has the model in the
+image itself.
-# Full end-to-end test (starts mock backends + router)
-make test-local
-```
+## Quick start
-### Kubernetes (Helm)
+**Try it locally in a minute** (mock backends, no models, needs Go):
```bash
-helm install inference-stack ./deploy/helm \
- --namespace ai \
- --set embedding.enabled=true \
- --set reranker.enabled=true \
- --set router.enabled=true
+make test-local # builds, starts mock backends + router, runs the end-to-end checks
```
-## API
-
-All endpoints are OpenAI-compatible:
+Or start the pieces by hand and call the API yourself:
```bash
-# Embeddings
-curl http://localhost:8080/v1/embeddings \
- -H "Content-Type: application/json" \
- -d '{"model":"BAAI/bge-m3","input":"Hello world"}'
-
-# Reranking
-curl http://localhost:8080/v1/rerank \
- -H "Content-Type: application/json" \
- -d '{"query":"What is Go?","documents":["Go is a language","Python is a language"]}'
-
-# Transcription
-curl http://localhost:8080/v1/audio/transcriptions \
- -F model=whisper-large-v3-turbo \
- -F file=@audio.mp3
+make build
+MOCK_TYPE=embedding MOCK_PORT=9101 build/bin/mock-backend &
+EMBEDDING_ENABLED=true EMBEDDING_URL=http://localhost:9101 build/bin/inference-router &
-# Model list (merged from all enabled backends)
-curl http://localhost:8080/v1/models
+curl http://localhost:8080/v1/embeddings -H 'Content-Type: application/json' \
+ -d '{"model":"BAAI/bge-m3","input":"Hello world"}'
```
-`/v1/models` also reports the request limits of the embedding and reranker
-backends (`limits.max_batch_tokens`, `limits.max_client_batch_size`,
-`limits.max_input_length`), read from the running backend, so clients can size
-batches without trial and error. The model id it advertises
-(`BAAI/bge-m3`) can be sent back as `model` on `/v1/embeddings`; the router
-strips it before forwarding, because TEI only accepts its internal model path
-or no model at all.
+**Run it for real on Kubernetes** with the Helm chart from the OCI registry. Pick a chart version from the
+[releases](https://github.com/layer87-labs/inference-stack/releases) (tags look like `chart/`):
-## Architecture
+```yaml
+# values.yaml: everything is off by default, enable what you need
+router: { enabled: true }
+embedding: { enabled: true }
+reranker: { enabled: true }
+whisper: { enabled: true }
+```
-### Init Container Pattern (Embedding + Reranker)
+```bash
+helm install stack oci://ghcr.io/layer87-labs/charts/inference-stack \
+ --version --namespace ai --create-namespace -f values.yaml
-```
-┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
-│ model-init │────▶│ /model (PVC) │────▶│ main container │
-│ (bakes model) │ │ shared volume │ │ (reads model) │
-└─────────────────┘ └──────────────────┘ └─────────────────┘
+kubectl -n ai port-forward svc/stack-inference-stack-router 8080:8080
```
-1. **Init container** copies baked model to PVC via `rsync --ignore-existing`
-2. **Main container** reads model from PVC (mounted read-only)
-3. PVC persists model across restarts (idempotent — no re-copy on restart)
+The first start takes a while: the init containers copy the models to the volume. Sizing per backend (CPU, memory,
+batch tokens) is in [docs/tuning.md](docs/tuning.md); all chart options are commented in
+[`deploy/helm/values.yaml`](deploy/helm/values.yaml).
-### Whisper (Standalone)
+## API
-Model baked into image at build time. No init container or PVC needed. The
-image runs `deploy/whisper/server.py` (faster-whisper behind a small FastAPI
-app) which implements `POST /v1/audio/transcriptions` and
-`/v1/audio/translations` natively, so the router forwards requests unchanged.
-`/health` is answered independently of inference and stays responsive while a
-transcription is running.
+| Method and path | Backend | Notes |
+| --- | --- | --- |
+| `POST /v1/embeddings` | embedding | OpenAI-style. The advertised model id `BAAI/bge-m3` may be sent as `model`. |
+| `POST /embed`, `POST /embed_sparse` | embedding | TEI native (dense and sparse) |
+| `POST /v1/rerank`, `POST /rerank` | reranker | `/v1/rerank` is rewritten to TEI's `/rerank` |
+| `POST /v1/audio/transcriptions` | whisper | multipart; `json`, `text`, `verbose_json`, `srt`, `vtt` |
+| `POST /v1/audio/translations` | whisper | exposed, but `large-v3-turbo` is not trained for translation |
+| `GET /v1/models` | all enabled | merged list incl. `limits` of embedding and reranker |
+| `GET /healthz`, `GET /readyz` | router | per-backend status, always HTTP 200 (`ok` or `degraded`) |
+| `GET :9090/metrics` | router | Prometheus |
-### Router (Go Proxy)
+```bash
+curl http://localhost:8080/v1/rerank -H 'Content-Type: application/json' \
+ -d '{"query":"What is Go?","texts":["Go is a language","Python is a language"]}'
-Pure reverse proxy — routes requests to backends based on path prefix. Zero model logic.
+curl http://localhost:8080/v1/audio/transcriptions -F model=whisper-large-v3-turbo -F file=@audio.mp3
+```
-## Container Images
+A disabled backend answers `503 backend_disabled`; an unreachable one `502 upstream_error`; one at its
+concurrency bound `503 backend_overloaded` with `Retry-After`.
-All images are published to `ghcr.io/layer87-labs/`:
+## Components and images
-| Image | Description |
-| --------------------- | -------------------------------------- |
-| `inference-router` | Go reverse proxy |
-| `tei-base` | Hardened TEI base (patchelf, non-root) |
-| `tei-runtime` | TEI runtime (model via volume) |
-| `tei-model-init` | BGE-M3 model baked, copies to volume |
-| `tei-reranker-model-init` | Reranker model as ONNX (default: mmarco-mMiniLMv2-L12-H384-v1; option: BGE-reranker-v2-m3) |
-| `reranker-server` | FlagEmbedding HTTP server |
-| `whisper` | Whisper ASR server, model baked in |
+| Component | Image(s) in `ghcr.io/layer87-labs/` | Purpose |
+| --- | --- | --- |
+| router | `inference-router` | Go reverse proxy on a minimal static base image (no shell) |
+| tei | `tei-base`, `tei-runtime` | Hardened TEI CPU base and runtime (model via volume) |
+| embedding-model | `tei-model-init` | `BAAI/bge-m3` baked in, copies to the volume |
+| reranker-model | `tei-reranker-model-init` | Reranker as ONNX: `cross-encoder/mmarco-mMiniLMv2-L12-H384-v1` (default) or `BAAI/bge-reranker-v2-m3` |
+| whisper | `whisper` | faster-whisper server, `large-v3-turbo` baked in |
+| chart | `charts/inference-stack` (OCI) | Helm chart |
-All images run as non-root with no privilege escalation.
+Why the default reranker is the small model: on 4 CPUs it needs 0.76 to 0.85 s for 20 documents of 800
+characters, against 8.3 to 11.9 s for `bge-reranker-v2-m3`. Method and quality numbers are in
+[docs/tuning.md](docs/tuning.md#reranker-model-choice).
-### Verify image signatures
+## Security
-Images built by the release workflows are signed with
-[cosign](https://github.com/sigstore/cosign) keyless via GitHub OIDC. Verify by
-digest against the exact workflow identity:
+Container images from the release pipeline are signed keyless with cosign. Verify by digest against the exact
+workflow identity:
```bash
IMAGE=ghcr.io/layer87-labs/inference-router
@@ -130,290 +156,33 @@ cosign verify \
"$IMAGE@$DIGEST"
```
-`release.yml` signs `inference-router`, `tei-base` and `tei-runtime`.
-`release-models.yml` signs `tei-model-init`, `tei-reranker-model-init` and
-`whisper`; for those, use the identity
-`https://github.com/layer87-labs/inference-stack/.github/workflows/release-models.yml@refs/heads/main`
-(for manual runs, the ref is the branch the workflow was started from).
-Images published before signing was added are unsigned.
+Model and Whisper images published earlier were signed by the separate `release-models.yml` workflow (same
+command, that workflow file as identity). Images published before signing was added are
+unsigned. The Helm chart is not signed.
-## Build
+Runtime posture of the chart defaults: non-root users (uid 65532 for the router, 1000 for the rest),
+`allowPrivilegeEscalation: false`, `capabilities.drop: [ALL]`, `seccompProfile: RuntimeDefault`, a read-only root
+filesystem for the router, read-only model mounts, and no outbound network calls needed at runtime. An optional
+`NetworkPolicy` restricts the router.
-```bash
-# Go binary
-make build
+## Documentation
-# All container images
-make docker
-
-# Push to registry
-make push REGISTRY=ghcr.io/layer87-labs VERSION=202611.3.1
-```
+- [docs/configuration.md](docs/configuration.md): environment variables, backpressure, health endpoints, metrics
+- [docs/tuning.md](docs/tuning.md): CPU sizing, reranker model choice and measurements, Whisper options, scheduling
+- [docs/ADR-001-tei-for-reranking.md](docs/ADR-001-tei-for-reranking.md): why reranking runs on TEI
+- [AGENTS.md](AGENTS.md): repository layout, build and test commands, release components
-## Releases
-
-The router, TEI images, embedding model, reranker models, Whisper and the Helm chart are released
-independently as [relctl](https://github.com/layer87-labs/relctl) components with CalVer versions
-(`YYYYMM.D.N`, tag `/`). Only the parts whose files changed are built on a merge to
-`main`. See `AGENTS.md` for the component table and image tag formats.
-
-## Metrics
-
-Prometheus metrics on `:9090/metrics`:
-
-- `inference_router_requests_total` — total requests by backend/path/status
-- `inference_router_request_duration_seconds` — latency histogram
-- `inference_router_active_requests` — in-flight requests
-- `inference_router_backend_up` — backend health (0/1)
-- `inference_router_upstream_errors_total` — upstream error counts
-
-## CPU Tuning
-
-### Embedding (TEI + BGE-M3)
-
-| `--max-batch-tokens` | RSS (fp32) | Recommendation |
-| -------------------- | ---------- | -------------------- |
-| 4096 | 3-6Gi | **CPU default** |
-| 8192 | 6-10Gi | May OOM on 8Gi limit |
-| 16384 | 10-16Gi | GPU-only |
-
-### Reranker model choice
-
-The reranker model is baked into the `tei-reranker-model-init` image and
-selected by its tag (`reranker.modelInit.image.tag`). Both models run on the
-same TEI runtime with the ONNX Runtime backend.
-
-Measured with TEI `cpu-1.9.4`, limited to 4 CPUs, `--max-batch-tokens 2048`,
-one `/rerank` request with one query and 20 documents of 800 characters each
-(German/English mix), 4 runs per model. The CPU was an older AVX2 machine, so
-only the ratios carry over.
-
-| Model | Format | Parameters | Latency (20 docs) |
-| ------------------------------------------------------ | ------------------------- | ---------- | ----------------- |
-| `cross-encoder/mmarco-mMiniLMv2-L12-H384-v1` (default) | fp32 ONNX | 118M | 0.76 to 0.85 s |
-| `BAAI/bge-reranker-v2-m3` | fp32 ONNX | 568M | 8.3 to 11.9 s |
-| `BAAI/bge-reranker-v2-m3` | int8 ONNX | 568M | 7.9 to 8.2 s |
-| `Alibaba-NLP/gte-multilingual-reranker-base` | safetensors (candle path) | n/a | 11.1 to 12.1 s |
-
-That is about 0.04 s per document pair for the default against roughly 0.4 to
-0.5 s for `bge-reranker-v2-m3`, so reranking 40 candidates with the larger
-model does not fit an interactive latency budget on 4 CPUs.
-
-Quality, on a downstream 75-question German/English relevance set (hybrid
-retrieval, rerank the top 20 candidates, 800 characters per document):
-
-| Setup | hit@1 | hit@5 | hit@10 |
-| ------------------------------------------ | ----- | ----- | ------ |
-| No rerank | 77% | 95% | 96% |
-| `BAAI/bge-reranker-v2-m3` | 92% | 96% | 96% |
-| `cross-encoder/mmarco-mMiniLMv2-L12-H384-v1` | 92% | 96% | 96% |
-
-This set is small and saturated (one question is 1.3 points), its documents
-were short, and the embeddings used for candidate retrieval were a simple
-stand-in, so it cannot separate the two models. Real-world German technical
-text may favour the larger model; measure on your own data if quality matters
-more than latency.
-
-#### Sizing the request for the default model
-
-Latency is dominated by the number of passages and their length, and one
-request already uses all CPUs, so concurrent requests queue. Measured with the
-default model on a 4-vCPU pod (TEI `cpu-1.9.4`, `--max-batch-tokens 2048`),
-75 queries, passages of title plus text cut to the given length (800
-characters are about 190 tokens, 500 about 120), p95 latency of one `/rerank`
-call:
-
-| Passages | 800 chars | 600 chars | 500 chars | 400 chars |
-| -------- | --------- | --------- | --------- | --------- |
-| 40 | 3.2 s | 2.5 s | 2.1 s | 1.8 s |
-| 30 | 2.4 s | 1.9 s | 1.7 s | 1.4 s |
-| 20 | 1.7 s | 1.3 s | 1.1 s | 1.0 s |
-| 15 | 1.3 s | 1.0 s | 0.9 s | 0.7 s |
-
-With four such requests in flight at once, p95 is about 3 to 4 times higher
-(for example 3.0 s for 15 passages of 500 characters, 6.4 s for 40 of 400).
-If the budget is about 1.5 s per request, send at most 15 to 20 passages of
-about 500 characters, and scale out (`reranker.replicaCount`) or add CPU for
-concurrent callers. Reranking a short list also bounds what it can gain: it can
-only reorder the passages it receives.
-
-Memory: the working set stayed at about 1.4 GiB, including four concurrent
-requests of 40 passages, so the chart defaults to a 1.5 GiB request and a 2 GiB
-limit. Inputs longer than the model's 512-token limit are truncated by default
-(`truncate: true`, or the TEI default when the field is omitted); with
-`truncate: false` the request fails with HTTP 422.
-
-The model repository also ships quantised ONNX variants (for example
-`onnx/model_qint8_avx512_vnni.onnx`, `onnx/model_quint8_avx2.onnx`). They are
-not used by this chart and were not measured; they are CPU-specific and
-would need to be baked as `onnx/model.onnx` for TEI.
-
-Licence: `cross-encoder/mmarco-mMiniLMv2-L12-H384-v1` is Apache-2.0,
-`BAAI/bge-reranker-v2-m3` is Apache-2.0 as well (as tagged on the Hugging Face hub); check the model card of
-anything else you select.
-
-To use the higher-quality model (more CPU or a GPU), build or pull the matching
-init image and set:
+## Contributing
-```yaml
-reranker:
- modelName: "BAAI/bge-reranker-v2-m3"
- modelInit:
- image:
- tag: "bge-reranker-v2-m3-" # e.g. bge-reranker-v2-m3-202611.3.1, see the published tags
-```
-
-The init step copies with `--ignore-existing`, so when you change the model on
-an existing release, delete the reranker model PVC (or install with
-`reranker.persistence.enabled=false`) so the old model files are not reused.
-`BAAI/bge-reranker-v2-m3` needs `requests: 4Gi` / `limits: 8Gi` memory with
-`--max-batch-tokens 2048`; the default model needs far less.
-
-To build an init image yourself: `make docker/tei-reranker-model-init
-RERANKER_MODEL_ID=`. If the model repository ships
-`onnx/model.onnx` it is used as-is; otherwise the model is exported with
-Optimum. Only XLM-RoBERTa-style sequence-classification models that TEI
-supports will work.
-
-### Whisper (faster-whisper + large-v3-turbo, int8)
-
-Measured on CPU: ~2.0 GiB RSS peak; roughly real-time speed on 2 threads (a
-3.7 min recording took 3.3 min), faster with more threads.
-
-- `whisper.cpuThreads` must match the CPU limit (CTranslate2 sizes itself by
- the node's cores, not by the cgroup limit).
-- Transcriptions run one at a time; further requests queue in the server. Keep
- the router's `WHISPER_TIMEOUT` (default `300s`) above queue time + runtime,
- e.g. via `router.extraEnv`.
-- Upload limit: `whisper.maxUploadMB` (default 100). Formats: anything FFmpeg
- decodes (wav, mp3, m4a, ogg, flac, webm, mp4, ...).
-- `response_format`: `json` (default), `text`, `verbose_json`, `srt`, `vtt`.
-- Set `whisper.language` (e.g. `de`) to skip language auto-detection; a
- request's own `language` field wins.
-- Vocabulary hints, two mechanisms (both optional, both off by default):
- - `prompt` (form field, OpenAI-compatible) becomes faster-whisper's
- `initial_prompt`. Set a server-side default with `whisper.initialPrompt`
- (`WHISPER_INITIAL_PROMPT`) for clients that send no prompt (e.g. an STT
- integration that only sends `model` and `language`). A request prompt is
- **appended** to the default (` `): Whisper weighs the end
- of the prompt most, and an over-long prompt is cut from the front, so the
- request-specific text survives. Whisper reads at most 223 tokens
- (`max_length // 2 - 1`); faster-whisper keeps the last 223 and drops the
- rest. The server additionally caps the combined text at 2000 characters
- (tail kept).
- - `hotwords` (form field, extension; free text such as
- `Kubernetes Grafana Postgres`) is passed to faster-whisper's `hotwords`.
- Server default: `whisper.hotwords` (`WHISPER_HOTWORDS`). A request's
- `hotwords` **replaces** the default (no merging). faster-whisper puts the
- hotwords in front of the previous-text prompt; it ignores them only when
- `prefix` is set, which this server never sets, so `prompt` and `hotwords`
- work together (checked in `faster_whisper/transcribe.py`, `get_prompt`,
- version 1.2.1). Both count against the same 223-token window of their own.
- - Neutral example for `whisper.initialPrompt`:
- `Release notes for Kubernetes, PostgreSQL and Grafana.`
- - Hints raise the odds of a spelling; they do not guarantee it. Keep them
- short and spell terms the way they should appear.
-- Repetition loops on long audio: the sequential decoder conditions every
- window on the previous text and can get stuck repeating itself. The server
- therefore (1) keeps `condition_on_previous_text` off by default
- (`whisper.conditionOnPreviousText`), (2) sends audio longer than
- `whisper.batchThresholdSeconds` (default 35 s, `WHISPER_BATCH_THRESHOLD_S`)
- through faster-whisper's `BatchedInferencePipeline` (VAD-cut chunks decoded
- independently, `whisper.batchSize` = 8, `WHISPER_BATCH_SIZE`), and (3) uses
- faster-whisper's temperature fallback (0.0, 0.2, ... 1.0 with its default
- compression-ratio, log-prob and no-speech thresholds) on the sequential
- path. The batched path always uses VAD and only the first temperature (the
- library does not fall back there). A request's explicit `temperature` form
- field (including `0`) is used as given, without fallback; clients that always
- send `temperature=0` therefore get no fallback on the sequential path.
- Measured locally (FLEURS de, int8, 4 threads, beam 1, VAD): three 55-88 s
- clips WER 3.1 % instead of 42 % (one clip looped to 256 instead of 120
- words) and 56 s of audio in 17.8 s instead of 27.2 s; 40 single clips
- 5.6 % vs 5.2 % (noise); no speed difference on short clips.
-- Warmup: after loading the model the server runs a 2 s synthetic clip through
- VAD and decoder (`WHISPER_WARMUP`, default `true`) so the first real request
- does not pay the initialisation cost. `/health` returns 503 until model and
- warmup are done; a failed warmup is logged and does not block startup.
-- Model source and pins: the image bakes `large-v3-turbo` from
- `dropbox-dash/faster-whisper-large-v3-turbo` at a fixed commit
- (`WHISPER_MODEL_REVISION` in `deploy/Containerfile.whisper`) and verifies
- `model.bin` against its SHA-256; the build fails if either changes. This is
- the repository faster-whisper's `large-v3-turbo` alias
- (`mobiuslabsgmbh/faster-whisper-large-v3-turbo`) redirects to (HTTP 307);
- `Systran/faster-whisper-large-v3-turbo` answers HTTP 401. Model license: MIT.
- Python dependencies are pinned in `deploy/whisper/requirements.txt` (`av`
- must stay on 16.x, newer majors break faster-whisper 1.2.1) and the base
- image by digest.
-- Per-request log line (JSON after the prefix `whisper_request`), e.g.
- `whisper_request {"status":"ok","path":"standard","audio_s":9.0,"prep_s":0.4,"infer_s":7.6,"total_s":8.1,"rtf":0.889,...}`:
- audio duration (`audio_s`, `audio_after_vad_s`), upload, queue wait, decode +
- VAD (`prep_s`) and inference (`infer_s`) time, real-time factor
- (`rtf = (prep_s + infer_s) / audio_s`), model, language, `beam_size`, `vad`, `path` (`standard|batched`),
- `temperature_mode` (`fallback|fixed`),
- file size, and `prompt_chars` / `hotwords_chars` / `prompt_source`
- (`none|default|request|both`). Prompt, hotwords and transcript text are
- never logged.
-- `/v1/audio/translations` (to English) is exposed, but large-v3-turbo is not
- trained for translation; use a non-turbo model for that.
-
-### Scheduling (`affinity`, `topologySpreadConstraints`)
-
-`embedding` and `whisper` accept optional `affinity` and
-`topologySpreadConstraints` (empty by default, so the rendered manifests do not
-change). With `embedding.replicaCount > 1` the replicas can land on one node,
-and then the PodDisruptionBudget does not protect against a node failure.
-Example, soft spreading that never blocks scheduling:
-
-```yaml
-embedding:
- replicaCount: 2
- affinity:
- podAntiAffinity:
- preferredDuringSchedulingIgnoredDuringExecution:
- - weight: 100
- podAffinityTerm:
- topologyKey: kubernetes.io/hostname
- labelSelector:
- matchLabels:
- app.kubernetes.io/component: embedding
- topologySpreadConstraints:
- - maxSkew: 1
- topologyKey: kubernetes.io/hostname
- whenUnsatisfiable: ScheduleAnyway
- labelSelector:
- matchLabels:
- app.kubernetes.io/component: embedding
+```bash
+make test # go test -race ./...
+make lint # golangci-lint
+make test-local # end-to-end test against mock backends
```
-## Environment Variables
-
-| Variable | Default | Description |
-| ---------------------- | ------- | ----------------------------- |
-| `ROUTER_ADDR` | `:8080` | Main listen address |
-| `ROUTER_METRICS_ADDR` | `:9090` | Prometheus metrics address |
-| `ROUTER_READ_TIMEOUT` | `120s` | HTTP read timeout |
-| `ROUTER_WRITE_TIMEOUT` | `300s` | HTTP write timeout |
-| `EMBEDDING_ENABLED` | `false` | Enable embedding backend |
-| `EMBEDDING_URL` | — | Base URL for TEI embedding |
-| `EMBEDDING_TIMEOUT` | `60s` | Per-request timeout |
-| `RERANKER_ENABLED` | `false` | Enable reranker backend |
-| `RERANKER_URL` | — | Base URL for reranker |
-| `RERANKER_TIMEOUT` | `30s` | Per-request timeout |
-| `WHISPER_ENABLED` | `false` | Enable Whisper backend |
-| `WHISPER_URL` | — | Base URL for Whisper |
-| `WHISPER_TIMEOUT` | `300s` | Per-request timeout |
-| `LOG_LEVEL` | `info` | `debug`/`info`/`warn`/`error` |
-| `LOG_FORMAT` | `json` | `json`/`console` |
-
-## Security
-
-- All containers run as non-root (uid 1000 or 65532)
-- `allowPrivilegeEscalation: false`
-- `capabilities: drop: [ALL]`
-- ONNX Runtime exec-stack flag cleared via patchelf
-- No outbound network calls at runtime (`HF_HUB_OFFLINE=1`)
-- Router image uses distroless base (no shell)
+Pull requests are welcome. Releases are cut automatically from `main`
+per component, see [AGENTS.md](AGENTS.md#container-image-versioning).
## License
-[Apache License 2.0](LICENSE)
+[Apache License 2.0](LICENSE). The models have their own licenses: check the model cards of the models you use.
diff --git a/assets/banner.png b/assets/banner.png
new file mode 100644
index 0000000000000000000000000000000000000000..7eda2ef630e4838b9ff4802e750c055dec367301
GIT binary patch
literal 80595
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