LangSmith, ślady i oceny aplikacji z LLM

LangSmith, czyli koniec zgadywania, co zrobił model

Aplikacja z modelem językowym psuje się inaczej niż zwykły kod. Nie ma wyjątku ani błędnego statusu, jest odpowiedź, która wygląda poprawnie i jest zła. Bez zapisu tego, co poszło do modelu i co wróciło, diagnoza sprowadza się do odtwarzania sytuacji na ślepo.

LangSmith zapisuje ten przebieg: każde wywołanie modelu, każde wywołanie narzędzia, zużyte tokeny, czas i wynik. Do tego dokłada warstwę ocen, czyli sposób sprawdzania, czy zmiana promptu poprawiła działanie, czy tylko przesunęła problem gdzie indziej.

Ślady wywołań

Ślad to drzewo tego, co wydarzyło się przy obsłudze jednego zapytania. Widzisz kolejne kroki, ich argumenty i wyniki, więc pytanie „dlaczego agent odpowiedział w ten sposób" przestaje być zagadką.

pip install langsmith
export LANGSMITH_TRACING=true
export LANGSMITH_API_KEY=...

Przy pracy z LangChainem albo LangGraphem nie trzeba nic więcej, bo ślady zbierane są automatycznie. We własnym kodzie oznaczasz funkcje dekoratorem.

from langsmith import traceable

@traceable
def odpowiedz_na_pytanie(pytanie: str, user_id: str) -> str:
    fragmenty = wyszukaj(pytanie)
    return wywolaj_model(pytanie, fragmenty)

Zagnieżdżone wywołania funkcji oznaczonych w ten sam sposób tworzą drzewo, więc widzisz, ile czasu zajęło wyszukiwanie, a ile samo generowanie. To rozstrzyga częsty spór o to, gdzie leży opóźnienie.

Warto od razu dodać metadane, bo bez nich ślad jest tylko zapisem, a nie danymi do analizy. Identyfikator użytkownika, wersja promptu, nazwa modelu i typ zapytania pozwalają potem filtrować i porównywać.

@traceable(metadata={"wersja_promptu": "v3", "typ": "wsparcie"})
def odpowiedz_na_pytanie(pytanie: str) -> str:
    ...

Zestawy testowe i oceny

To druga połowa narzędzia i ta, którą pomija się najczęściej. Zmiana promptu, która subiektywnie poprawia jedną odpowiedź, zwykle psuje trzy inne, a bez zestawu przypadków nikt tego nie zauważy.

Zestaw to zbiór przykładów z oczekiwanym wynikiem. Buduje się go najprościej ze śladów: sytuacje, w których aplikacja zawiodła, dopisujesz do zestawu jednym kliknięciem i od tej chwili każda zmiana jest na nich sprawdzana.

from langsmith import evaluate

def poprawnosc(wyjscie: dict, oczekiwane: dict) -> bool:
    return wyjscie["kategoria"] == oczekiwane["kategoria"]

wyniki = evaluate(
    lambda wejscie: klasyfikuj(wejscie["tresc"]),
    data="zgloszenia-testowe",
    evaluators=[poprawnosc],
    experiment_prefix="prompt-v4",
)

Oceny dzielą się na trzy rodzaje i warto je rozróżniać. Ocena deterministyczna porównuje wynik z oczekiwaniem i jest tania oraz szybka. Ocena modelem w roli sędziego sprawdza rzeczy, których nie da się porównać wprost, jak ton odpowiedzi albo trzymanie się faktów, i kosztuje tokeny. Ocena ludzka jest najdroższa i najbardziej wiarygodna, więc rezerwuje się ją do próbek.

Praktyczna rada: zacznij od trzydziestu przypadków i oceny deterministycznej. To wystarczy, żeby wychwycić regresję, a rozbudowywanie zestawu ma sens dopiero wtedy, gdy zaczyna przepuszczać błędy.

Koszty i opóźnienia

Ślady zawierają liczbę tokenów i czas, więc narzędzie pokazuje, ile faktycznie kosztuje obsługa jednego zapytania. Ta liczba bywa zaskakująca, zwłaszcza przy agentach.

Trzy rzeczy widać dopiero po włączeniu śladów. Pierwsza to ponowienia: agent, który dwa razy poprawia odpowiedź niezgodną ze schematem, zużywa trzy razy więcej tokenów, niż wynika z pojedynczego wywołania. Druga to rozrost kontekstu, gdy historia rozmowy rośnie i przy setnej wiadomości wejście kosztuje więcej niż wyjście. Trzecia to wywołania zbędne, na przykład wyszukiwanie uruchamiane przy pytaniach, które go nie wymagają.

Filtrowanie po metadanych pozwala odpowiedzieć na pytania, które inaczej wymagałyby własnej analityki: który typ zapytań kosztuje najwięcej, czy nowa wersja promptu skróciła czas odpowiedzi, którzy użytkownicy generują największe zużycie.

Ocena modelem w roli sędziego

To najczęściej używana i najczęściej źle używana część warstwy ocen. Idea polega na tym, że jeden model ocenia odpowiedź drugiego według zadanego kryterium.

from langsmith import evaluate
from langsmith.evaluation import LangChainStringEvaluator

trzymanie_sie_zrodel = LangChainStringEvaluator(
    "labeled_score_string",
    config={
        "criteria": {
            "oparcie": "Czy odpowiedz opiera sie wylacznie na podanych fragmentach?"
        },
        "normalize_by": 10,
    },
)

Trzy zasady oddzielają ocenę użyteczną od kosztownego szumu. Pierwsza to jedno kryterium na jednego sędziego: pytanie „czy odpowiedź jest dobra" daje wyniki, których nie da się porównać między przebiegami, a pytanie „czy odpowiedź opiera się wyłącznie na podanych fragmentach" tak.

Druga to skala binarna albo trzystopniowa zamiast oceny w skali dziesięciopunktowej. Model nie odróżnia siódemki od ósemki w sposób powtarzalny, więc precyzja jest pozorna.

Trzecia to sprawdzenie sędziego na próbce ocenionej przez człowieka. Jeśli sędzia zgadza się z człowiekiem w siedemdziesięciu procentach przypadków, jego wyniki wciąż niosą informację, ale różnica dwóch punktów procentowych między wersjami promptu nic nie znaczy.

Do zastosowań, w których liczy się poprawność faktyczna, lepiej sprawdza się porównanie z odpowiedzią wzorcową niż ocena swobodna. Wymaga to przygotowania wzorców, co jest pracą, ale daje wynik, na którym można oprzeć decyzję.

Zbieranie opinii od użytkowników

Ocena automatyczna mierzy to, co potrafisz opisać, a użytkownik widzi rzeczy, których nie przewidziałeś. Narzędzie pozwala dopisać ocenę do konkretnego śladu z poziomu aplikacji.

from langsmith import Client

klient = Client()

klient.create_feedback(
    run_id=id_sladu,
    key="pomocna",
    score=1,
    comment="Uzytkownik kliknal kciuk w gore",
)

Identyfikator śladu trzeba przekazać do interfejsu razem z odpowiedzią, żeby dało się go potem powiązać z kliknięciem. To drobiazg implementacyjny, który przesądza o tym, czy opinie w ogóle da się zebrać.

Wartość tego mechanizmu leży nie w samej statystyce zadowolenia, tylko w tym, że oznaczone negatywnie ślady tworzą naturalną kolejkę do przeglądu. Z niej powstaje zestaw testowy, a z zestawu testowego kolejna poprawka. To zamyka pętlę między produkcją a rozwojem.

Prompty i wersjonowanie

Narzędzie przechowuje prompty jako obiekty z historią zmian, więc można je edytować poza kodem i podglądać, jak wersja wpływa na wyniki.

To rozwiązanie ma zaletę i pułapkę. Zaletą jest możliwość poprawiania promptu przez osobę nietechniczną bez wdrożenia nowej wersji aplikacji. Pułapką jest utrata powiązania między kodem a promptem: aplikacja pobiera prompt z zewnątrz, więc odtworzenie zachowania sprzed tygodnia wymaga sprawdzenia, która wersja wtedy obowiązywała.

Rozsądny kompromis polega na przypinaniu wersji promptu w kodzie produkcyjnym i pozostawieniu swobodnej edycji tylko w środowisku testowym. Wtedy wdrożenie nowego promptu jest świadomą decyzją, a nie efektem ubocznym cudzej edycji.

Ceny

Poza abonamentem rozliczane jest samo zbieranie śladów, przy czym kluczowa jest retencja. Ślad przechowywany krótko kosztuje wyraźnie mniej niż ślad przechowywany długo, a narzędzie automatycznie przedłuża retencję śladom, do których ktoś dodał ocenę.

Sposób naliczania został ostatnio przebudowany w kierunku znormalizowanych jednostek, więc przed policzeniem budżetu sprawdź aktualny cennik u źródła zamiast opierać się na stawkach z artykułów.

Praktyczna oszczędność polega na próbkowaniu. W środowisku produkcyjnym rzadko potrzebujesz śladu każdego zapytania: dziesięć procent ruchu plus wszystkie przypadki zakończone błędem daje pełny obraz przy ułamku kosztu.

Testy w potoku ciągłej integracji

Oceny da się uruchamiać nie tylko ręcznie, ale też jako część procesu budowania, tak samo jak zwykłe testy. To zamienia jakość odpowiedzi z rzeczy sprawdzanej okazjonalnie w rzecz sprawdzaną przy każdej zmianie.

import pytest
from langsmith import testing as t

@pytest.mark.langsmith
def test_klasyfikacja_pilnych_zgloszen():
    wejscie = "Nie moge sie zalogowac od wczoraj, pilne"
    t.log_inputs({"tresc": wejscie})

    wynik = klasyfikuj(wejscie)
    t.log_outputs(wynik)

    assert wynik["priorytet"] >= 4

Wyniki trafiają do narzędzia, więc porównanie między gałęziami jest dostępne w interfejsie, a nie tylko w logach z budowania. Przy zmianie promptu widzisz od razu, które przypadki przestały przechodzić.

Praktyczna uwaga dotyczy kosztu i czasu. Pełny zestaw stu przypadków przy każdym zapisie kodu to wolne testy i zauważalny rachunek, więc rozsądny podział wygląda tak: dziesięć przypadków szybkich przy każdej zmianie i pełny zestaw raz dziennie albo przed wydaniem.

Druga uwaga dotyczy niedeterminizmu. Test na modelu potrafi przejść cztery razy i nie przejść za piątym, więc próg zaliczenia lepiej ustawiać na poziomie zestawu, na przykład wymagając osiemdziesięciu procent przechodzących przypadków, niż na poziomie pojedynczego wywołania.

LangSmith kontra alternatywy

Ostatni wiersz bywa niesłusznie pomijany. Przy aplikacji z jednym wywołaniem modelu zapisanie promptu, odpowiedzi i zużycia tokenów do własnej tabeli zajmuje pół godziny i wystarcza. Osobne narzędzie zaczyna się opłacać, gdy pojawia się drzewo wywołań albo potrzeba porównywania wersji.

Granica przebiega mniej więcej tam, gdzie kończy się jedno wywołanie, a zaczyna sekwencja. Przy trzech krokach z wywołaniami narzędzi własne logowanie zamienia się w pisanie własnego narzędzia obserwacyjnego, co jest pracą, której nikt nie planował.

Z tabeli wypada jeszcze jedno podejście: zbieranie danych przez pośrednika, czyli podmianę adresu bazowego klienta modelu zamiast dekoratorów w kodzie. Tak działa Helicone i przy zastanym projekcie, którego kodu nie chcesz ruszać, jest to najszybsza droga do liczb o kosztach. Ma dwa ograniczenia. Pośrednik widzi pojedyncze wywołania, a nie drzewo kroków, więc przy agencie traci sens dokładnie tam, gdzie zaczyna być potrzebny. Do tego sam produkt po przejęciu przez Mintlify w marcu 2026 roku przeszedł w tryb utrzymania, więc nowych funkcji nie dostanie i do nowego projektu nie warto się nim wiązać.

Dane wrażliwe w śladach

Ślad zawiera dokładnie to, co użytkownik wpisał, oraz to, co model odpowiedział. Przy asystencie obsługi klienta znaczy to nazwiska, adresy, numery zamówień, a czasem dane, których nikt się nie spodziewał.

Trzy mechanizmy pozwalają sobie z tym poradzić. Pierwszy to maskowanie po stronie aplikacji, jeszcze przed wysłaniem śladu: wzorce wykrywające numery kart, adresy i identyfikatory zamieniasz na znaczniki. To rozwiązanie najpewniejsze, bo dane nie opuszczają Twojego środowiska.

Drugi to ograniczenie tego, co w ogóle trafia do śladu. Nie każde wywołanie musi zapisywać pełną treść, a sama struktura wywołań z metadanymi wystarcza do diagnozowania większości problemów z opóźnieniem i kosztem.

Trzeci to wdrożenie we własnej infrastrukturze, dostępne w planie dla dużych organizacji. Wtedy pytanie o transfer danych przestaje istnieć, ale wiąże się z kosztem i z obowiązkiem utrzymania.

Warto ustalić to na początku, a nie po pierwszym audycie. Ślady zebrane bez maskowania zostają w systemie i usunięcie ich wstecz bywa trudniejsze niż ustawienie reguł od razu.

Typowe błędy

Pierwszy to ślady bez metadanych. Zapis wywołania bez informacji o wersji promptu, modelu i typie zapytania jest ciekawy pojedynczo i bezużyteczny w analizie.

Drugi to zbieranie śladów bez zestawu testowego. Widzisz wtedy, że coś działa źle, ale nie wiesz, czy poprawka pomogła, dopóki nie zbierzesz kolejnych danych z produkcji.

Trzeci to ocena modelem sędziowskim tam, gdzie wystarczy porównanie wartości. Sędzia kosztuje tokeny i wprowadza własny szum, więc rezerwuj go do rzeczy, których nie da się sprawdzić prościej.

Czwarty to zbieranie stu procent ruchu na produkcji. Przy dużym wolumenie rachunek za obserwowalność potrafi przewyższyć rachunek za sam model, a próbkowanie daje ten sam obraz.

Piąty to zapisywanie treści rozmów bez sprawdzenia wymogów. Ślady zawierają dane wprowadzone przez użytkownika, więc przy danych wrażliwych trzeba je maskować albo wybrać wdrożenie we własnej infrastrukturze.

Szósty to swobodna edycja promptów produkcyjnych. Bez przypięcia wersji zachowanie aplikacji zmienia się bez wdrożenia, a odtworzenie stanu sprzed tygodnia staje się śledztwem.

FAQ

Czy LangSmith działa tylko z LangChainem?

Nie. Integracja z LangChainem i LangGraphem jest automatyczna, ale własny kod oznaczasz dekoratorem i działa tak samo. Można go używać z dowolnym dostawcą modelu i bez żadnej biblioteki agentowej.

Ile kosztuje LangSmith?

Plan dla jednej osoby jest darmowy i obejmuje kilka tysięcy śladów miesięcznie. Plan zespołowy kosztuje trzydzieści dziewięć dolarów za miejsce, do dziesięciu osób. Poza tym rozliczane jest zbieranie śladów, z niższą stawką przy krótkiej retencji. Sposób naliczania był ostatnio zmieniany, więc sprawdź aktualny cennik.

LangSmith czy Langfuse?

Langfuse wybierzesz, gdy potrzebujesz otwartego źródła i wdrożenia we własnej infrastrukturze bez negocjacji. LangSmith wybierzesz, gdy pracujesz w tym ekosystemie i chcesz ślady oraz oceny w jednym narzędziu, bez składania tego z części.

Czy da się wdrożyć we własnej infrastrukturze?

Tak, ale w planie dla dużych organizacji. Przy wymogu, żeby treść rozmów nie opuszczała firmy, i przy braku budżetu na taki plan, właściwym wyborem jest narzędzie otwarte.

Od czego zacząć?

Od włączenia śladów w środowisku testowym i przejrzenia dziesięciu prawdziwych przebiegów. Zwykle wychodzą z tego dwie rzeczy: krok zabierający najwięcej czasu i wywołanie, którego nikt się nie spodziewał. Dopiero potem buduj zestaw testowy z przypadków, które zawiodły.

Dokumentacja stoi na stronie projektu, a aktualne progi cenowe na stronie cennika.