Initialize repo

This commit is contained in:
Patryk Gensch
2026-11-15 15:39:55 +01:00
commit af37f7966d
27 changed files with 5678 additions and 0 deletions
+141
View File
@@ -0,0 +1,141 @@
# Tłumacz napisów SRT
Lokalna aplikacja webowa, która tłumaczy pliki `.srt` modelami LLM uruchomionymi u Ciebie:
**Ollama**, **LM Studio** albo dowolny serwer **OpenAI-compatible** (llama.cpp `llama-server`, vLLM, KoboldCpp, Jan…).
```bash
npm install # tylko @lmstudio/sdk (ładowanie modeli z KV-cache quant); bez niego też działa
npm start # → http://127.0.0.1:8765
npm test
```
Wymaga Node.js ≥ 20. Serwer nie ma innych zależności. `PORT` i `HOST` można ustawić zmiennymi środowiskowymi.
## Jak to działa — czemu ramki czasowe się nie rozjadą
1. Parser SRT zapisuje linie czasu **dosłownie**. Model ich w ogóle nie widzi: dostaje tylko tekst z numerami (`[17] …`).
2. Napisy idą partiami (domyślnie 25) razem z kilkoma poprzednimi (już przetłumaczonymi) i następnymi liniami jako kontekstem.
3. **Tryb JSON (domyślny):** odpowiedź jest ograniczona schematem JSON (Ollama `format`, LM Studio/OpenAI `response_format: json_schema`)
z dokładnie tymi kluczami, w tej kolejności. Klucz zawiera początek oryginału, np. `"17|The partner's office…"`. Gramatyka każe modelowi
napisać go tuż przed tłumaczeniem, więc każda wartość jest przypięta do swojego napisu. To usuwa klasyczny błąd, w którym od jakiegoś
miejsca wszystko jest przesunięte o jedną linię.
4. Wynik jest sprawdzany: czy nie brakuje id, czy odpowiedź nie została ucięta, czy model nie skopiował oryginału, nie scalił dwóch linii
i nie powtarza tłumaczeń. Jeśli coś jest nie tak, partia jest dzielona na pół, a pojedyncze problematyczne linie idą osobno.
Zdanie scalone z dwóch napisów (jedna linia pełna, druga pusta) jest dzielone automatycznie, proporcjonalnie do długości oryginałów.
5. Formatowanie obejmujące cały napis (`{\an8}`, `<i>…</i>`) jest zdejmowane przed tłumaczeniem i potem przywracane. Linie bez liter
(`♪ ♪`) są kopiowane bez pytania modelu. Za długie linie są zawijane (domyślnie do 42 znaków, maks. 2 linie).
Inne tryby: **numerowane linie** (dla serwerów bez structured output; odporny parser bierze ostatni kompletny blok odpowiedzi)
i **po jednej linii**. Jeśli model „myśli na głos” i w trybie linii ucina odpowiedzi, zadanie samo przełącza się na JSON.
**Piosenki (linie z ♪/♫ albo w starym stylu `# … #`)** mają trzy tryby: *tłumacz jak resztę*, *zostaw w oryginale*
albo *usuń z napisów*. W dwóch ostatnich linie piosenek w ogóle nie trafiają do modelu (szybciej, mniej tokenów) i nie są używane
jako kontekst. Usuwanie dzieje się przy eksporcie: napis z samą piosenką znika, a w napisie mieszanym („- ♪ Sto lat ♪ / - Przestań!”)
usuwane są tylko linie piosenki. Pozostałe napisy zachowują dokładnie swoje czasy i są numerowane od nowa. Wieloliniowa zwrotka
otwarta i zamknięta nutą w jednym napisie jest rozpoznawana w całości. Opisy dźwięków typu `[music playing]` nie są traktowane
jako piosenki. Zmiana trybu nie wymaga ponownego tłumaczenia.
W tabeli wyników tłumaczenia można edytować ręcznie, a każdą linię przetłumaczyć ponownie (↻). Podejrzane linie są oznaczane:
za krótkie lub za długie względem oryginału, bez zmian, >2 linie, za długie linie, za szybkie do przeczytania (>21 znaków/s).
Praca zapisuje się w przeglądarce, a „Dokończ brakujące” wznawia przerwane tłumaczenie. Eksport: samo tłumaczenie albo
napisy dwujęzyczne, LF/CRLF, opcjonalny BOM.
## Kontekst, KV-cache i pamięć
| | Długość kontekstu | Kwantyzacja KV-cache | Szacunek pamięci |
|---|---|---|---|
| **LM Studio** | przy ładowaniu modelu (przycisk „Załaduj model” albo automatycznie na starcie) | ✅ K i V osobno (`q8_0`, `q4_0`, …) przez `@lmstudio/sdk` | estymator LM Studio + własny |
| **Ollama** | `num_ctx` w każdym zapytaniu (Ollama sama przeładuje model) | ustawienie serwera: `OLLAMA_FLASH_ATTENTION=1`, `OLLAMA_KV_CACHE_TYPE=q8_0` | własny + **rzeczywiste** użycie z `/api/ps` po załadowaniu |
| **OpenAI-compat.** | przy starcie serwera (`llama-server -c 16384 -fa on -ctk q8_0 -ctv q8_0`) | argumenty serwera | własny (do planowania) |
Własny szacunek liczy KV-cache warstwa po warstwie na podstawie metadanych GGUF: z Ollamy przez `/api/show`, a dla LM Studio
z nagłówka pliku `.gguf` na dysku. Uwzględnia GQA, warstwy z przesuwnym oknem (Gemma), współdzielony KV-cache (Gemma 3n/4),
modele hybrydowe z warstwami rekurencyjnymi (Qwen3.5/Qwen3-Next), MLA (DeepSeek) i typ kwantyzacji K/V. Na Apple Silicon budżet
to `recommendedMaxWorkingSetSize` z Metal (ta sama wartość, której używają Ollama i llama.cpp; odczytywana raz przez `swift`,
a gdy go nie ma, szacowana na ~74% RAM), albo `iogpu.wired_limit_mb`, jeśli go podniesiono. Na NVIDII to wynik `nvidia-smi`. Bufory obliczeniowe są przybliżone, więc dla LM Studio wiarygodniejszy jest jego własny estymator.
Kwantyzacja V-cache w llama.cpp wymaga Flash Attention. `q8_0` praktycznie nie pogarsza jakości i zmniejsza KV-cache prawie o połowę.
## Pobieranie modeli z aplikacji
W karcie „2. Model” → „Pobierz nowy model” wpisujesz nazwę i widzisz pasek postępu z prędkością i czasem do końca.
Pobieranie trwa na serwerze, więc odświeżenie lub zamknięcie karty go nie przerywa (po powrocie pasek się
podpina). Podpowiedzi tylko wpisują nazwę, a pobieranie startuje dopiero przyciskiem. Modele, które nie zmieszczą
się w pamięci GPU, są oznaczone, a te już pobrane mają ✓.
- **Ollama:** nazwy z biblioteki (`translategemma:12b`) albo dowolne repozytorium GGUF z Hugging Face
(`hf.co/speakleash/Bielik-11B-v3.0-Instruct-GGUF:Q4_K_M`). Postęp przychodzi z `/api/pull`. Przerwanie zatrzymuje
pobieranie, a ponowne pobranie wznawia je od miejsca przerwania.
- **LM Studio:** nazwy z katalogu (`google/gemma-3-12b`) albo link do Hugging Face plus kwantyzacja
(`POST /api/v1/models/download` i odpytywanie statusu). API LM Studio nie ma anulowania, więc pobieranie
wstrzymuje się w panelu Downloads w samym LM Studio.
- Silnik OpenAI-compatible nie ma ujednoliconego pobierania.
## Modele
**Zwykłe LLM-y** (profil „Uniwersalny”) tłumaczą partiami z kontekstem: Gemma, Qwen, Llama, Mistral, Aya Expanse, a dla polskiego
warto też spróbować Bielika (SpeakLeash). Rozumowanie („thinking”) jest domyślnie wyłączane (`think: false` w Ollamie,
`reasoning_effort: "none"` w LM Studio), bo przy tłumaczeniu tylko spowalnia.
**Dedykowane modele tłumaczeniowe** są rozpoznawane po nazwie (profil można też wybrać ręcznie). Dostają swój oficjalny szablon
promptu i tłumaczą po jednym segmencie. Kwestie dialogowe (`- …`) idą linia po linii.
| Profil | Przykłady | Uwagi |
|---|---|---|
| TranslateGemma | `ollama pull translategemma:4b` / `:12b` / `:27b` | wymaga języka źródłowego (aplikacja go wykrywa) |
| Hunyuan-MT / HY-MT | `tencent/HY-MT1.5-7B` (GGUF od społeczności) | zalecane parametry ustawia przycisk „Zastosuj parametry zalecane” |
| Seed-X | `ByteDance-Seed/Seed-X-PPO-7B` | |
| Tower | `Unbabel/Tower-Plus-9B`, TowerInstruct | |
Modele MT tłumaczą zdania bez szerszego kontekstu, więc przy rodzaju gramatycznym i zwrotach (ty/Pan) radzą sobie gorzej niż
dobry LLM z kontekstem. Pole „Uwagi dla tłumacza” (płeć postaci, ton, słowniczek) trafia tylko do profilu uniwersalnego.
## API (dla skryptów)
`POST /api/srt/parse` (surowe bajty pliku) → napisy · `POST /api/jobs` → id zadania · `GET /api/jobs/:id/events` (SSE) ·
`GET /api/jobs/:id` · `POST /api/jobs/:id/cancel` · `POST /api/srt/build` → plik SRT ·
`POST /api/engine/{status,models,model-info,estimate,load,unload,loaded}`.
## Struktura
```
server.js serwer HTTP + API (bez frameworka)
src/srt.js parser/serializer SRT, wykrywanie kodowania, tagi, zawijanie
src/translator.js zadanie tłumaczenia: partie, walidacja, podziały, naprawy
src/prompts.js prompty, schemat JSON, szablony modeli MT, parser linii
src/vram.js szacowanie pamięci z metadanych GGUF, pamięć systemu
src/gguf.js czytnik nagłówka GGUF
src/engines/ ollama.js, lmstudio.js, openai.js
public/ interfejs (HTML/CSS/JS bez bundlera)
samples/ przykładowe napisy
```
## Wyniki testów (MacBook M4, 16 GB)
| Model | Silnik | Tryb | 40 linii | Uwagi |
|---|---|---|---|---|
| gemma-4-e4b Q4_K_M | LM Studio | JSON, partie po 15 | ~40 s | najlepsza jakość z testowanych; potrafi „myśleć na głos” w trybie linii, więc najlepiej JSON |
| translategemma:4b | Ollama | oficjalny szablon MT | ~25 s | szybka (~40 tok/s); bez kontekstu zgaduje rodzaj i ton, czasem przegaduje |
| translategemma:4b | Ollama | JSON z kontekstem | ~34 s | trafniejsza w kontekście, ale daje warianty „byłeś/aś” (oznaczane w tabeli) |
| qwen3.5-9b Q4_K_M | LM Studio | JSON | — | wolniejsza (~13 tok/s); 12 linii w ~15 s |
Szacunek KV-cache porównany z logami llama.cpp (TranslateGemma 4B, 32k): f16 — 814 MiB (szacunek 0.79 GiB),
q8_0 — 432 MiB (szacunek 0.42 GiB). Uwaga: Ollama 0.40 w `/api/ps` raportuje mniej, niż faktycznie zajmuje
(pomija część KV-cache), dlatego aplikacja pokazuje tę wartość jako „Ollama raportuje”, z ostrzeżeniem, gdy jest niespójna.
## Plik wykonywalny (bez instalowania Node.js)
```bash
npm run build:win # → dist/srt-translator-win-x64.zip (srt-translator.exe + JAK-URUCHOMIC.txt)
npm run build:mac # → dist/srt-translator-darwin-arm64.zip
```
Skrypt `scripts/build-exe.mjs` łączy serwer i wszystkie moduły w jeden plik (esbuild), a interfejs (`public/`) dodaje
jako zasoby. Potem wstrzykuje to do oficjalnej binarki Node.js dla systemu docelowego (Node.js Single Executable
Application). Binarki są pobierane raz z nodejs.org do `build/cache` i sprawdzane sumą SHA-256. Node z Homebrew ma
wyłączone SEA, więc do samego budowania skrypt używa wtedy oficjalnego Node dla bieżącego systemu. Wersja Node
uruchamiającego skrypt musi zgadzać się z wersją binarki docelowej.
Gotowy program uruchamia serwer, otwiera przeglądarkę i, jeśli 8765 jest zajęty, sam bierze następny wolny port.
Pliki nie są podpisane, więc Windows SmartScreen („Więcej informacji” → „Uruchom mimo to”) i macOS Gatekeeper
(prawy klik → Otwórz) pytają przy pierwszym uruchomieniu.