Initialize repo
This commit is contained in:
@@ -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.
|
||||
Reference in New Issue
Block a user