Instrukcja pracy z Modułem 3
Embeddingi i lokalne wyszukiwanie semantyczne
Przejdziesz od zaakceptowanych fragmentów M2 przez embeddingi i ranking do zapisanego indeksu oraz oceny wyszukiwania. Gotowe notebooki prowadzą przez obliczenia; własne oczekiwania i interpretacje zapisujesz samodzielnie, zanim zobaczysz wyniki modelu.
1Cel i rezultat modułu
- Odróżnisz dopasowanie słów od podobieństwa znaczenia.
- Utworzysz embeddingi lub jawnie skorzystasz z rzeczywistego checkpointu.
- Sprawdzisz ranking, teksty źródłowe i spójność indeksu.
- Przeprowadzisz testy z niezależnym kluczem i zachowasz wynik do M4.
M3 dotyczy wyszukiwania fragmentów. Nie uruchamia modelu generującego odpowiedzi. Score nie jest procentem pewności.
2Zawartość pakietu Studenta
Rozpakuj cały pakiet i zachowaj strukturę folderu Student. Nie kopiuj pojedynczego notebooka poza pakiet. Notebooki same odnajdują katalog Student, dlatego możesz uruchamiać je z folderu notebooki.
| Materiał | Rola |
|---|---|
notebooki/00_sprawdzenie_srodowiska.ipynb | Sprawdzenie pakietów, danych oraz wybranego trybu embeddingów. |
notebooki/M12_M3_R1…R6_*_start.ipynb | Sześć ćwiczeń z miejscami na własne decyzje i wnioski. |
notebooki/07_sprawdzenie_indeksu_po_restarcie.ipynb | Kontrola odczytu indeksu w nowym kernelu, bez wywołania modelu. |
| karty_pracy/ | Sześć kart DOCX i HTML odpowiadających notebookom. |
dane/knowledge_base_ready.jsonl i zrodla/ | 10 zaakceptowanych fragmentów M2 i cztery źródła w wersji 1.4. |
dane/R1_fragmenty.json i R1_fragmenty.md | Materiał do własnej oceny znaczenia w R1. |
dane/pytania_startowe.json i test_cases_szablon.jsonl | 12 pytań bez klucza oraz szablon oczekiwań do R6. |
kod/m3_tools.py i sprawdz_indeks.py | Wspólne funkcje, walidatory i kontrola w niezależnym procesie. |
konfiguracja.json i requirements.txt | Jedna konfiguracja modelu oraz zależności środowiska. |
| checkpointy/R2/, R5/ i pytania/ | Rzeczywiste zapisane embeddingi, indeks i wektory pytań. |
| wyniki/ | Twoje automatycznie tworzone foldery prób. |
DocAssist jest projektem dydaktycznym. Polecenia systemctl w źródłach są analizowanym tekstem, a nie poleceniami do wykonania na Twoim komputerze.
3Przygotowanie środowiska
Pakiet sprawdzono na Pythonie 3.12 w Windows. W terminalu otwartym w folderze Student utwórz środowisko i zarejestruj kernel:
py -3.12 -m venv .venv
.venv\Scripts\python.exe -m pip install -r requirements.txt
.venv\Scripts\python.exe -m ipykernel install --user --name m12-m3 --display-name "Python M12 M3"
.venv\Scripts\python.exe -m jupyterlabNa macOS lub Linux użyj python3.12 i .venv/bin/python zamiast ścieżki Windows. W JupyterLab wybierz kernel Python M12 M3. Otwórz notebook 00 przed R2; R1 nie wymaga działającego modelu.
Dla MODE=ollama uruchom lokalną usługę i upewnij się, że dostępny jest model:
ollama pull bge-m3:latest
ollama listPierwsza instalacja pakietów i pobranie modelu wymagają sieci. Po przygotowaniu środowiska MODE=checkpoint nie wymaga Ollama. Domyślny adres usługi to http://127.0.0.1:11434.
4Wybór trybu i danych wejściowych
| Ustawienie | Znaczenie |
|---|---|
| MODE = "ollama" | Nowe embeddingi powstają w lokalnym modelu. Fragmenty i pytania muszą mieć ten sam model, digest i wymiar. |
| MODE = "checkpoint" | Odczyt rzeczywistych wektorów prowadzącego. Nie jest nowym pomiarem modelu na Twoim komputerze. |
| SOURCE = "wlasne" | R3–R5 używają wskazanej własnej próby R2, a R6 — własnej próby R5. |
| SOURCE = "checkpoint" | R3–R5 używają dostarczonego R2, a R6 — dostarczonego indeksu R5. |
| EXPLICIT_INPUT = None | Domyślnie używany jest wskaźnik wyniki/wybrane_proby.json. Możesz wpisać konkretną ścieżkę R2/id albo R5/id względem wyniki. |
Zalecany przebieg: MODE=ollama i SOURCE=wlasne. Bez lokalnego modelu wybierz MODE=checkpoint. Jeżeli wykonasz R2 i R5 w tym trybie, możesz nadal używać SOURCE=wlasne do dalszej pracy z zapisanymi przez siebie kopiami i indeksem. Jeżeli zaczynasz od późniejszego rozdziału, wybierz jawnie SOURCE=checkpoint.
Tryb checkpoint obsługuje wyłącznie dokładne teksty 12 pytań z pytania_startowe.json i tekst kontrolny notebooka 00. Własne nowe pytanie albo zmiana jego treści wymagają MODE=ollama. Nie ma automatycznego przełączenia trybu przy błędzie.
W R2 checkpoint jest zgodny tylko z dostarczonym wejściem M2. Dla własnej zmienionej bazy użyj trybu ollama. Jeśli lokalny digest modelu jest inny niż w checkpointach, przelicz własne R2 albo użyj trybu checkpoint także dla pytań.
5Kolejność pracy
| Rozdział | Otwórz notebook | Rezultat |
|---|---|---|
| R1 — Od tekstu do reprezentacji wektorowej | M12_M3_R1_intuicja_embeddingow_start.ipynb | hipotezy_podobienstwa.json |
| R2 — Tworzenie embeddingów lokalnie | M12_M3_R2_embeddingi_start.ipynb | chunks_with_embeddings.jsonl i dwa pliki opisu przebiegu |
| R3 — Podobieństwo wektorów | M12_M3_R3_kosinus_start.ipynb | podobienstwa.csv i własna interpretacja |
| R4 — Wyszukiwanie najbliższych fragmentów | M12_M3_R4_ranking_top_k_start.ipynb | ranking_results.jsonl i interpretacja wyników |
| R5 — Od listy embeddingów do lokalnego indeksu | M12_M3_R5_zapis_indeksu_start.ipynb | folder semantic_index gotowy do przekazania do M4 |
| R6 — Testowanie jakości wyszukiwania semantycznego | M12_M3_R6_test_retrieval_start.ipynb | test_cases.jsonl, retrieval_baseline.jsonl i raport_testow.md |
- Przygotuj próbę
Przeczytaj kartę i materiał rozdziału. W notebooku wybierz ustawienia, a następnie wykonaj Przygotowanie. Zapisz wyświetloną ścieżkę.
- Uzupełnij własne decyzje
Pola UZUPEŁNIJ i None wymagają odpowiedzi. W R3 i R4 ustal oczekiwania przed pomiarem. W R6 uzupełnij szablon, a notebook zapisze klucz przed pobraniem rankingu.
- Uruchom obliczenia i kontrole
Przeczytaj wskazane funkcje wspólne. Wykonuj komórki kolejno i sprawdzaj komunikaty. Kontrole błędnych danych celowo pokazują oczekiwane błędy.
- Zachowaj interpretację
Uzupełnij wniosek i zapisz notebook. Gotowe pliki obliczeń nie zastępują własnej analizy. R2 i R5 mogą wskazać dane do dalszej pracy jeszcze przed uzupełnieniem wniosku.
Łączny czas orientacyjny kart: około 220 minut, bez instalacji i oglądania materiałów. R6: minimum 8 pytań, wariant rozszerzony 12. Pierwsze 8 pozycji szablonu obejmuje wymagane typy; klasyfikację i klucz ustalasz samodzielnie.
6Punkty kontrolne
| Etap | Co musi się zgadzać |
|---|---|
| R2 | Liczności sukcesów, pominięć i błędów rozliczają wejście; zachowano chunk_id, tekst i całe metadata. |
| R3 | Proste pary dają 1, 0 i −1; błędne wektory są odrzucane. |
| R4 | Wyniki są uporządkowane malejąco; każdy zawiera tekst, źródło i score. |
| R5 | Oba walidatory zostały wywołane. Mapowanie porównano z R2. Niezależny proces odtworzył ranking z plików. |
| Notebook 07 | Nowy kernel potrafi odczytać wskazany indeks i powtórzyć kontrolę bez zmiennych z R5. |
| R6 | Klucz zapisano przed testem; metryki liczone są tylko po answerable. Przypadki bez odpowiedzi analizujesz osobno. |
7Zapis wyników i nazewnictwo
Komórka Przygotowanie tworzy nowy folder wyniki/Rn/<proba_id>/. Identyfikator nadaje kod, nie wpisujesz go ręcznie. Nie uruchamiaj Przygotowania ponownie w środku pracy. Próba ponownego zapisu istniejącego pliku zgłosi błąd; rozpocznij nowy przebieg. Wskaźnik wybrane_proby.json ułatwia przejście między rozdziałami i nie usuwa poprzednich wyników.
| Rozdział | Podstawowe pliki |
|---|---|
| R1 | hipotezy_podobienstwa.json, wnioski.md |
| R2 | chunks_with_embeddings.jsonl, embedding_manifest.json, embedding_errors.jsonl, wnioski.md |
| R3 | oczekiwania.json, podobienstwa.csv, wnioski.md |
| R4 | oczekiwania.jsonl, ranking_results.jsonl, wnioski.md |
| R5 | semantic_index/, kontrola_restartu.json, wynik_restartu.json, kontrola_indeksu.md, wnioski.md |
| R6 | test_cases.jsonl, retrieval_baseline.jsonl, metryki.json, raport_testow.md |
| Pochodzenie | przebieg.json; dla zależnych etapów zaleznosci.json; dla kopii R2 dodatkowo POCHODZENIE_CHECKPOINTU.json. |
Nie zamieniaj nazw podobnych plików
| Plik | Zawartość i rola |
|---|---|
knowledge_base_ready.jsonl | Wejście z M2. Rekordy chunk_id, text i metadata; bez embeddingów. |
chunks_with_embeddings.jsonl | Wynik R2. Te same rekordy rozszerzone o pole embedding. |
embedding_manifest.json | Opis przebiegu tworzenia embeddingów: wejście, model, backend, wymiar, data, liczności i pochodzenie. |
embedding_errors.jsonl | Rejestr pominięć i błędów. Rozróżnij status skipped i error; przypisz jedno końcowe rozstrzygnięcie każdemu rekordowi wejściowemu. |
semantic_index/chunks.jsonl | Treści i pełne metadane bez embeddingów, z vector_index równym pozycji w macierzy. |
semantic_index/index_metadata.json | Manifest zapisanego indeksu, łączący macierz i rekordy. Nie jest zamiennikiem manifestu R2. |
Minimalny kontrakt manifestu indeksu
Użyj poniższych nazw pól. Wartości w nawiasach kątowych zastąp rzeczywistymi danymi; chunk_count zapisz jako liczbę całkowitą. Dla indeksu M3 zapisujesz znormalizowaną macierz float32 i metrykę cosine.
| Pole | Wymagana wartość lub znaczenie |
|---|---|
| schema_version | "1.0" |
index_id | Własny jednoznaczny identyfikator tej wersji indeksu. |
| embedding_model | "bge-m3:latest" |
| embedding_backend | "ollama" |
| dimension | 1024, potwierdzone na zapisanych wektorach. |
| metric | "cosine" |
| normalized | true |
| chunk_count | Liczba wierszy macierzy i rekordów chunks.jsonl. |
| data_type | "float32" |
| source_artifact | "knowledge_base_ready.jsonl" |
| embeddings_file | "embeddings.npy" |
| chunks_file | "chunks.jsonl" |
| created_at | Rzeczywisty czas utworzenia w ISO 8601, ze strefą czasową. |
Dodatkowo warto zachować identyfikator lokalnego modelu, skróty kontrolne wejścia i plików oraz wersje środowiska. Wszystkie rekordy muszą zachować pełne metadata, w tym document_id, source, version, status, qa_status i dostępne wskazanie strony lub sekcji. Warianty zmieniające model mają odrębny manifest i indeks.
Nazwy funkcji i formaty wyników
| Nazwa | Kontrakt |
|---|---|
create_embedding(text, model_name=EMBEDDING_MODEL) | Własny parametr model_name przekaż jako model w embed() klienta Ollama. Stała EMBEDDING_MODEL wskazuje tag modelu. |
| cosine_similarity(vector_a, vector_b) | Wektory jednowymiarowe, zgodny wymiar, wartości skończone, normy dodatnie. |
search_similar_chunks(query_embedding, chunks, top_k=3) | Pętla po rekordach R2. Wyniki płaskie: chunk_id, text, metadata, score. |
| normalize_vector(vector) | Sprawdzenie danych i normalizacja do normy jednostkowej. |
validate_manifest() i validate_index() | Własne walidatory: trzeba je zdefiniować i wywołać po odczycie. Zakres kontroli określa karta R5. |
search_local_index(query_embedding, embedding_matrix, chunk_records, top_k=3) | Wyszukiwanie w macierzy R5. Normalizuje wektor pytania przed iloczynem skalarnym. Wynik zawiera score oraz zagnieżdżony chunk. |
normalize_search_results() | Adapter formatu R5 do płaskiego formatu R4; zachowuje pełne metadata. |
Zapis testów i definicja trafienia
W test_cases.jsonl zapisz question_id, question, question_type, case_type, expected_chunk_ids i uzasadnienie. question_type opisuje formę, np. direct, paraphrase lub ambiguous. case_type przyjmuje answerable, missing_in_sources albo out_of_scope. Dla dwóch ostatnich expected_chunk_ids jest pustą listą.
W retrieval_baseline.jsonl zapisz dla każdego pytania jego identyfikator, listę results z top-5, index_id, model, czas pomiaru oraz hit_at_1, hit_at_3 i hit_at_5. Dla answerable trafienie oznacza obecność co najmniej jednego dopuszczalnego chunk_id w pierwszych k wynikach. Dla pozostałych przypadków wpisz null zamiast 0; przeanalizuj je opisowo. Średnie licz wyłącznie po answerable. Gdy ta grupa jest pusta, wynik jest nieokreślony.
expected_chunk_ids oznacza alternatywne dopuszczalne trafienia. Jeśli do odpowiedzi potrzebujesz kilku fragmentów łącznie, pojedyncze Hit@k nie mierzy kompletności — opisz to ograniczenie lub dodaj osobną miarę.
W dostarczonym indeksie manifest zawiera także model_digest, source_sha256, r2_embeddings_sha256 oraz sumy embeddings_sha256 i chunks_sha256. Walidator odrzuca zmianę plików. Kontrola verify_mapping porównuje wektory, identyfikatory, tekst i metadane z konkretnym wejściem R2. Sumy kontrolne nie dowodzą prawdziwości źródeł.
8Lista kontroli przed oddaniem
Zaznaczenia na tej stronie nie są zapisywane. Ocenie podlegają pliki i Twoje uzasadnienia.
9Gdy pojawi się problem
Komunikat Uzupełnij pole
To zamierzony punkt pracy własnej. Wróć do odpowiedniej komórki, wpisz ocenę na podstawie źródeł i kontynuuj. Nie usuwaj walidacji tylko po to, aby notebook przeszedł dalej.
Plik wynikowy już istnieje
Rozpocznij nową próbę od Przygotowania, potem wykonaj komórki kolejno. Poprzedni wynik pozostaje zachowany.
Brak własnej próby R2 lub R5
Wykonaj poprzedni etap albo jawnie wybierz SOURCE=checkpoint. Sprawdź wybrane_proby.json lub EXPLICIT_INPUT.
Brak pytania w cache
Tryb checkpoint wymaga dokładnego tekstu z pytania_startowe.json. Dla własnego pytania użyj MODE=ollama.
Niezgodny digest lub wymiar
Nie łącz fragmentów i pytań z innych modeli. Wykonaj własny spójny przebieg R2 albo użyj checkpointów dla obu stron porównania.
Ollama nie odpowiada
Sprawdź usługę i ollama list. Jeśli wybierasz pracę bez modelu, ustaw MODE=checkpoint przed Przygotowaniem.
Kernel nie widzi pakietu
Wybierz Python M12 M3 i zainstaluj requirements.txt w tym środowisku. Rozpakuj cały pakiet, nie sam notebook.
10Przekazanie pracy i przejście do M4
Oddaj uzupełnione notebooki R1–R6 i wybrane foldery wyników zgodnie z ustaleniami prowadzącego. Nie dołączaj środowiska .venv ani zbędnych prób. Do M4 zachowaj cały semantic_index z R5 oraz raport testów R6. W pracy opisz, które embeddingi obliczono lokalnie, a które pochodzą z checkpointu.
Nie obowiązuje uniwersalny próg Hit@k. Liczą się poprawność pomiaru, odtwarzalność i rzetelna interpretacja. Wynik małego zestawu nie oznacza takiej samej jakości na dowolnej bazie.