Część 9 — Krajobraz narzędzi open source

Poziom: ⭐⭐⭐ (do czytania w dowolnym momencie) · Czas: ~3 h czytania + eksperymenty

Po co ten rozdział. Części 1–8 nauczyły Cię budować wszystko od zera — celowo, żebyś rozumiał mechanizmy. Teraz możesz świadomie wybierać gotowe narzędzia, bo wiesz, co one robią pod spodem i co ukrywają.

Ten rozdział to katalog z oceną, nie lista linków. Przy każdym narzędziu: co robi, kiedy je wziąć, kiedy nie — i czy zadziała na Twoim RDNA4, bo to jest realne sito, które odsiewa połowę ekosystemu.

---

⚠️ Zanim zaczniesz: Twoje żelazo to sito

Masz Radeon AI PRO R9700, gfx1201, RDNA4, ROCm 7.2.4. To jest architektura nowa i niszowa. Znaczna część ekosystemu AI zakłada NVIDIA/CUDA.

Trzy poziomy wsparcia, którymi oceniam każde narzędzie:

⚠️ To nie jest wada Twojego wyboru sprzętu. Masz 65 GB VRAM za ułamek ceny odpowiednika NVIDII. Płacisz za to czasem na integrację. Wiedz o tym, wybierając narzędzie.

---

Spis treści

---

1. Silniki inferencji

To jest kategoria, o którą pytałeś wprost. llama.cpp to Twój start — oto reszta.

1.1 Porównanie

1.2 ⭐ vLLM — kiedy naprawdę warto

Co robi lepiej od llama.cpp:

⭐ Kiedy vLLM wygrywa: WIELU RÓWNOLEGŁYCH UŻYTKOWNIKÓW. Dla jednego agenta llama.cpp jest w zupełności wystarczający i dużo prostszy.

⚠️ Realia na gfx1201 — to jest wiedza, którą masz już zapisaną w projekcie:

# Szkic uruchomienia (wymaga Dockera - ktorego NIE masz, patrz czesc 7 §2)
# sudo apt install -y docker.io
# docker run --rm -it --device=/dev/kfd --device=/dev/dri \
#   --group-add video --ipc=host --shm-size 16G \
#   -e NCCL_P2P_DISABLE=1 -e NCCL_PROTO=Simple \
#   -p 8000:8000 kyuz0/vllm-therock-gfx1201 \
#   --model /models/... --tensor-parallel-size 2

💡 Rekomendacja: vLLM zostaw na później. Wracaj do niego, gdy (a) będziesz serwował wielu klientów naraz, albo (b) llama.cpp okaże się wąskim gardłem zmierzonym, a nie przeczuwanym.

1.3 ⛔ Ollama i LM Studio — dlaczego nie u Ciebie

Oba są wygodne. Oba niosą własny, wbudowany silnik.

⚠️ To rozwala Twoją metodykę pomiarową. Cała Twoja dyscyplina zapisuje dokładny commit llama.cpp i flagi budowy (GGML_HIP=ON, GPU_TARGETS=gfx1201). Drugi silnik o nieznanej konfiguracji oznacza, że pomiar przestaje opisywać to, co realnie serwujesz. Na świeżym gfx1201 to nie jest ryzyko teoretyczne.

💡 To nie znaczy, że są złe. Dla kogoś, kto chce pogadać z modelem — Ollama jest świetna. Dla kogoś, kto sprzedaje liczby wydajnościowe klientowi — nie.

---

2. Bramki i orkiestracja

2.1 LiteLLM — wart uwagi

python3 -m venv $VENVS/litellm
$VENVS/litellm/bin/pip install 'litellm[proxy]'

cat > $KURS/litellm.yaml <<'EOF'
model_list:
  - model_name: lokalny-maly
    litellm_params:
      model: openai/gpt-oss-20b
      api_base: http://127.0.0.1:8081/v1
      api_key: nieuzywany
  - model_name: lokalny-duzy
    litellm_params:
      model: openai/qwen3-32b
      api_base: http://127.0.0.1:8082/v1
      api_key: nieuzywany
EOF

$VENVS/litellm/bin/litellm --config $KURS/litellm.yaml --port 4000

⭐ Dlaczego to ma sens: jedno API dla modeli lokalnych i Claude (część 10). Zmiana modelu = zmiana jednego stringa. Ma też wbudowane liczenie kosztów i limity.

---

3. Interfejsy użytkownika

# Open WebUI - najprosciej (wymaga Dockera albo pip)
python3 -m venv $VENVS/webui
$VENVS/webui/bin/pip install open-webui
OPENAI_API_BASE_URL=http://127.0.0.1:8080/v1 \
  $VENVS/webui/bin/open-webui serve --port 3000

💡 Dla produktu księgowego AnythingLLM jest wart obejrzenia — ma gotowe wgrywanie dokumentów, izolację „workspace'ów" per klient i cytowania. Zanim go weźmiesz, zrozum, że robi to samo, co Twoja część 4 — tylko bez Twojej kontroli nad chunkingiem.

---

4. Wymuszanie struktury

Część 3 robiła to gramatykami GBNF. Alternatywy:

⚠️ Rozróżnienie, które ma znaczenie: Outlines/XGrammar/GBNF wymuszają na poziomie próbkowania — wynik jest gwarantowany. Instructor próbuje i powtarza — gwarancji nie ma. Dla lokalnego modelu 20B ta różnica jest krytyczna (część 3 §2.1).

---

5. Bazy wektorowe

5.1 Ścieżka rozwoju

część 4 (sqlite + Python)  →  sqlite-vec  →  LanceDB  →  Qdrant
      < 100k fragmentów       < 1 mln       < 10 mln    powyżej

# sqlite-vec - najmniejszy skok z czesci 4
python3 -m venv $VENVS/kurs
$VENVS/kurs/bin/pip install sqlite-vec

💡 Nie przeskakuj od razu na Qdranta. Twoja baza z części 4 wystarcza do dziesiątek tysięcy fragmentów i rozumiesz ją w całości. Migruj, gdy zmierzysz, że wyszukiwanie trwa za długo — nie wcześniej.

---

6. Embeddingi i reranking

6.1 Modele embeddingowe

⭐ mmlw to polski model embeddingowy z Politechniki Wrocławskiej. Zmierz go przeciwko bge-m3 metodą „marginesu" z części 4 §2.4 — na polskim tekście księgowym może wygrać.

6.2 Reranking

💡 Dedykowany reranker jest 10–50× szybszy niż LLM w tej roli i zwykle trafniejszy. Jeśli reranking z części 4 jest u Ciebie wąskim gardłem — to jest właściwa wymiana.

6.3 Serwery embeddingów

---

7. Przetwarzanie dokumentów i OCR

⭐ To jest kategoria, która dla Ciebie znaczy najwięcej — pracujesz z fakturami, umowami i skanami.

7.1 ⭐ Strategia dla faktur — hierarchia kosztu

1. PDF ma warstwę tekstową?         → PyMuPDF          (milisekundy, darmowe)
2. PDF to skan, układ typowy?       → Docling/Tesseract (sekundy)
3. Układ nietypowy, zdjęcie z ręki? → model VL (część 5) (dziesiątki sekund)

⚠️ Nie wysyłaj każdej faktury do modelu VL. To jest najdroższa opcja. Sprawdź najpierw, czy PDF nie ma już tekstu — połowa faktur, które dostajesz mailem, go ma.

# Szybki test: czy PDF ma warstwe tekstowa?
python3 -m venv $VENVS/dok
$VENVS/dok/bin/pip install pymupdf docling pdfplumber

$VENVS/dok/bin/python - <<'PYEOF'
import sys, fitz   # PyMuPDF
p = "/sciezka/do/faktura.pdf"
try:
    d = fitz.open(p)
    tekst = "".join(page.get_text() for page in d)
    if len(tekst.strip()) > 100:
        print(f"✅ PDF MA tekst ({len(tekst)} znaków) — użyj PyMuPDF, nie modelu VL")
        print(tekst[:400])
    else:
        print("⚠️ PDF to SKAN — potrzebny OCR albo model VL")
except Exception as e:
    print("błąd:", e)
PYEOF

# Docling: PDF -> Markdown ze struktura
sudo apt install -y tesseract-ocr tesseract-ocr-pol
$VENVS/dok/bin/python -c "
from docling.document_converter import DocumentConverter
r = DocumentConverter().convert('/sciezka/faktura.pdf')
print(r.document.export_to_markdown()[:1500])
"

⭐ Docling zachowuje tabele jako tabele Markdown. Dla faktur z pozycjami to jest ogromna różnica w porównaniu z płaskim OCR — model dostaje strukturę, nie sieczkę.

---

8. Mowa — STT i TTS

8.1 Rozpoznawanie mowy (STT)

8.2 Synteza mowy (TTS)

⭐ Dla polskiego: Piper. Działa na CPU, nie konkuruje o VRAM, ma naturalne głosy. XTTS v2 wtedy, gdy potrzebujesz konkretnego głosu (np. klonowanie własnego).

---

9. Frameworki agentowe

⚠️ Przeczytaj to po częściach 6–7, nie przed. Wtedy zobaczysz, że każdy z nich robi to, co Twój agent.py — i ocenisz, czy jego abstrakcje Ci pomagają, czy przeszkadzają.

9.1 Co realnie warto wziąć z tych frameworków

⭐ DSPy jest jedyną pozycją na tej liście, która robi coś, czego nie napisałeś sam. Zamiast ręcznie poprawiać prompt, definiujesz metrykę (masz ją — część 3 §6) i DSPy szuka lepszego promptu. To jest naturalna kontynuacja Twojego zestawu ewaluacyjnego.

---

10. Gotowi agenci kodujący

# Aider z Twoim lokalnym modelem
python3 -m venv $VENVS/aider
$VENVS/aider/bin/pip install aider-install && $VENVS/aider/bin/aider-install

cd ~/projekt
OPENAI_API_BASE=http://127.0.0.1:8081/v1 OPENAI_API_KEY=x \
  $VENVS/aider/bin/aider --model openai/gpt-oss-20b

⭐ Uruchom Aidera i porównaj z własnym agent.py. Zobacz, jak rozwiązał te same problemy: edycję plików, kontekst, zatwierdzanie. To jest najlepsza lekcja projektowa w tym rozdziale — i będzie zrozumiała tylko dlatego, że najpierw napisałeś swojego.

---

11. Obserwowalność

💡 Langfuse ma sens, gdy masz wielu użytkowników albo chcesz porównywać wersje promptów na wykresach. Dla jednego agenta Twój JSONL jest wygodniejszy — grep działa od razu.

---

12. Ewaluacja

⭐ Najbardziej niedoceniana kategoria w całym ekosystemie.

# promptfoo - porownaj trzy modele na tym samym zestawie
npm install -g promptfoo

cat > $KURS/promptfooconfig.yaml <<'EOF'
providers:
  - id: openai:chat:gpt-oss-20b
    config: { apiBaseUrl: http://127.0.0.1:8081/v1, apiKey: x }
  - id: openai:chat:qwen3-32b
    config: { apiBaseUrl: http://127.0.0.1:8082/v1, apiKey: x }

prompts:
  - "Wyciągnij z faktury numer, datę i kwotę brutto jako JSON:\n{{tekst}}"

tests:
  - vars:
      tekst: "FV/2025/01/0001 z 2025-01-10. Netto 1000 zł, VAT 23%, brutto 1230 zł."
    assert:
      - type: is-json
      - type: javascript
        value: JSON.parse(output).brutto === 1230
  - vars:
      tekst: "Rachunek A/12/2025 z 2025-06-30, zwolniony z VAT, 500,00 zł."
    assert:
      - type: is-json
      - type: contains
        value: "A/12/2025"
EOF

cd $KURS && promptfoo eval && promptfoo view

⭐ promptfoo view daje tabelę porównawczą w przeglądarce. To jest to samo, co Twój harness z części 3, ale z UI i wygodnym porównywaniem wielu modeli naraz. Warto — zwłaszcza gdy będziesz pokazywał wyniki klientowi.

---

13. Dostrajanie (fine-tuning)

⚠️ Realia dostrajania na RDNA4: PyTorch-ROCm wspiera gfx1201, ale ekosystem (bitsandbytes, flash-attention, xformers) jest nierówny. Spodziewaj się zachodu.

💡 Zanim zaczniesz dostrajać, przeczytaj część 8 §6.1 jeszcze raz. W 80 % przypadków odpowiedzią jest RAG (część 4) albo gramatyka (część 3), nie LoRA.

---

14. Kwantyzacja

💡 Zostań przy GGUF. Jest najlepiej wspierany na ROCm, masz do niego wszystkie narzędzia i cała Twoja metodyka pomiarowa jest na nim zbudowana.

---

15. Co wziąć na start

15.1 Trzy rzeczy do wzięcia od razu

15.2 Do przetestowania w drugiej kolejności

15.3 Świadomie odkładam na później

15.4 ⭐ Zasada, którą warto zapamiętać

Bierz narzędzie wtedy, gdy potrafisz opisać, czego dokładnie ono za Ciebie nie zrobi.

Po częściach 1–8 potrafisz to dla każdej pozycji w tym katalogu. To jest prawdziwy efekt tego kursu — nie to, że napisałeś własną bazę wektorową, tylko że wiesz, co kupujesz, biorąc cudzą.

---

Ćwiczenia

1. Docling na prawdziwej fakturze. Weź PDF faktury, przepuść przez Docling i porównaj z tym, co dał model VL z części 5. Zmierz czas i trafność. Który wygrał i w jakim typie dokumentu?
2. promptfoo na zestawie z części 3. Przenieś faktury.jsonl do konfiguracji promptfoo i porównaj trzy modele w UI.
3. mmlw vs bge-m3. Zmierz „margines" metodą z części 4 §2.4 na polskim tekście księgowym. Który lepiej rozdziela?
4. Aider vs Twój agent. To samo zadanie kodujące na tym samym modelu. Porównaj liczbę tur, jakość i to, co Aider robi inaczej. Zapisz trzy rzeczy, które od niego zapożyczysz.
5. Ustal swój stos. Napisz w HANDOFF.md jedną tabelę: warstwa → wybrane narzędzie → dlaczego → co odrzuciłeś. To jest dokument architektury Twojego produktu.

---

Następna część: 10-HYBRYDA-LOKALNY-PLUS-CLAUDE.md — krótki rozdział: kiedy i jak dołożyć Claude API do lokalnego stosu, nie tracąc kontroli nad prywatnością.