Przejdź do głównej treści
Polski— Wybierz język
Menu

Metadane i pola niestandardowe

Lekcja 7 z 16 Zaktualizowano 29 lipca 2026 Programista
Na tej stronie
  1. Kontekst, którego dokument nie zawiera
  2. Dołączanie pól do dokumentu
  3. Ustalanie reguł na poziomie kolekcji
  4. Opcja zmieniająca trafność wyników
  5. Trzy sprawdzone schematy
  6. Utrzymywanie spójnego schematu
  7. Kluczowe wnioski

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:

UstawienieEfekt
required: trueKażdy dokument musi zawierać te metadane
unique: trueDwa dokumenty nie mogą mieć tej samej wartości
inject_into_chunk: trueMetadane 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

  • fields wiąże z każdym dokumentem metadane w postaci par klucz-wartość
  • field_definitions na poziomie kolekcji definiują reguły: required, unique, inject_into_chunk
  • Opcja inject_into_chunk poprawia trafność wyszukiwania, dodając metadane do indeksowanej treści
  • Standaryzuj swoje schematy metadanych, aby utrzymać spójność kolekcji