Metadane i pola niestandardowe
Na tej stronie
Kontekst, którego dokument nie zawiera
Raport techniczny nie zawsze zawiera w treści nazwiska autora, roku powstania czy poziomu poufności. A jednak to właśnie te szczegóły decydują o tym, czy wyszukiwarka zwróci właściwy dokument, czy też trzy nieistotne wyniki. System metadanych kolekcji służy dokładnie temu celowi: pozwala powiązać z każdym dokumentem ustrukturyzowane informacje, które wyszukiwarka może wykorzystać, a Ty możesz filtrować.
Dołączanie pól do dokumentu
Podczas dodawania dokumentu parametr fields przyjmuje pary klucz-wartość, które definiujesz dowolnie:
await client.collections.upload_document(
collection_id=collection_id,
name="technical-report-q1",
data=pdf_content,
fields={
"author": "Marie Dupont",
"year": "2026",
"department": "R&D",
"document_type": "report",
"confidentiality": "internal"
}
)
Na tym poziomie nie ma wymuszonego schematu: nazwy pól wybierasz sam. Ta swoboda wydaje się wygodna przy pierwszym dokumencie, ale staje się problemem przy setnym, gdy w tej samej kolekcji współistnieją author, auteur i Author, a żaden filtr nie działa poprawnie.
Ustalanie reguł na poziomie kolekcji
Tutaj z pomocą przychodzą field_definitions, deklarowane na poziomie kolekcji. Zamieniają one niepisane ustalenia w ograniczenia weryfikowane przez API. Istnieją trzy ustawienia:
| Ustawienie | Efekt |
|---|---|
required: true | Każdy dokument musi zawierać te metadane |
unique: true | Dwa dokumenty nie mogą mieć tej samej wartości |
inject_into_chunk: true | Metadane są dodawane do indeksowanej treści |
Definicja łączy te ustawienia dla każdego pola z osobna:
{
"field_definitions": [
{
"name": "author",
"required": true,
"inject_into_chunk": true
},
{
"name": "document_id",
"required": true,
"unique": true
},
{
"name": "year",
"required": false,
"inject_into_chunk": true
}
]
}
Przeczytaj ten przykład jako politykę dotyczącą dokumentów: każdy dokument musi mieć autora i identyfikator, przy czym ten identyfikator należy tylko do jednego dokumentu – co blokuje duplikaty podczas ingestii – a rok pozostaje opcjonalny, aby nie odrzucać elementów bez daty.
Opcja zmieniająca trafność wyników
Spośród tych trzech ustawień tylko inject_into_chunk wpływa na jakość odpowiedzi i zasługuje na bliższe przyjrzenie się. Podczas indeksowania dokument jest dzielony na fragmenty (chunki), a włączenie tej opcji kopiuje wartość pola do każdego z nich.
Konkretnie, przy author: "Marie Dupont" i inject_into_chunk: true, każdy zaindeksowany fragment zawiera to nazwisko. Pytanie typu „Co Marie Dupont napisała o opóźnieniach w sieci?“ ma wtedy szansę trafić w sedno, ponieważ nazwisko pojawia się w przeszukiwanej treści. Bez injecji to samo pytanie opierałoby się wyłącznie na tekście raportu, gdzie autor mógłby pojawić się tylko na stronie tytułowej.
Włącz więc injecję dla pól niosących kontekst – autor, dział, rok, kategoria – a zostaw ją wyłączoną dla pól administracyjnych, takich jak wewnętrzny ID, data przesłania czy status walidacji, które jedynie wprowadziłyby szum.
Trzy sprawdzone schematy
Przydatne metadane nie wymyśla się w abstrakcji: wynikają one z pytań zadawanych bazie danych. Baza dokumentacji technicznej organizuje się wokół produktu i wersji, ponieważ pierwszym pytaniem użytkownika jest prawie zawsze „która wersja?“:
{
"fields": {
"product": "Grok API",
"version": "v1",
"type": "reference",
"language": "en"
}
}
Baza wiedzy HR rozumuje natomiast przez kategorię i datę wejścia w życie, ponieważ niewłaściwa odpowiedź to najczęściej uchylona polityka:
{
"fields": {
"category": "hr-policy",
"effective_date": "2026-01-01",
"department": "all",
"status": "active"
}
}
Wreszcie, baza prawna strukturyzuje się wokół stron, typu umowy i daty wygaśnięcia, co pozwala w jednym zapytaniu wyciągnąć umowy zbliżające się do końca ważności:
{
"fields": {
"contract_type": "vendor",
"party": "Acme Corp",
"expiration": "2027-06-30",
"jurisdiction": "France"
}
}
Utrzymywanie spójnego schematu
Spójność zawsze ginie tymi samymi kanałami, a kilka nawyków wystarczy, aby ją utrzymać. Ujednolić formaty nazw pól – snake_case, po angielsku, bez mieszania języków. Ogranicz ich liczbę: od pięciu do dziesięciu pól pokrywa większość potrzeb; powyżej tej liczby koszty utrzymania przewyższają zyski z trafności. Obchodź się z inject_into_chunk roztropnie, ponieważ każde injektowane pole powiększa chunki, a tym samym koszty przechowywania. Na koniec udokumentuj oczekiwany schemat dla każdej kolekcji w pliku dostępnym dla zespołu: gdy wiele osób go zasila, to ten plik, a nie pamięć twórcy, gwarantuje spójność.
Kluczowe wnioski
fieldswiąże z każdym dokumentem metadane w postaci par klucz-wartośćfield_definitionsna poziomie kolekcji definiują reguły: required, unique, inject_into_chunk- Opcja
inject_into_chunkpoprawia trafność wyszukiwania, dodając metadane do indeksowanej treści - Standaryzuj swoje schematy metadanych, aby utrzymać spójność kolekcji