Uwagi praktyczne: Poza embeddingami – automatyczna weryfikacja dokumentów i wersjonowanie
Praktyczne wskazówki: Poza embeddingami – automatyczna walidacja dokumentów oraz wersjonowanie umów, kontrol i miejsc na kod do łatwego wdrożenia dla zespołów stosujących ten wzorzec.
Źródła: Beyond Embeddings: Automated Document Validation and Version Control for RAG Knowledge Bases
To przewodnictwo pokazuje, jak odtworzyć proces od surowców do gotowego systemu w ramach projektu: Beyond Embeddings: Automated Document Validation and Version Control for RAG Knowledge Bases. Skupia się na konkretnych krokach, wyraźnych sprawdzeniach oraz kodzie, który można bez problemu wdrożyć do repozytorium, bez konieczności domyślania się intencji. Na etapie przeglądu należy zdefiniować dane wejściowe, osobę odpowiedzialną za dany krok oraz kryteria zakończenia przed zmianą kodu. Operatorzy powinni móc ponownie uruchomić dany krok na podstawie znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu systemu. Konfigurację należy przechowywać oddzielnie od kodu aplikacji. Pliki środowiskowe, magazyny haseł oraz flagi funkcjonalne powinny znajdować się w jednym miejscu, które operatorzy mogą sprawdzić, nie musząc czytać całej struktury aplikacji.
Wprowadzenie
Gdy przechodzisz przez etap wprowadzenia, najpierw zapisz umowę: wymagane dane wejściowe, sygnał sukcesu oraz to, co dzieje się w przypadku częściowego niepowodzenia. Taka lista kontrolna zapewnia uczciwość późniejszych zmian w kodzie. Zdokumentuj zarówno ścieżkę prawidłowego działania, jak i ścieżkę naprawczą. Próby ponowne, kontrola przez ludzi oraz obsługa wiadomości błędnych stanowią część produktu, a nie elementy dodawane później w celu udoskonalenia. Zmierz stopień odzyskiwania informacji na ustalonej grupie pytań przed dostosowywaniem promptów. Częste zmiany promptów rzadko naprawiają słabe mechanizmy wyszukiwania.
Dlaczego same metadane zawodzą
Gdy przechodzisz przez etap „Dlaczego same metadane nie wystarczą”, najpierw zapisz umowę: wymagane dane wejściowe, sygnał sukcesu oraz to, co dzieje się w przypadku częściowego niepowodzenia. Taka lista kontrolna zapewnia uczciwość późniejszych zmian w kodzie. Wolij małe, testowalne jednostki nad rozbudowane skrypty. Gdy jakiś krok się nie powiedzie, błąd powinien wskazywać na jedną konkretne odpowiedzialność, a nie na skomplikowany proces. Zmierz stopień przywoływania informacji na ustalonej serii pytań przed dostosowywaniem promptów. Częste zmiany promptów rzadko naprawiają słabe możliwości wyszukiwania.
import fitz # PyMuPDF
from pypdf import PdfReader
doc = fitz.open("mining_act_2022.pdf")
metadata = doc.metadata
for key, value in metadata.items():
print(f"{key}: {value} -> {type(value)}")
format: PDF 1.5 -> <class 'str'>
title: View - NSW legislation -> <class 'str'>
author: -> <class 'str'>
subject: -> <class 'str'>
keywords: PCO, Parliamentary Counsel's Office, ...
creator: -> <class 'str'>
producer: Prince 15.1 (www.princexml.com) -> <class 'str'>
creationDate: -> <class 'str'>
modDate: -> <class 'str'>
trapped: -> <class 'str'>
encryption: None -> <class 'NoneType'>
Dlaczego regex i LLM nie wystarczają
Gdy przechodzisz przez etap „Dlaczego Regex i LLMs”, najpierw zapisz umowę: wymagane dane wejściowe, sygnał sukcesu oraz to, co dzieje się w przypadku częściowego niepowodzenia. Taka lista kontrolna zapewnia uczciwość późniejszych zmian w kodzie. Traktuj ten etap jako umowę pomiędzy danymi wejściowymi a zweryfikowanymi wynikami. Nadaj nazwy poszczególnym elementom, zdefiniuj kryteria sukcesu i odrzuć ciche, częściowe ukończenie zadań. Zachowuj w pamięci tymczasowej stabilne instrukcje systemu oraz schematy narzędzi. Ponowne wysyłanie identycznego tekstu wejściowego jest częstą przyczyną marnotrawstwa zasobów. Gdy przechodzisz przez etap „Dlaczego Regex i LLMs”, najpierw zapisz umowę: wymagane dane wejściowe, sygnał sukcesu oraz to, co dzieje się w przypadku częściowego niepowodzenia. Taka lista kontrolna zapewnia uczciwość późniejszych zmian w kodzie. Przechowuj konfigurację poza kodem aplikacji. Pliki środowiskowe, magazyny haseł oraz flagi funkcjonalne powinny znajdować się w jednym miejscu, które operatorzy mogą sprawdzić bez konieczności czytania całej struktury.
Metodologia
Etap metodologii funkcjonuje najlepiej, gdy traktowany jest jako mierzalna powierzchnia. Zapisz jeden idealny przepis działania, jeden przypadek awarii oraz notatkę dotyczącą cofnięcia działań, zanim rozszerzysz zakres pracy. Zdokumentuj zarówno ścieżkę prawidłowego działania, jak i ścieżkę przywracania stanu. Próby ponownych działań, kontrolne punkty ludzkie oraz obsługa wiadomości nieodebranych stanowią część produktu, a nie elementy dodawane później. Oddziel zasadę dzielenia na fragmenty od zasady wyszukiwania. Zmiana jednej z nich nie powinna zmuszać do przepisywania drugiej w przypadku zmian wskaźników jakości.
Ekstrakcja metadanych
Etap wydobywania metadanych działa najlepiej, gdy traktuje się go jako mierzalną powierzchnię. Zapisz jeden idealny przepis, jeden przypadek awarii oraz notatkę dotyczącą cofnięcia działań, zanim rozszerzysz zakres pracy. Wolno preferować małe, testowalne jednostki zamiast rozbudowanych skryptów. Gdy jakiś krok zawiedzie, awaria powinna wskazywać na konkretną odpowiedzialność, a nie na skomplikowany łańcuch operacji. Oddziel zasady dzielenia na fragmenty od zasad pobierania danych. Zmiana jednych nie powinna zmuszać do przepisywania drugich, gdy zmieniają się metryki jakości.
# Example of document id generation
raw_bytes = Path(pdf_path).read_bytes()
content_hex = raw_bytes.hex()
doc_std_id = str(uuid.uuid5(DOCUMENT_ID_NAMESPACE, content_hex))
# Code Example of generating similarity id with minhash encoding
def _compute_doc_similarity_id(self, full_text: str) -> str:
sketch = pyhyperminhash.Sketch()
entry = pyhyperminhash.Entry()
entry.add_bytes(full_text.encode("utf-8"))
sketch.add_entry(entry)
return base64.b64encode(sketch.save()).decode()
# Code Example of DocumentFingerprint Pydantic model class
class DocumentFingerprint(BaseModel):
primary_entity: str
entity_type: str
key_words: list[str]
Walidacja treści
Etap walidacji treści funkcjonuje najlepiej, gdy traktowany jest jako mierzalna powierzchnia do analizy. Zapisz jeden idealny przykład transkrypcji, jeden przypadek awarii oraz notatkę dotyczącą cofnięcia działań, zanim rozszerzysz zakres pracy. Traktuj ten etap jako umowę pomiędzy danymi wejściowymi a zweryfikowanymi wynikami. Nadaj nazwy poszczególnym elementom, zdefiniuj kryteria sukcesu i odrzucaj ciche, częściowe ukończenie zadań. Oddziel politykę dzielenia na fragmenty od polityki pobierania danych. Zmiana jednej z nich nie powinna zmuszać do przepisywania drugiej, gdy zmieniają się metryki jakości. Etap walidacji treści funkcjonuje najlepiej, gdy traktowany jest jako mierzalna powierzchnia do analizy. Zapisz jeden idealny przykład transkrypcji, jeden przypadek awarii oraz notatkę dotyczącą cofnięcia działań, zanim rozszerzysz zakres pracy. Przechowuj konfigurację poza kodem aplikacji. Pliki środowiskowe, składyce z danymi poufnymi oraz flagi funkcjonalne powinny znajdować się w jednym miejscu, które operatorzy mogą audytować bez konieczności czytania całej struktury.
# Coding Example for Jaccard similarity computation
import pyhyperminhash
new_sketch_bytes = base64.b64decode(new_doc_similarity_id)
new_sketch = pyhyperminhash.Sketch.load(new_sketch_bytes)
cand_sketch_bytes = base64.b64decode(candidate_similarity_id)
cand_sketch = pyhyperminhash.Sketch.load(cand_sketch_bytes)
jaccard_sim = new_sketch.similarity(cand_sketch)
jaccard_threshold = SIMILARITY_CONFIG["jaccard_threshold"]
if jaccard_sim < jaccard_threshold:
print("New document detected")
"""
Upload as a new document to vector daatabase
"""
else:
print("Similar document detected")
"""
Subsequent identity score calculation...
"""
Wniosek
W fazie podsumowania należy zdefiniować dane wejściowe, osobę odpowiedzialną za dany krok oraz kryteria zakończenia przed zmianą kodu. Operatorzy powinni móc ponownie uruchomić ten krok na podstawie znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu. Należy udokumentować zarówno prawidłowy przebieg procesu, jak i ścieżkę naprawczą. Próby ponownych działań, kontrolne punkty ludzkie oraz obsługa wiadomości błędnych stanowią część produktu, a nie elementy dodawane później. Należy podać fragmenty tekstu, które faktycznie stanowią podstawę odpowiedzi. Bez tych odniesień operatorzy nie będą w stanie odróżnić halucynacji od braku danych w indeksie.
Lista kontrolna operacyjna
Faza listy kontrolnej operacyjnej działa najlepiej, gdy jest traktowana jako mierzalna powierzchnia do analizy. Należy zebrać jeden idealny przepis działania, jeden przypadek awarii oraz notatkę dotyczącą cofnięcia zmian, zanim rozszerzy się zakres pracy.
Należy rejestrować czasy wykonywania operacji oraz koszt tokenów lub zapytań obok wyników funkcjonalnych. Wczesna widoczność kosztów zapobiega niespodziewanym rachunkom, gdy proces przechodzi z środowiska demonstracyjnego do wspólnych środowisk.
Rozdziel politykę dzielenia na fragmenty od polityki pobierania danych. Zmiana jednej z nich nie powinna zmuszać do przepisania drugiej, gdy zmieniają się metryki jakości.
Dodaj test sprawdzający, który symuluje kluczową ścieżkę w procesie CI przy użyciu narzędzi testowych, a nie rzeczywistych płatnych API, o ile na to pozwalają budżety.
Zachowaj konfigurację poza kodem aplikacji. Pliki środowiskowe, magazyny haseł oraz flagi funkcjonalne powinny znajdować się w jednym miejscu, które operatorzy mogą sprawdzić bez konieczności przeglądania całej struktury.
Rozdziel politykę dzielenia na fragmenty od polityki pobierania danych. Zmiana jednej z nich nie powinna zmuszać do przepisania drugiej, gdy zmieniają się metryki jakości.
Zanim wdrożysz nową architekturę, zamroź aktualne wersje, utwórz „złoty zapis” dla kluczowej ścieżki i upewnij się, że znasz kroki odwracające zmiany. Środowiska współdzielone wymagają ograniczeń szybkości, weryfikacji dostępu oraz wyraźnego właściciela odpowiedzialnego za rotację haseł. Wolisz nudną niezawodność od pomysłowych, jednorazowych demonstracji.
Uwaga dotycząca partii dla 4cd49d3b9b36: unikaj przechowywania kluczy dostawcy w repozytorium, ustaw ograniczenie liczby tokenów na sesję oraz przechowuj transkrypcje obok przykładów do oceny, aby późniejsze zmiany modeli pozostały porównywalne.
Etap 0 dotyczący wzmocnienia bezpieczeństwa działa najlepiej, gdy traktuje się go jako mierzalną powierzchnię do analizy. Zapisz jedną idealną transkrypcję, jeden przypadek awarii oraz notatkę dotyczącą cofnięcia zmian przed rozszerzaniem zakresu. Traktuj ten etap jako umowę pomiędzy danymi wejściowymi a zweryfikowanymi wynikami. Nazwij pliki, zdefiniuj kryteria sukcesu i odrzuć ciche, częściowe ukończenie zadań.
Szczegół wzmocnienia bezpieczeństwa 0/869: zmierz czas wykonywania, klasę błędu oraz zużycie tokenów dla tej notatki, a następnie zdecyduj, czy zachować zmianę na podstawie ustalonego zestawu pytań, a nie jedynie informacji anegdotycznych.
Literatura pokrewna
- Praktyczne notatki: Poza chwaleniem się bilionowymi wektorami – wybieranie najlepszego — Szczegółowy przewodnik po Praktycznych notatkach: Poza chwaleniem się bilionowymi wektorami – wybieranie najlepszego: kontrakty, sprawdzenia oraz gotowe fragmenty kodu dla zespołów wdrażających ten wzorzec.
- Praktyczne notatki: Search semantyczny vs Search wektorowy – jaka jest różnica, i — Szczegółowy przewodnik po Praktycznych notatkach: Search semantyczny vs Search wektorowy – jaka jest różnica, i: kontrakty, sprawdzenia oraz gotowe fragmenty kodu dla zespołów wdrażających ten wzorzec.