No description
  • Python 94.7%
  • Dockerfile 5.3%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-10-10 19:52:25 +00:00
.gitignore docs: README s architekturou, konfiguraci, monitoringem a historii incidentu 2026-10-10 19:52:25 +00:00
app.py upgrade: Haiku 5.5 + lepsi prompt pro kvalitnejsi preklady 2026-10-10 19:32:10 +00:00
docker-compose.yml Initial: LibreTranslate-compatible Claude translation wrapper 2026-09-14 19:03:16 +00:00
Dockerfile Initial: LibreTranslate-compatible Claude translation wrapper 2026-09-14 19:03:16 +00:00
README.md docs: README s architekturou, konfiguraci, monitoringem a historii incidentu 2026-10-10 19:52:25 +00:00
requirements.txt Initial: LibreTranslate-compatible Claude translation wrapper 2026-09-14 19:03:16 +00:00

mt-wrapper

Self-hosted překladový backend pro Mastodon, kompatibilní s LibreTranslate API. Překládá přes Anthropic Claude. Nasazeno jako lt.oscloud.cz, obsluhuje mamutovo.cz.

Co to řeší

Mastodon umí volat LibreTranslate pro překlad postů. Vlastní LibreTranslate dával slabou kvalitu (Argos modely), DeepL stál 20 €/měsíc. Tenhle wrapper se tváří jako LibreTranslate (endpointy /translate a /languages), ale pod kapotou volá Claude API. Mastodon o výměně neví, config neměnil.

Architektura

Mastodon  →  nginx (HTTPS, LE cert)  →  gunicorn :5000  →  Claude API
                                            ↑
                                      Docker kontejner
  • Flask + gunicorn 2 workers × 4 threads
  • Běží v Docker Compose na 127.0.0.1:5000
  • nginx reverse proxy s Let's Encrypt
  • Stateless, kód v gitu, žádná databáze

Konfigurace (.env)

ANTHROPIC_API_KEY=sk-ant-...
LT_API_KEY=<klic ktery pouziva Mastodon>
MODEL=claude-haiku-5-5
MAX_TOKENS=3000

MODEL — jakýkoli Claude model (haiku-5-5, sonnet-4-5, opus-...). Změna modelu = úprava jednoho řádku a rebuild.

MAX_TOKENS=3000 — rezerva pro posty do 2500 znaků (mamutovo má custom limit).

LT_API_KEY — klíč, který Mastodon posílá v každém requestu. Musí odpovídat tomu, co má Mastodon nastavené.

Endpointy

GET /

Healthcheck. Vrací {"status":"ok","backend":"claude","model":"..."}. Nevolá API — monitoring tím zjistí jen že proces běží.

GET /languages

Seznam podporovaných jazyků s poli targets. Mastodon si z toho staví tabulku podporovaných překladových dvojic — musí tam být targets, jinak Mastodon překlad odmítne u sebe.

POST /translate

Přijímá q (string nebo pole stringů), source, target, api_key. Při poli (Mastodon posílá text + spoiler + alt texty najednou) překládá položky paralelně přes ThreadPoolExecutor.

Nasazení

git clone https://git.oscloud.cz/Mamutovo/mt-wrapper.git
cd mt-wrapper
cp .env.example .env
# edituj .env
sudo docker compose up -d --build

nginx config (zjednodušeno):

server {
    listen 80;
    server_name lt.oscloud.cz;
    location / {
        proxy_pass http://127.0.0.1:5000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Pak certbot --nginx -d lt.oscloud.cz pro HTTPS.

Update modelu

cd ~/mt-wrapper
sed -i 's/^MODEL=.*/MODEL=claude-sonnet-4-5/' .env
sudo docker compose up -d --build
curl -s https://lt.oscloud.cz/ && echo

Monitoring

Uptime Kuma (status.oscloud.cz), dva monitory, interval 300 s, retries 2:

  1. lt.oscloud-translate

    • URL: https://lt.oscloud.cz/translate
    • Method: POST
    • Body encoding: x-www-form-urlencoded
    • Body: q=hello world&source=en&target=cs&api_key=<klic>
    • Keyword: translatedText
  2. lt.oscloud-languages

    • URL: https://lt.oscloud.cz/languages
    • Method: GET
    • Keyword: targets

Notifikace: ntfy + email.

Historie incidentů

17. 9. 2026 — chybějící targets v /languages

Wrapper vracel u jazyků jen code a name. Mastodon se nemohl rozhodnout, mezi kterými jazyky umí překládat, a odmítal každý překlad u sebe (hláška "Translation failed. Maybe the administrator has not enabled..." — zavádějící, server funguje). Opraveno přidáním pole targets do odpovědi /languages.

21. 9. 2026 — timeouty u postů s obrázky (499)

Mastodon posílá dávku (text + spoiler + alt texty) jako pole. Wrapper je překládal postupně, u postu se 4 obrázky = 5 volání za sebou = ~5 s, Mastodon mezitím vzdal (499 Client Closed Request v nginx logu). Opraveno paralelizací přes ThreadPoolExecutor(max_workers=min(len(q), 8)).

29. 9. 2026 — ojedinělá chyba credential validation failed

Anthropic API vrátilo InternalServerError: credential validation failed (ne 401 — tedy ne vadný klíč, byl to jejich dočasný problém s ověřením). Preventivně přidán retry na úrovni SDK:

anthropic.Anthropic(api_key=..., max_retries=3, timeout=25.0)

Timeout kratší než gunicorn, aby se retry stihly.

8. 10. 2026 — false alarmy z Kumy (DNS)

Kuma hlásila getaddrinfo ENOTFOUND lt.oscloud.cz. Příčina nebyla ve wrapperu — Hetznerovy resolvery (185.12.64.1/2) zahazovaly ~50 % UDP paketů. Reprodukce: dig +time=1 +tries=1 lt.oscloud.cz @185.12.64.1 opakovaně, Quad9 ze stejného stroje čistě. Řešení: přepnout resolver nebo postavit lokální cachovací unbound.

10. 10. 2026 — upgrade na Haiku 5.5 + lepší prompt

Starý prompt byl ořezaný na úsporu tokenů. Nový vysvětluje: překládej přirozeně, respektuj kapitalizaci cílového jazyka, správně skloňuj cizí slova. Model Haiku 5.5 (nová generace, 10× levnější než 4.5). Reálný měsíční provoz ~$0.30 místo $3.

Benchmark modelů (10. 10. 2026, překlad Zelenského postu EN→CS)

model latence cena/preklad kvalita
Haiku 4.5 (starý prompt) 4,6 s $0,002 "pohon proudu šahedů" — nesmysl
Haiku 4.5 (nový prompt) 4,6 s $0,002 "drony se spalovacím motorem" — nesmysl
Haiku 5.5 (nový prompt) 1–3 s $0,0003 "Rusko si zvolilo válku" — přirozené
Sonnet 4.5 (nový prompt) 10,9 s $0,006 "proudovými sahedy" — nejpřesnější
gpt-4.1-mini (nový prompt) 2,2 s $0,0006 "miliardový dolar", překlepy

Haiku 5.5 vyhrává poměr cena/kvalita/rychlost.

Náklady

Při typickém provozu mamutovo.cz (odhad říjen 2026):

  • Haiku 5.5: ~$0,30 / měsíc = ~0,30 €
  • Sonnet 4.5: ~$9 / měsíc = ~8 €
  • DeepL (pro srovnání): 20 € / měsíc

Užitečné příkazy

# logy
sudo docker logs mt-wrapper --tail 50 -f

# restart bez rebuildu
sudo docker compose restart

# rebuild po změně kódu
sudo docker compose up -d --build

# ruční test prekladu
KEY=$(grep LT_API_KEY .env | cut -d= -f2)
curl -s -X POST https://lt.oscloud.cz/translate \
  -d "q=hello world" -d "source=en" -d "target=cs" -d "api_key=$KEY"

# diagnostika: ztrácejí se DNS pakety?
for i in $(seq 1 20); do
  dig +time=1 +tries=1 +short lt.oscloud.cz @185.12.64.1 \
    >/dev/null 2>&1 && echo -n "." || echo -n "X"
done; echo

Co stojí za zvážení

  • Rate limiting (flask-limiter) proti zneužití LT_API_KEY
  • Lokální unbound na strojích v Hetzneru místo spoléhání na jejich resolver
  • Vícejazyčná verze promptu — teď je obecný, mohl by být rozlišen podle target