first

2026-07-10 09:46:49 +02:00
parent 429cb84461
commit 7a3f61c125
16 changed files with 762 additions and 16 deletions
@@ -0,0 +1,66 @@
+# audio-transcription — přehled
+
+Stateless FastAPI služba v AppFactory. Přijme audio + parametry v POST a vrátí JSON
+s přepisy. Přepis běží dvěma engine paralelně (Deepgram + OpenAI Whisper) a volitelně
+se oba texty sloučí přes OpenAI Chat do jednoho co nejpřesnějšího přepisu.
+
+Vychází z původní .NET implementace `CallCenterController` (dual/combined přepis).
+Napojení na Twilio bylo vynecháno — audio se posílá přímo jako proměnná (upload).
+
+## Architektura
+
+```
+app/
+  main.py              # FastAPI app, root_path, Swagger, exception handlers
+  config.py            # env konfigurace + defaulty (žádné secrets)
+  logging_config.py    # logging (bez secrets)
+  errors.py            # typované výjimky + handlery (žádná tichá selhání)
+  credentials.py       # X- hlavičky → přihlašovací údaje (stateless)
+  prompts.py           # výchozí slučovací prompt (Czech Transcript Merger)
+  clients/
+    deepgram_client.py # Deepgram pre-recorded REST (httpx)
+    openai_client.py   # OpenAI Whisper + Chat Completions (httpx)
+  routers/
+    meta.py            # /health, /version
+    transcribe.py      # /transcribe/dual, /transcribe/combined
+```
+
+Žádné SDK — upstream API se volají přímo přes `httpx`, aby služba nebyla závislá na
+verzích knihoven. Nic se neukládá; služba je multi-tenant a stateless.
+
+## Reverse proxy
+
+Běží za `/apps/audio-transcription`. `root_path` se čte z env `ROOT_PATH`, takže
+OpenAPI `servers` i Swagger „Try it out“ míří na správný prefix.
+
+## Endpointy
+
+| Metoda | Cesta | Popis |
+|--------|-------|-------|
+| GET | `/health` | Health check (200) |
+| GET | `/version` | Verze + root_path |
+| POST | `/transcribe/dual` | Deepgram + Whisper (dva texty) |
+| POST | `/transcribe/combined` | dual + sloučený `merged` |
+
+Detaily viz [transcribe.md](transcribe.md).
+
+## Přihlašovací údaje
+
+Secrets se předávají v hlavičkách u každého requestu (nikdy v těle/URL, nikdy se
+nelogují ani neukládají):
+
+- `X-Deepgram-Api-Key`
+- `X-OpenAI-Api-Key`
+
+## Konfigurace (env)
+
+| Proměnná | Default | Popis |
+|----------|---------|-------|
+| `ROOT_PATH` | `""` | Prefix reverse proxy (`/apps/audio-transcription`) |
+| `DEFAULT_DEEPGRAM_MODEL` | `nova-2` | Výchozí Deepgram model |
+| `DEFAULT_WHISPER_MODEL` | `whisper-1` | Výchozí OpenAI přepisový model |
+| `DEFAULT_CHAT_MODEL` | `gpt-4o` | Výchozí chat model pro sloučení |
+| `DEFAULT_LANGUAGE` | `cs` | Výchozí jazyk |
+| `UPSTREAM_TIMEOUT_SECONDS` | `300` | Timeout upstream volání |
+| `DEEPGRAM_BASE_URL` | `https://api.deepgram.com/v1` | Base URL Deepgram |
+| `OPENAI_BASE_URL` | `https://api.openai.com/v1` | Base URL OpenAI |
@@ -0,0 +1,97 @@
+# Endpointy přepisu
+
+Audio se posílá jako proměnná `file` (multipart/form-data). Všechny ostatní parametry
+jsou form fields v POST. API klíče jsou v X- hlavičkách. Výstup je vždy JSON.
+
+## Hlavičky (secrets)
+
+| Hlavička | Nutná | Popis |
+|----------|-------|-------|
+| `X-Deepgram-Api-Key` | ano | Deepgram API klíč |
+| `X-OpenAI-Api-Key` | ano | OpenAI API klíč (Whisper + slučovací chat) |
+
+## POST /transcribe/dual
+
+Paralelní přepis dvěma engine. Vrací dva nezávislé texty.
+
+### Form parametry
+
+| Pole | Typ | Default | Popis |
+|------|-----|---------|-------|
+| `file` | soubor | — | Audio k přepisu (povinné) |
+| `deepgram_model` | text | `nova-2` | Deepgram model |
+| `whisper_model` | text | `whisper-1` | OpenAI přepisový model |
+| `language` | text | `cs` | Jazyk (ISO kód) |
+| `diarize` | bool | `true` | Deepgram diarizace |
+| `smart_format` | bool | `true` | Deepgram smart formatting |
+
+### Odpověď
+
+```json
+{
+  "text1": "přepis z Deepgramu",
+  "text2": "přepis z OpenAI Whisper",
+  "deepgram_model": "nova-2",
+  "whisper_model": "whisper-1",
+  "language": "cs"
+}
+```
+
+### Příklad (curl)
+
+```bash
+curl -X POST https://services.csbot.cz/apps/audio-transcription/transcribe/dual \
+  -H "X-Deepgram-Api-Key: <DEEPGRAM_KEY>" \
+  -H "X-OpenAI-Api-Key: <OPENAI_KEY>" \
+  -F "file=@nahravka.mp3" \
+  -F "language=cs"
+```
+
+## POST /transcribe/combined
+
+Jako `dual`, navíc oba přepisy sloučí přes OpenAI Chat do jednoho výsledku (`merged`).
+
+### Form parametry
+
+Vše z `dual`, plus:
+
+| Pole | Typ | Default | Popis |
+|------|-----|---------|-------|
+| `combine_prompt` | text | výchozí „Czech Transcript Merger“ | System prompt pro sloučení |
+| `chat_model` | text | `gpt-4o` | OpenAI chat model pro sloučení |
+
+Nezadá-li se `combine_prompt`, použije se výchozí prompt z `app/prompts.py`.
+
+### Odpověď
+
+```json
+{
+  "text1": "přepis z Deepgramu",
+  "text2": "přepis z OpenAI Whisper",
+  "merged": "sloučený, co nejpřesnější výsledný přepis",
+  "deepgram_model": "nova-2",
+  "whisper_model": "whisper-1",
+  "chat_model": "gpt-4o",
+  "language": "cs"
+}
+```
+
+### Příklad (curl)
+
+```bash
+curl -X POST https://services.csbot.cz/apps/audio-transcription/transcribe/combined \
+  -H "X-Deepgram-Api-Key: <DEEPGRAM_KEY>" \
+  -H "X-OpenAI-Api-Key: <OPENAI_KEY>" \
+  -F "file=@nahravka.mp3"
+```
+
+## Chybové stavy
+
+| HTTP | Kdy |
+|------|-----|
+| 400 | Chybí / prázdný audio soubor |
+| 401 | Chybí `X-Deepgram-Api-Key` nebo `X-OpenAI-Api-Key` |
+| 502 | Chyba upstream API (Deepgram / OpenAI) |
+| 500 | Neočekávaná chyba serveru |
+
+Všechny chyby se logují (bez secrets), žádné tiché selhání.