Langfuse, obserwowalnosc aplikacji LLM

Langfuse, czyli widok na to, co robi Twoja aplikacja LLM

Aplikacja oparta o model językowy psuje się inaczej niż zwykły backend. Nie rzuca wyjątku, tylko zwraca odpowiedź, która wygląda poprawnie i jest błędna. Langfuse zapisuje każde wywołanie razem z promptem, odpowiedzią, czasem i kosztem, więc pytanie „dlaczego to wyszło tak" przestaje być zgadywaniem.

Co dokładnie zapisuje

Podstawową jednostką jest ślad, czyli zapis jednego przebiegu od wejścia użytkownika do odpowiedzi. Wewnątrz śladu leżą kroki: wywołania modelu, zapytania do bazy wektorowej, wywołania narzędzi, przekształcenia danych.

Każdy krok niesie cztery informacje, które w praktyce wystarczają do diagnozy. Wejście, czyli dokładna treść promptu razem z kontekstem. Wyjście, czyli surowa odpowiedź przed Twoim przetworzeniem. Czas trwania, pozwalający wskazać, który etap spowalnia całość. Liczbę tokenów i koszt, wyliczony na podstawie modelu i stawek.

To ostatnie bywa najbardziej odkrywcze. Zespoły regularnie odkrywają, że osiemdziesiąt procent rachunku generuje jeden krok, o którym nikt nie myślał, na przykład streszczanie historii rozmowy uruchamiane przy każdym pytaniu.

Warto rozumieć, czym to się różni od zwykłego monitoringu aplikacji. Klasyczne narzędzia mierzą czas odpowiedzi, kody błędów i zużycie zasobów, czyli rzeczy, które przy modelu językowym wyglądają dobrze nawet wtedy, gdy odpowiedź jest błędna. Tutaj jednostką obserwacji jest treść, a nie status, i to przesunięcie decyduje o przydatności narzędzia.

Ślady da się grupować po sesji użytkownika i oznaczać własnymi etykietami, więc pytanie „co się dzieje u tego konkretnego klienta" ma odpowiedź, a nie tylko hipotezy.

Wdrożenie

Instrumentacja sprowadza się do dekoratora albo owinięcia klienta modelu.

pip install langfuse

LANGFUSE_PUBLIC_KEY=pk-lf-...
LANGFUSE_SECRET_KEY=sk-lf-...
LANGFUSE_HOST=https://cloud.langfuse.com

from langfuse import observe
from langfuse.openai import openai

@observe()
def odpowiedz_na_pytanie(pytanie: str) -> str:
    fragmenty = retriever.invoke(pytanie)
    wynik = openai.chat.completions.create(
        model="gpt-5-mini",
        messages=[{"role": "user", "content": zbuduj_prompt(pytanie, fragmenty)}],
    )
    return wynik.choices[0].message.content

Dekorator tworzy ślad, a podmieniony klient modelu automatycznie dopisuje do niego wywołanie razem z tokenami i kosztem. Przy LangChain i LlamaIndex działa to przez gotowe integracje, bez zmiany kodu poza dodaniem procedury obsługi.

Zapis odbywa się asynchronicznie, więc nie wydłuża odpowiedzi dla użytkownika. Warto natomiast pamiętać o wywołaniu opróżniającego bufor przy krótko żyjących procesach, na przykład w funkcjach bezserwerowych, bo inaczej ostatnie ślady nie zdążą dotrzeć.

Wersjonowanie promptów

Druga funkcja, dla której zespoły sięgają po to narzędzie, dotyczy promptów. Trzymanie ich w kodzie oznacza, że każda korekta wymaga wdrożenia, a osoba odpowiedzialna za treść musi prosić programistę o zmianę przecinka.

from langfuse import Langfuse

langfuse = Langfuse()
prompt = langfuse.get_prompt("klasyfikacja-zgloszen", label="production")
tresc = prompt.compile(zgloszenie=tekst)

Prompt ma wersje i etykiety, więc przełączenie produkcji na nową wersję to zmiana etykiety, a cofnięcie to ta sama operacja w drugą stronę. Ślady zapisują użytą wersję, dzięki czemu porównanie jakości przed i po nie opiera się na wspomnieniach.

Przy pobieraniu promptu z zewnętrznego źródła dołóż zabezpieczenie na wypadek niedostępności. Biblioteka trzyma ostatnią pobraną wersję w pamięci podręcznej, ale przy zimnym starcie procesu warto mieć zapasową treść w kodzie, żeby awaria narzędzia nie zatrzymała aplikacji.

Warto od razu ustalić zasadę: prompt w narzędziu jest źródłem prawdy, a w kodzie zostaje wyłącznie odwołanie po nazwie. Trzymanie kopii w obu miejscach kończy się rozjazdem, którego nikt nie zauważa do momentu, gdy wersje zaczynają się różnić.

Ewaluacja, czyli mierzenie jakości

Ślady mówią, co się wydarzyło. Ewaluacja odpowiada na pytanie, czy było dobrze, i bez niej każda dyskusja o poprawie jakości kończy się wymianą wrażeń.

Zestaw danych to lista przypadków z oczekiwanym wynikiem, przechowywana w narzędziu i uruchamiana po każdej zmianie promptu albo modelu. Trzydzieści realnych przypadków wystarcza, żeby zauważyć regresję.

Oceny można nadawać na trzy sposoby i każdy ma inne zastosowanie. Ręcznie w interfejsie, co sprawdza się przy pierwszych kilkudziesięciu przypadkach i buduje intuicję. Automatycznie funkcją porównującą wynik z oczekiwanym, co działa przy zadaniach o jednoznacznej odpowiedzi. Modelem oceniającym, gdy poprawność jest kwestią stopnia, na przykład przy streszczeniach.

Osobno warto zbierać oceny od użytkowników. Kciuk w górę i w dół obok odpowiedzi kosztuje godzinę pracy, a daje sygnał z prawdziwego użycia, którego żaden zestaw testowy nie zastąpi.

Cennik i self hosting

Projekt jest na licencji MIT, a w czerwcu 2025 roku wszystkie funkcje produktowe, łącznie ze śledzeniem, promptami i ewaluacjami, trafiły pod tę licencję. Wersja uruchomiona u siebie nie ma limitu zdarzeń ani użytkowników.

Dwie rzeczy odróżniają ten cennik od konkurencji. Plany zawierają nielimitowaną liczbę użytkowników, więc koszt nie rośnie z wielkością zespołu. Plan darmowy ma natomiast twardy limit bez rozliczania nadwyżki, co oznacza, że po jego wyczerpaniu śledzenie po prostu się zatrzymuje, zamiast generować rachunek.

Jednostka rozliczeniowa liczy zdarzenia, a nie wywołania modelu, więc ślad z pięcioma krokami zużywa ich więcej niż pojedyncze wywołanie. Przy szacowaniu planu policz to na realnym przebiegu swojej aplikacji, bo różnica między prostym zapytaniem a agentem z narzędziami bywa dziesięciokrotna.

Self hosting jest realną opcją, ale nie darmową. Do kosztu maszyny dolicz bazę zdarzeń, która przy dużym wolumenie potrafi urosnąć, oraz czas na aktualizacje i kopie zapasowe. Przy jednym projekcie i umiarkowanym ruchu chmura wychodzi taniej, przy danych, które nie mogą opuścić firmy, wybór jest rozstrzygnięty niezależnie od rachunku.

Jak czytać ślady przy diagnozowaniu

Zebrane dane są warte tyle, ile umiejętność ich czytania. Trzy pytania prowadzą do przyczyny szybciej niż przeglądanie wszystkiego po kolei.

Pierwsze: czy model dostał właściwy kontekst. Otwórz krok pobierania fragmentów i przeczytaj, co faktycznie trafiło do promptu. Jeśli właściwej informacji tam nie ma, problem leży w wyszukiwaniu i żadna zmiana promptu tego nie naprawi. To najczęstsza przyczyna błędnych odpowiedzi w systemach opartych o dokumenty, a jednocześnie ta, której szuka się najrzadziej.

Drugie: czy model zignorował kontekst, który dostał. Jeśli właściwy fragment był w promptcie, a odpowiedź go pomija albo mu przeczy, problem leży w instrukcji. Tu pomaga polecenie odpowiadania wyłącznie na podstawie podanych fragmentów oraz przyznawania się do braku danych.

Trzecie: gdzie poszedł czas. Ślad pokazuje czas każdego kroku, więc wąskie gardło widać od razu. Zaskoczeniem bywa, że to nie model, tylko zapytanie do bazy albo wywołanie zewnętrznego API czekające na odpowiedź.

Przy agentach dochodzi czwarte pytanie: ile obrotów wykonała pętla. Ślad z dwudziestoma wywołaniami modelu na jedno pytanie użytkownika to zwykle znak, że agent krąży, a nie że zadanie było trudne. Limit obrotów i przegląd takiego śladu rozwiązują większość przypadków.

Warto wyrobić nawyk zaglądania do śladów przy każdym zgłoszeniu od użytkownika, zamiast odtwarzać problem u siebie. Odtwarzanie zajmuje pół godziny i często się nie udaje, a ślad z produkcji pokazuje dokładnie to, co się wydarzyło.

Langfuse kontra alternatywy

Ostatni wiersz zasługuje na uwagę, bo bywa niedoceniany. Zapisywanie promptu i odpowiedzi do własnej bazy to godzina pracy. Narzędzie zaczyna się opłacać, gdy potrzebujesz porównywać wersje promptów, liczyć koszt po użytkowniku i przeglądać ślady wielokrokowe.

Poza tabelą stoi jeszcze kategoria narzędzi działających jako pośrednik: zamiast dekoratorów podmieniasz adres bazowy klienta modelu i zapisy powstają same, bez dotykania kodu aplikacji. Tak działa Helicone, tyle że po przejęciu przez Mintlify w marcu 2026 produkt jest w trybie utrzymania i nowych funkcji nie dostanie, więc do nowego projektu wchodzi w grę najwyżej wersja uruchamiana u siebie na licencji Apache 2.0.

Kontrola kosztów w praktyce

Rachunek za model rośnie cicho i zwykle odkrywa się to na fakturze. Ślady z wyliczonym kosztem pozwalają zamienić to w liczbę, którą da się obserwować.

Zacznij od podziału kosztu na kroki. Ślad pokazuje, ile kosztowało wyszukiwanie, ile generowanie odpowiedzi, ile ewentualne streszczanie historii. W większości aplikacji jeden krok odpowiada za lwią część rachunku i zwykle jest to inny krok, niż podpowiada intuicja.

Potem policz koszt na użytkownika i na sesję. Etykiety w śladach pozwalają grupować dane, więc odpowiedź na pytanie „ilu mamy użytkowników generujących połowę rachunku" zajmuje minutę. Ta liczba bywa istotna przy ustalaniu cennika produktu, bo pokazuje, gdzie leży realny koszt obsługi.

Trzecim krokiem jest obserwacja zmian w czasie. Rachunek rosnący szybciej niż liczba użytkowników oznacza, że coś się wydłużyło: historia rozmowy, kontekst pobierany do promptu albo liczba obrotów agenta. Bez zapisu wcześniejszego stanu ta zmiana pozostaje niewidoczna do momentu, gdy staje się bolesna.

Osobno warto ustawić alarm na nietypowe przebiegi. Ślad, który kosztował dziesięć razy więcej niż mediana, zwykle oznacza pętlę, wyjątkowo długi dokument albo użytkownika testującego granice systemu. Każdy z tych przypadków warto zobaczyć od razu, a nie po miesiącu.

Wreszcie zapisuj koszt razem z oceną jakości. Bez tego zestawienia optymalizacja kosztu bywa cofaniem się w jakości, którego nikt nie zauważa, bo mierzy tylko jedną stronę równania.

Typowe błędy

Pierwszy to instrumentowanie wyłącznie wywołań modelu. Największą wartość daje zapis całego przebiegu, bo w systemach opartych o wyszukiwanie źródłem błędu zwykle jest krok pobierania fragmentów, a nie sam model.

Drugi to zapisywanie danych osobowych bez zastanowienia. Ślady zawierają pełne prompty, a te zawierają to, co wpisał użytkownik. Ustal, co maskujesz, zanim narzędzie trafi na produkcję.

Trzeci to brak ustawienia retencji. Historia rośnie razem z ruchem, a przy self hostingu przekłada się to wprost na rozmiar bazy i koszt jej utrzymania.

Czwarty to zbieranie śladów bez zestawu testowego. Wgląd w to, co się dzieje, nie odpowiada na pytanie, czy zmiana promptu poprawiła jakość. To dwie różne warstwy i obie są potrzebne.

Piąty to pomijanie opróżnienia bufora w środowiskach krótko żyjących. Funkcja bezserwerowa kończy się szybciej, niż ślad zdąży dotrzeć, więc w danych pojawiają się luki, których nikt nie potrafi wyjaśnić.

FAQ

Czy Langfuse jest darmowy?

Wersja uruchomiona na własnym serwerze jest darmowa na licencji MIT, bez limitu zdarzeń i użytkowników, płacisz tylko za infrastrukturę. Chmura ma darmowy plan z 50 tysiącami jednostek miesięcznie, a plan Core kosztuje 29 USD za 100 tysięcy jednostek i nielimitowaną liczbę osób w zespole.

Langfuse czy LangSmith?

Langfuse wybierasz, gdy zależy Ci na wersji lokalnej, licencji otwartej albo rozliczeniu niezależnym od liczby osób w zespole. LangSmith ma głębszą integrację z ekosystemem LangChain i dojrzalszy interfejs, więc lepiej pasuje do projektów opartych wyłącznie o ten framework.

Czy śledzenie spowalnia aplikację?

Nie w zauważalny sposób, bo zapis odbywa się asynchronicznie w tle. Wyjątkiem są środowiska krótko żyjące, gdzie proces kończy się przed wysłaniem danych, dlatego w funkcjach bezserwerowych trzeba jawnie opróżnić bufor przed zakończeniem.

Czy działa z modelami innymi niż OpenAI?

Tak, obsługuje modele różnych dostawców, w tym Claude i modele lokalne. Koszt jest wyliczany na podstawie modelu i stawek, więc przy modelu uruchomionym u siebie zobaczysz zużycie tokenów, a wycenę ustawisz sam albo pominiesz.

Od czego zacząć przy istniejącej aplikacji?

Od instrumentacji jednej ścieżki, najlepiej tej, która sprawia najwięcej problemów. Po tygodniu zbierania śladów zwykle widać, gdzie leży koszt i gdzie powstają błędne odpowiedzi, a dopiero wtedy warto rozszerzać zakres i dokładać zestaw testowy.

Dokumentacja stoi na langfuse.com, a kod źródłowy w repozytorium na GitHubie.