Ragas, pomiar jakości wyszukiwania i odpowiedzi

Ragas, czyli skąd wiadomo, że wyszukiwanie działa

System odpowiadający na pytania z własnych dokumentów psuje się na dwa różne sposoby, a z zewnątrz wygląda to tak samo. Albo wyszukiwanie nie znalazło właściwego fragmentu, albo znalazło, a model i tak odpowiedział po swojemu. Poprawka na jedno nie pomaga na drugie, więc bez rozdzielenia tych przypadków strojenie jest zgadywaniem.

Ragas rozdziela je czterema miarami: dwie oceniają wyszukiwanie, dwie odpowiedź. To biblioteka otwarta, która ustaliła słownik używany dziś w całej tej kategorii narzędzi.

Cztery metryki i co mówią

Rozdzielenie na dwie pary jest sednem. Jeśli pokrycie kontekstu jest niskie, żadna zmiana promptu nie pomoże, bo właściwej informacji po prostu nie ma w tym, co dostał model. Jeśli wierność jest niska przy wysokim pokryciu, problem leży w prompcie albo w modelu, a nie w bazie wektorowej.

Ta jedna obserwacja oszczędza najwięcej czasu. Zespoły zwykle zaczynają od poprawiania promptu, bo to najłatwiejsze, podczas gdy w większości wdrożeń zawodzi etap wyszukiwania, a dokładniej sposób cięcia dokumentów na fragmenty.

Stan projektu

Zanim wpiszesz to do zależności, sprawdź tempo rozwoju, bo w ostatnich miesiącach wyraźnie zwolniło.

Biblioteka nie została wycofana ani zarchiwizowana, dokumentacja działa, licencja Apache 2.0 pozostaje bez zmian. Ostatnie wydanie ma jednak numer 0.4.3 i pochodzi ze stycznia 2026 roku, a ostatnia zmiana w repozytorium z lutego tego samego roku, przy czym zgłoszenia i propozycje zmian od społeczności nadal napływają i czekają nierozpatrzone. Zmieniła się też nazwa firmy prowadzącej projekt, z Exploding Gradients na Vibrant Labs, więc dawny adres repozytorium tylko przekierowuje, a odnośniki w starszych materiałach prowadzą do nieaktualnej ścieżki.

Praktyczny wniosek jest dwuczęściowy. Same metryki i sposób ich liczenia są ustabilizowane, więc do pomiaru biblioteka nadaje się dziś tak samo dobrze jak wcześniej i nic w opisanych niżej wynikach się nie zmienia. Nie licz natomiast na szybką reakcję przy błędzie ani na wsparcie dla świeżo wydanych modeli, a przed związaniem się z tą biblioteką na dłużej sprawdź datę ostatniego wydania, bo od tego zależy, czy nadal jest to wybór aktualny.

Pierwszy pomiar

pip install ragas

from ragas import evaluate, EvaluationDataset
from ragas.metrics import (
    Faithfulness, AnswerRelevancy, LLMContextPrecisionWithReference, LLMContextRecall
)

dane = EvaluationDataset.from_list([
    {
        "user_input": "Jak pobrac duplikat faktury?",
        "retrieved_contexts": ["Duplikaty faktur pobierasz w panelu rozliczen...", "..."],
        "response": "Duplikat pobierzesz w panelu rozliczen, sekcja Historia platnosci.",
        "reference": "Duplikat faktury jest dostepny w panelu rozliczen.",
    },
])

wynik = evaluate(
    dataset=dane,
    metrics=[Faithfulness(), AnswerRelevancy(),
             LLMContextPrecisionWithReference(), LLMContextRecall()],
)
print(wynik)

Cztery pola opisują jeden przypadek: pytanie, fragmenty pobrane przez wyszukiwanie, odpowiedź systemu i odpowiedź wzorcowa. Ostatnie pole jest potrzebne tylko części metryk, ale to właśnie ono daje najbardziej wiarygodne wyniki.

Ocena odbywa się modelem językowym, więc każdy przypadek to kilka wywołań. Przy stu przypadkach i czterech metrykach idzie kilkaset wywołań, a to trzeba policzyć przed uruchomieniem, zwłaszcza przy modelu z górnej półki cenowej.

Jak czytać wyniki

Wyniki mieszczą się w zakresie od zera do jedynki i kuszą, żeby traktować je jak ocenę szkolną. To błąd, bo wartość bezwzględna znaczy mniej niż różnica między przebiegami.

Przy wierności wartość powyżej mniej więcej osiemdziesięciu pięciu setnych oznacza, że odpowiedzi trzymają się kontekstu. Wynik poniżej siedemdziesięciu setnych sygnalizuje, że model regularnie dokłada rzeczy, których w kontekście nie było, i to wymaga reakcji, a nie dalszego strojenia.

Przy metrykach kontekstu progi zależą od zadania. System odpowiadający na pytania proste może mieć wysoką precyzję i wystarczające pokrycie przy trzech fragmentach. System odpowiadający na pytania wymagające połączenia informacji z dwóch dokumentów będzie miał niższe pokrycie i to bywa naturalne, a nie błędne.

Praktyczna zasada: zapisz wynik pierwszego pomiaru jako punkt odniesienia i porównuj do niego kolejne. Pytanie „czy zmiana pomogła" jest odpowiadalne, a pytanie „czy nasz system jest dobry" nie, bo nie ma skali wspólnej dla różnych dziedzin.

Generowanie zestawu testowego

Największą przeszkodą jest zwykle brak przypadków z odpowiedziami wzorcowymi. Biblioteka potrafi wygenerować je z Twoich dokumentów, co przyspiesza start.

from ragas.testset import TestsetGenerator

generator = TestsetGenerator.from_langchain(llm=model, embedding_model=osadzenia)
zestaw = generator.generate_with_langchain_docs(dokumenty, testset_size=50)

Wygenerowane pytania trzeba przejrzeć, a nie przyjąć bez sprawdzenia. Automat układa pytania pod dokumenty, więc bywają zbyt bliskie treści i nie przypominają tego, co pisze prawdziwy użytkownik: skrótowo, z literówkami i czasem o dwóch rzeczach naraz.

Rozsądny układ to zestaw mieszany. Połowa przypadków wygenerowana z dokumentów, żeby pokryć zakres treści, i połowa wzięta z prawdziwych zapytań, żeby pokryć sposób, w jaki ludzie pytają. Ta druga połowa wykrywa więcej problemów.

Warto też zadbać o przypadki, na które system nie powinien odpowiadać. Pytanie spoza zakresu dokumentacji jest dobrym testem, bo poprawną odpowiedzią jest przyznanie się do braku informacji, a nie wymyślona treść. Takich przypadków warto mieć kilka na każdych dwadzieścia zwykłych.

Koszty i próbkowanie

Ocena modelem językowym kosztuje, więc pełny zestaw uruchamiany przy każdej zmianie kodu jest nierealny finansowo.

Trzy rzeczy obniżają ten koszt. Pierwsza to tańszy model do oceny, przy czym trzeba sprawdzić, czy jego wyniki korelują z wynikami mocniejszego na próbce. Druga to wybór metryk: precyzja kontekstu jest tania, a wierność wymaga rozbicia odpowiedzi na twierdzenia i sprawdzenia każdego, więc kosztuje najwięcej. Trzecia to podział na zestaw mały uruchamiany często i pełny uruchamiany przed wydaniem.

Warto też pamiętać, że ocena modelem ma własny szum. Ten sam przypadek oceniony dwa razy może dać nieco inny wynik, więc różnica dwóch setnych między przebiegami nie znaczy nic. Dopiero różnice rzędu pięciu setnych na kilkudziesięciu przypadkach są sygnałem.

Co zrobić z wynikiem

Diagnoza sprowadza się do prostego drzewa decyzyjnego i to jest największa praktyczna wartość tego narzędzia.

Niskie pokrycie kontekstu znaczy, że wyszukiwanie nie znalazło potrzebnej informacji. Sprawdź kolejno: czy fragment w ogóle jest w indeksie, czy sposób cięcia dokumentów nie rozbił go na pół, czy model osadzeń radzi sobie z Twoim językiem i czy zwracasz wystarczającą liczbę fragmentów.

Niska precyzja kontekstu przy dobrym pokryciu znaczy, że wśród wyników jest dużo szumu. Pomaga filtrowanie po metadanych, wyszukiwanie mieszane łączące wektory z wyszukiwaniem słownym oraz zmiana kolejności wyników osobnym modelem.

Niska wierność przy dobrym kontekście to problem po stronie generowania. Instrukcja powinna wprost mówić, że odpowiedź ma opierać się wyłącznie na podanych fragmentach, a przy braku informacji trzeba to przyznać. Czasem pomaga też ograniczenie liczby fragmentów, bo model gubi się przy dwudziestu, a radzi sobie przy pięciu.

Niska trafność odpowiedzi przy dobrej wierności zwykle oznacza, że model odpowiada na inne pytanie niż zadane. To bywa skutkiem przetwarzania pytania przed wyszukiwaniem albo instrukcji zachęcającej do rozbudowanych odpowiedzi.

Warto przejść to drzewo w tej kolejności, a nie zaczynać od tego, co najłatwiej zmienić. Poprawianie promptu przy niskim pokryciu kontekstu nie daje nic, a zajmuje popołudnie i zostawia wrażenie, że problem jest nierozwiązywalny.

Jak liczone są metryki

Warto wiedzieć, co dzieje się pod spodem, bo to tłumaczy zarówno koszt, jak i ograniczenia tych miar.

Wierność powstaje w dwóch krokach. Najpierw model rozbija odpowiedź na pojedyncze twierdzenia, potem sprawdza każde z osobna wobec podanego kontekstu. Wynik to udział twierdzeń mających pokrycie. Stąd bierze się koszt: odpowiedź z ośmioma twierdzeniami to dziewięć wywołań zamiast jednego.

Trafność odpowiedzi liczy się odwrotnie. Model generuje pytania, na które ta odpowiedź byłaby dobrą odpowiedzią, a następnie porównuje je z pytaniem rzeczywistym przez podobieństwo osadzeń. Konsekwencja praktyczna jest taka, że odpowiedź rozwlekła, dorzucająca informacje spoza pytania, obniża tę miarę nawet gdy jest poprawna.

Pokrycie kontekstu wymaga odpowiedzi wzorcowej, bo sprawdza, czy każde zdanie wzorca da się przypisać do pobranego fragmentu. Bez wzorca ta miara nie ma odniesienia i trzeba sięgnąć po wariant przybliżony, mniej wiarygodny.

Precyzja kontekstu ocenia każdy pobrany fragment osobno pod kątem tego, czy pomaga odpowiedzieć, z uwzględnieniem kolejności. Fragment trafny na pierwszej pozycji podnosi wynik bardziej niż ten sam fragment na dziesiątej, co odpowiada temu, jak model faktycznie czyta kontekst.

Pomiar na produkcji

Zestaw testowy pokazuje, jak system radzi sobie z przypadkami, które przewidziałeś. Produkcja pokazuje przypadki, których nie przewidziałeś, i tam warto mierzyć dalej.

Ograniczenie jest jedno i istotne: na produkcji nie ma odpowiedzi wzorcowych, więc dwie z czterech metryk odpadają. Zostają wierność i trafność odpowiedzi, obie liczone bez odniesienia, i to wystarcza do wykrycia pogorszenia.

Praktyczny układ polega na próbkowaniu. Ocena dziesięciu procent ruchu daje wystarczający obraz przy dziesięciokrotnie niższym koszcie, a przypadki z niską wiernością trafiają do kolejki przeglądu.

Z tej kolejki powstaje zestaw testowy na kolejny cykl. To zamyka pętlę: produkcja dostarcza przypadków, zestaw pilnuje, żeby poprawka ich nie zepsuła, a kolejny pomiar produkcyjny sprawdza, czy poprawka faktycznie zadziałała u użytkowników.

Ragas kontra alternatywy

Ostatni wiersz nabiera znaczenia w świetle sekcji o stanie projektu. Triada z tamtej biblioteki opisuje te same trzy zerwania, a rozwój ma wyraźnie żywszy, z wydaniami z połowy 2026 roku. Jest jednak różnica, którą trzeba znać przed przesiadką: po tamtej stronie nie ma osobnej miary pokrycia kontekstu, więc fragment, którego wyszukiwanie w ogóle nie zwróciło, ujawni się dopiero pośrednio, po niskiej ocenie odpowiedzi. To właśnie ta miara wymaga u nas odpowiedzi wzorcowej i to ona najczęściej rozstrzyga, czy poprawiać indeks, czy prompt.

Te narzędzia obsługują różne pytania i najczęściej używa się dwóch. To odpowiada na pytanie, gdzie leży problem w systemie wyszukiwania. Narzędzie obserwacyjne odpowiada na pytanie, co faktycznie dzieje się na produkcji, i dostarcza przypadków do zestawu.

Warto też wiedzieć, że metryki opisane tutaj przyjęły się szeroko, więc znajdziesz je w innych narzędziach pod tymi samymi nazwami. Wybór biblioteki jest więc mniej istotny niż zrozumienie, co która miara mówi.

Przy okazji porównania warto rozdzielić dwie rzeczy, które w rozmowach o jakości systemów wyszukujących nagminnie się mieszają. Pierwsza to trafność wyszukiwania mierzona bez udziału modelu: czy właściwy fragment znalazł się w pierwszej trójce wyników. To sprawdzisz zwykłym skryptem, za darmo i deterministycznie, więc warto zacząć właśnie od tego.

Druga to jakość odpowiedzi, która wymaga oceny modelem i kosztuje. Jeśli pierwsza miara jest niska, druga nie ma czego mierzyć, bo model dostaje zły materiał. Kolejność diagnozy powinna więc iść od taniego pomiaru wyszukiwania do drogiego pomiaru odpowiedzi, a nie odwrotnie.

Typowe błędy

Pierwszy to mierzenie wyłącznie jakości odpowiedzi. Bez metryk kontekstu nie wiadomo, czy poprawiać prompt, czy wyszukiwanie, a to dwie zupełnie różne prace.

Drugi to traktowanie wyniku bezwzględnego jako oceny. Wartość osiemdziesięciu setnych nie znaczy nic bez porównania z poprzednim przebiegiem i bez wiedzy o dziedzinie.

Trzeci to zestaw złożony z pytań wygenerowanych automatycznie. Takie pytania są zbyt bliskie dokumentom i nie przypominają tego, jak pytają ludzie.

Czwarty to brak przypadków spoza zakresu. System, który na wszystko odpowiada, wypadnie dobrze w pomiarze i źle w praktyce, bo na pytania bez pokrycia w dokumentach powinien odpowiadać, że nie wie.

Piąty to wyciąganie wniosków z różnic mniejszych niż szum pomiaru. Ocena modelem nie jest deterministyczna, więc dwie setne różnicy to przypadek, a nie poprawa.

Szósty to jednorazowy pomiar przy wdrożeniu. Dokumenty się zmieniają, model dostawcy się zmienia, a jakość spada po cichu, więc pomiar warto powtarzać cyklicznie.

FAQ

Do czego dokładnie służy Ragas?

Do rozdzielenia dwóch przyczyn słabych odpowiedzi w systemie odpowiadającym z własnych dokumentów: błędu wyszukiwania i błędu generowania. Cztery metryki pokazują, na którym etapie leży problem, co przekłada się wprost na to, co poprawiać.

Czy Ragas jest darmowy?

Tak, biblioteka jest otwarta i uruchamiasz ją u siebie. Płacisz natomiast za wywołania modelu, którym odbywa się ocena, a przy pełnym zestawie metryk to kilka wywołań na każdy przypadek testowy.

Ile przypadków testowych potrzeba?

Trzydzieści do pięćdziesięciu wystarcza, żeby wykryć różnicę między wariantami. Ważniejsza od liczby jest różnorodność: pytania proste, wymagające połączenia informacji i takie, na które system nie powinien odpowiadać.

Czym Ragas różni się od Promptfoo?

Ragas ma metryki dopasowane do systemów wyszukujących i mówi, na którym etapie leży problem. Promptfoo porównuje warianty promptów i modeli oraz generuje ataki sprawdzające odporność. Najlepiej działają razem, bo odpowiadają na inne pytania.

Czy pomiar można zautomatyzować?

Tak, biblioteka daje się uruchomić w potoku budowania jak zwykły test. Ze względu na koszt rozsądny podział to mały zestaw przy każdej zmianie i pełny przed wydaniem, z progiem zaliczenia ustawionym na poziomie zestawu, a nie pojedynczego przypadku.

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