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 - -[![Go Tests](https://github.com/layer87-labs/inference-stack/actions/workflows/ci.yml/badge.svg)](https://github.com/layer87-labs/inference-stack/actions/workflows/ci.yml) -[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE) - -Unified CPU-based inference stack — serving embeddings, reranking and transcription behind a single OpenAI-compatible API. +

+ inference-stack: embeddings, reranking and speech-to-text on plain CPU +

-## Components +

+ Latest router release + CI + Go version + License: Apache-2.0 +

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

O!HX&(PWmA8ovVn(9N2j!NE+10<=io}A#62TOx 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 T#v@GI#k@xEw9zRR(Kh5?TXFEn literal 0 HcmV?d00001 diff --git a/assets/icon-tile.svg b/assets/icon-tile.svg new file mode 100644 index 0000000..88d9af1 --- /dev/null +++ b/assets/icon-tile.svg @@ -0,0 +1,2 @@ + + diff --git a/assets/icon.svg b/assets/icon.svg new file mode 100644 index 0000000..f817758 --- /dev/null +++ b/assets/icon.svg @@ -0,0 +1,2 @@ + + diff --git a/assets/lockup-dark.svg b/assets/lockup-dark.svg new file mode 100644 index 0000000..e024b62 --- /dev/null +++ b/assets/lockup-dark.svg @@ -0,0 +1,2 @@ + + diff --git a/assets/lockup-light.svg b/assets/lockup-light.svg new file mode 100644 index 0000000..09e7bae --- /dev/null +++ b/assets/lockup-light.svg @@ -0,0 +1,2 @@ + + diff --git a/assets/logo.svg b/assets/logo.svg new file mode 100644 index 0000000..b862611 --- /dev/null +++ b/assets/logo.svg @@ -0,0 +1,2 @@ + + diff --git a/docs/configuration.md b/docs/configuration.md new file mode 100644 index 0000000..8c8968f --- /dev/null +++ b/docs/configuration.md @@ -0,0 +1,60 @@ +# Configuration + +The router is configured exclusively through environment variables (`internal/config/config.go`). With the +Helm chart the backend variables are set for you; add or override variables with `router.extraEnv`. + +At least one backend must be enabled, and every enabled backend needs its `*_URL`, otherwise the router exits +at startup with a config error. + +| Variable | Default | Description | +| --- | --- | --- | +| `ROUTER_ADDR` | `:8080` | Main listen address | +| `ROUTER_METRICS_ADDR` | `:9090` | Prometheus metrics address (`/metrics`) | +| `ROUTER_READ_TIMEOUT` | `120s` | HTTP read timeout | +| `ROUTER_WRITE_TIMEOUT` | `300s` | HTTP write timeout | +| `ROUTER_IDLE_TIMEOUT` | `60s` | HTTP idle timeout | +| `ROUTER_MAX_REQUEST_SIZE` | `104857600` | Maximum request body in bytes (100 MB) | +| `LOG_LEVEL` | `info` | `debug`, `info`, `warn` or `error` | +| `LOG_FORMAT` | `json` | `json` or `console` | +| `EMBEDDING_ENABLED` | `false` | Enable the embedding backend | +| `EMBEDDING_URL` | none | Base URL of the TEI embedding server | +| `EMBEDDING_TIMEOUT` | `60s` | Per-request timeout | +| `EMBEDDING_MAX_CONCURRENT` | `20` | Requests forwarded at once; more get `503` + `Retry-After` | +| `RERANKER_ENABLED` | `false` | Enable the reranker backend | +| `RERANKER_URL` | none | Base URL of the TEI reranker server | +| `RERANKER_TIMEOUT` | `30s` | Per-request timeout | +| `RERANKER_MAX_CONCURRENT` | `20` | Requests forwarded at once; more get `503` + `Retry-After` | +| `WHISPER_ENABLED` | `false` | Enable the Whisper backend | +| `WHISPER_URL` | none | Base URL of the Whisper server | +| `WHISPER_TIMEOUT` | `300s` | Per-request timeout | +| `WHISPER_MAX_CONCURRENT` | `8` | Requests forwarded at once; more get `503` + `Retry-After` | + +A value of `0` or below for a `*_MAX_CONCURRENT` variable disables the bound for that backend. + +## Backpressure + +When a backend is at its concurrency bound the router answers immediately with +`503 Service Unavailable`, a `Retry-After: 3` header and `{"error":"backend_overloaded", ...}` instead of +queuing the request. Clients should back off and retry. Each rejection increments +`inference_router_rejected_total{backend}`. + +## Health endpoints + +| Path | Port | Behaviour | +| --- | --- | --- | +| `/healthz`, `/readyz` | 8080 | Backends are probed (`GET /health`) every 15 seconds. The answer is always HTTP 200; the JSON body says `ok` or `degraded` and lists each backend as `ok`, `unhealthy` or `disabled`. A failing backend does not take the router out of rotation. | +| `/health` | 8080 | Router liveness only: `{"status":"ok"}` | +| `/metrics` | 9090 | Prometheus metrics | + +## Metrics + +| Metric | Type | Labels | +| --- | --- | --- | +| `inference_router_requests_total` | counter | `backend`, `path`, `status` | +| `inference_router_request_duration_seconds` | histogram | `backend`, `path` | +| `inference_router_request_size_bytes` | histogram | `backend` | +| `inference_router_response_size_bytes` | histogram | `backend` | +| `inference_router_active_requests` | gauge | `backend` | +| `inference_router_backend_up` | gauge | `backend` | +| `inference_router_upstream_errors_total` | counter | `backend`, `error_type` | +| `inference_router_rejected_total` | counter | `backend` | diff --git a/docs/tuning.md b/docs/tuning.md new file mode 100644 index 0000000..183d1f2 --- /dev/null +++ b/docs/tuning.md @@ -0,0 +1,220 @@ +# CPU tuning and sizing + +Measurements and settings for running the stack on plain CPU. The Helm values referenced here are in +[`deploy/helm/values.yaml`](../deploy/helm/values.yaml); see also [Configuration](configuration.md). + +## 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: + +```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 +```