Preskoči na glavni sadržaj
Hrvatski— Odaberite jezik
Izbornik

Metapodaci i prilagođena polja

Lekcija 7 od 16 Ažurirano 29. srpnja 2026. Programer
Na ovoj stranici
  1. Kontekst koji dokument ne nosi
  2. Povezivanje polja s dokumentom
  3. Postavljanje pravila na razini kolekcije
  4. Opcija koja mijenja relevantnost
  5. Tri provjerene sheme
  6. Održavanje dosljedne sheme
  7. Ključne točke

Kontekst koji dokument ne nosi

Tehničko izvješće ne sadrži uvijek u samom tekstu ime autora, godinu nastanka ili razinu povjerljivosti. Ipak, upravo ti detalji čine razliku između pretraživanja koje pronalazi pravi dokument i onoga koje vraća tri nebitna rezultata. Sustav metapodataka kolekcije služi upravo toj svrsi: povezivanju strukturiranih informacija sa svakim dokumentom koje pretraživanje može iskoristiti, a ti filtrirati.

Povezivanje polja s dokumentom

Prilikom dodavanja dokumenta, parametar fields prihvaća parove ključ-vrijednost koje slobodno definiraš:

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 ovoj razini ne nameće se nikakva shema: imena polja biraš sam. Ta sloboda djeluje ugodno kod prvog dokumenta, ali postaje problem kod stotog, kada u istoj kolekciji istovremeno postoje author, auteur i Author, a nijedan filtar ne radi.

Postavljanje pravila na razini kolekcije

Ovdje nastupaju field_definitions, deklarirane na razini kolekcije. One pretvaraju usmeni dogovor u ograničenje koje API provjerava. Postoje tri postavke:

PostavkaUčinak
required: trueSvaki dokument mora sadržavati ovaj metapodatak
unique: trueDva dokumenta ne mogu dijeliti istu vrijednost
inject_into_chunk: trueMetapodatak se dodaje u indeksirani sadržaj

Definicija kombinira ove postavke polje po polje:

{
  "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
    }
  ]
}

Ovaj primjer čitaj kao politiku za dokumente: svaki dokument ima autora i ID, taj ID pripada samo jednom dokumentu – što blokira duplikate pri unosu – dok godina ostaje opcionalna kako bi se izbjeglo odbacivanje nedatiranih stavki.

Opcija koja mijenja relevantnost

Od ove tri postavke, samo inject_into_chunk utječe na kvalitetu odgovora i zaslužuje detaljniji pogled. Tijekom indeksiranja, dokument se dijeli na fragmente – chunkove – a omogućivanjem ove opcije vrijednost polja kopira se u svaki od njih.

Konkretno, uz author: "Marie Dupont" i inject_into_chunk: true, svaki indeksirani chunk nosi to ime. Pitanje poput „Što je Marie Dupont napisala o kašnjenju u mreži?“ tada ima šanse pogoditi cilj, jer se ime pojavljuje u pretraživanom sadržaju. Bez injektiranja, isto se pitanje oslanja samo na tekst izvješća, gdje se autor možda pojavljuje samo na naslovnici.

Stoga omogući injektiranje za polja koja nose kontekst – autor, odjel, godina, kategorija – a ostavi ga onemogućenim za administrativna polja poput internog ID-a, datuma prijenosa ili statusa validacije, koja bi samo dodala šum.

Tri provjerene sheme

Korisni metapodaci ne izmišljaju se u apstrakciji: proizlaze iz pitanja koja se postavljaju bazi podataka. Baza tehničke dokumentacije organizira se oko proizvoda i verzije, jer je prvo pitanje korisnika gotovo uvijek „koja verzija?“:

{
  "fields": {
    "product": "Grok API",
    "version": "v1",
    "type": "reference",
    "language": "en"
  }
}

Baza znanja za ljudske potencijale, s druge strane, razmišlja po kategorijama i datumu stupanja na snagu, jer je pogrešan odgovor tamo najčešće ukinuta politika:

{
  "fields": {
    "category": "hr-policy",
    "effective_date": "2026-01-01",
    "department": "all",
    "status": "active"
  }
}

Konačno, pravna baza strukturira se oko strana, vrste ugovora i isteka, što ti omogućuje da jednim upitom izvučeš ugovore kojima se bliži istek:

{
  "fields": {
    "contract_type": "vendor",
    "party": "Acme Corp",
    "expiration": "2027-06-30",
    "jurisdiction": "France"
  }
}

Održavanje dosljedne sheme

Dosljednost se uvijek gubi na iste načine, a nekoliko navika dovoljno je za njezino održavanje. Standardiziraj formate imena polja – snake_case, na engleskom, bez miješanja jezika. Ograniči njihov broj: pet do deset polja pokriva većinu potreba; iznad toga, troškovi održavanja nadmašuju dobitke u relevantnosti. Rukuj opcijom inject_into_chunk s razboritošću, jer svako injektirano polje povećava veličinu chunkova, a time i troškove pohrane. Naposljetku, dokumentiraj očekivanu shemu za svaku kolekciju u datoteci dostupnoj cijelom timu: kada je više ljudi hrani, ta datoteka, a ne creatorovo sjećanje, jamči dosljednost.

Ključne točke

  • fields povezuje metapodatke u obliku parova ključ-vrijednost sa svakim dokumentom
  • field_definitions na razini kolekcije definiraju pravila: required, unique, inject_into_chunk
  • Opcija inject_into_chunk poboljšava relevantnost pretraživanja dodavanjem metapodataka u indeksirani sadržaj
  • Standardiziraj svoje sheme metapodataka kako bi održao dosljednost kolekcije