Podręcznik uczestnika z objaśnieniami, przykładami i ćwiczeniami do samodzielnej nauki

5. Kod wyjaśnianie debugowanie i refaktoryzacja

LLM może wyjaśniać istniejący kod, proponować nowy, pomagać w debugowaniu i porządkować rozwiązanie. Każda z tych czynności ma inny punkt odniesienia. Przy wyjaśnianiu sprawdzasz zgodność opisu z operacjami. Przy generowaniu — zgodność kodu ze specyfikacją. Przy debugowaniu — usunięcie przyczyny błędu bez niezamierzonej zmiany sensu. Przy refaktoryzacji — zachowanie uzgodnionego zachowania programu.

Przygotowanie niezależnej sesji

Notebook zapisz jako notebooks/M5_praca_z_LLM.ipynb. Poniższy blok obsługuje uruchomienie z głównego katalogu projektu albo z notebooks. Jeśli używasz innego katalogu roboczego, wskaż PROJECT_DIR jawnie. Blok nie pobiera danych ani nie łączy się z modelem. Zapisuje informacje potrzebne do odtworzenia obliczeń.

from pathlib import Path
from hashlib import sha256
import sys
import pandas as pd
import numpy as np
 
PROJECT_DIR = Path.cwd()
if PROJECT_DIR.name == "notebooks":
    PROJECT_DIR = PROJECT_DIR.parent
plik = PROJECT_DIR / "data/processed/pomiary_clean.csv"
assert plik.is_file(), f"Brak przygotowanych danych: {plik}"
hash_wejscia = sha256(plik.read_bytes()).hexdigest()
df = pd.read_csv(plik, parse_dates=["czas", "data_instalacji"])
assert df.shape == (720, 14)
ID_URZADZEN = {f"U-{i:02d}" for i in range(1, 9)}
assert set(df["urzadzenie"]) == ID_URZADZEN
assert df["urzadzenie"].value_counts().eq(90).all()
assert df[["urzadzenie", "temperatura", "drgania"]].notna().all().all()
assert not df.duplicated(["czas", "urzadzenie"]).any()
df_baza = df.copy(deep=True)
print("Python:", sys.version.split()[0], "Pandas:", pd.__version__)
print("SHA-256:", hash_wejscia)
display(df.dtypes)

SHA-256 identyfikuje zawartość pliku, nie potwierdza jej jakości. Oczekiwania 720 × 14 i osiem urządzeń dotyczą danych kursowych. W innym projekcie wymagania ustalasz na podstawie źródła i celu, nie przez kopiowanie tych liczb.

Minimalna poprawka i czytelny wynik

Źródłem KeyError jest odwołanie do drgania_mm_s zamiast drgania. Nie musisz tworzyć nowego pola, przemianowywać całej ramki ani instalować bibliotek. Wystarczy użyć istniejącej nazwy. Poniższy wynik ma rozszerzony, jawny format: urzadzenie, mediana_drgan i n. Ponieważ drgania są kompletne, n oznacza zarówno liczbę rekordów, jak i dostępnych wartości.

ranking = (
    df.groupby("urzadzenie", as_index=False)
    .agg(mediana_drgan=("drgania", "median"),
         n=("drgania", "size"))
    .sort_values("mediana_drgan", ascending=False, ignore_index=True)
)
display(ranking)

Urządzenie

Mediana drgań w mm/s

n

U-05

1,3735

90

U-08

1,3605

90

U-07

1,3460

90

U-03

1,2520

90

U-06

1,2500

90

U-02

1,1575

90

U-04

1,1250

90

U-01

1,0380

90

To wartości obliczone na danych kursowych, nie wyniki odgadnięte przez model. Tabela odpowiada na pytanie o medianę w badanym okresie. U-05 ma najwyższą medianę, ale różnica względem U-08 wynosi tylko 0,0130 mm/s. Samo pierwsze miejsce nie jest diagnozą niesprawności ani oceną istotności różnicy.

Wyjaśnienie operacji

Groupby dzieli pomiary według urządzenia, agg nazywa miary wyniku, a sort_values ustala kolejność. Parametr as_index=False pozostawia identyfikator w kolumnie. Ignore_index=True porządkuje techniczny indeks po sortowaniu; nie zmienia identyfikatorów urządzeń. Taki opis pozwala sprawdzić, czy odpowiedź LLM faktycznie wyjaśnia kod, zamiast jedynie powtarzać jego nazwy.

Test wyniku i test braku skutków ubocznych

Sprawdzenie shape wykryje zmianę liczby wierszy lub kolumn, ale nie wykryje podmiany jednej wartości. Dlatego porównujesz całe df z kopią sprzed pracy. Osobno kontrolujesz wynik: nazwy pól, pełny zbiór identyfikatorów, liczebności, kolejność i wartości median obliczone drugim sposobem.

assert ranking.columns.tolist() == ["urzadzenie", "mediana_drgan", "n"]
assert set(ranking["urzadzenie"]) == ID_URZADZEN
assert ranking["urzadzenie"].is_unique
assert ranking["n"].eq(90).all()
assert ranking["mediana_drgan"].is_monotonic_decreasing
kontrola = df.pivot_table(
    index="urzadzenie", values="drgania", aggfunc="median"
)
np.testing.assert_allclose(
    ranking.set_index("urzadzenie").sort_index()["mediana_drgan"],
    kontrola.sort_index()["drgania"], rtol=1e-12, atol=1e-12
)
pd.testing.assert_frame_equal(df_baza, df)

Druga implementacja w Pandas pomaga wykryć pomyłkę w składaniu wyniku, ale nie stanowi niezależnego badania danych. Obie metody korzystają z tego samego wejścia i tej samej definicji mediany. Dlatego poprawność jednostki, sens grupowania i pochodzenie danych sprawdzasz osobno.

Funkcja z jawnymi warunkami wejścia

Refaktoryzacja pozwala użyć rozwiązania ponownie. Poniżej dodajemy walidację: wymagane kolumny muszą istnieć, tabela nie może być pusta, a identyfikatory i drgania nie mogą mieć braków. To świadome rozszerzenie zachowania; zamiast przypadkowego KeyError otrzymasz zrozumiały ValueError.

def ranking_drgan(dane):
    wymagane = {"urzadzenie", "drgania"}
    brakujace = wymagane - set(dane.columns)
    if brakujace:
        raise ValueError(f"Brak kolumn: {sorted(brakujace)}")
    if dane.empty or dane[list(wymagane)].isna().any().any():
        raise ValueError("Puste wejście lub braki w wymaganych polach")
    return (
        dane.groupby("urzadzenie", as_index=False)
        .agg(mediana_drgan=("drgania", "median"),
             n=("drgania", "size"))
        .sort_values("mediana_drgan", ascending=False, ignore_index=True)
    )

Przypadki brzegowe i zakres gwarancji

Nie dodawaj obsługi wyjątków tylko po to, aby ukryć problem. Funkcja ma zatrzymać pracę, gdy nie da się spełnić umówionego kontraktu. Dzięki temu brak identyfikatora nie zniknie po cichu podczas grupowania. W innym zastosowaniu możesz dopuścić braki drgań, ale wtedy potrzebujesz nowej reguły liczenia n i testu grup bez dostępnych wartości.

pd.testing.assert_frame_equal(ranking, ranking_drgan(df))
proby_bledne = [
    df.drop(columns="drgania"), df.iloc[:0],
    df.assign(urzadzenie=np.nan), df.assign(drgania=np.nan)
]
for proba in proby_bledne:
    try:
        ranking_drgan(proba)
    except ValueError as blad:
        print("Oczekiwane zatrzymanie:", blad)
    else:
        raise AssertionError("Funkcja przyjęła niepoprawne wejście")
pd.testing.assert_frame_equal(df_baza, df)

Oczekiwany wyjątek jest przechwycony wewnątrz testu, więc późniejsze uruchomienie wszystkich komórek nie zatrzyma się na demonstracji błędu. Test odróżnia poprawne odrzucenie nieprawidłowego wejścia od awarii niekontrolowanej. Nie przechwytuj jednak wszystkich wyjątków bez rozróżnienia: inny błąd powinien pozostać widoczny.

Podana funkcja nie jest pełnym walidatorem dowolnych danych produkcyjnych. Zakłada liczbowe drgania, a dla identycznych median nie definiuje dodatkowego kryterium kolejności. Jeśli to istotne w nowym zadaniu, rozszerz kontrakt i testy, zamiast traktować przykład jako uniwersalne rozwiązanie.

Co przyjąć z odpowiedzi modelu

Przyjmujesz poprawkę nazwy po przejściu testów. Możesz osobno przyjąć czytelniejszą strukturę funkcji. Odrzucasz zamianę mediany na średnią, globalne usuwanie braków lub zmianę nazw wejścia, jeżeli nie wynikają z zadania. Ocena „częściowo przydatne” jest bardziej precyzyjna niż bezwarunkowe przyjęcie całej odpowiedzi.

Sprawdź rozumienie 3

Po uruchomieniu kodu df nadal ma 720 wierszy i 14 kolumn. Dlaczego to za mało, aby potwierdzić brak zmian? Jak sprawdzisz poprawność rankingu oraz zachowanie funkcji po usunięciu wymaganej kolumny z kopii danych? Dlaczego zastąpienie KeyError przez ValueError trzeba opisać jako zmianę zachowania?