Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

Metadejta u Qasam Personalizzat

Lezzjoni 7 / 16 Aġġornat 29 ta’ Lulju 2026 Zviluppatur
F'din il-paġna
  1. Il-kuntest li d-dokument ma jġorrx
  2. Iرفiq oqsma ma’ dokument
  3. Stabbiliment ta’ regoli fil-livell tal-kollezzjoni
  4. L-għażla li tbiddel ir-rilevanza
  5. Tliet skemi ppruvati
  6. Żamma ta’ skema konsistenti
  7. Punti Ewlenin

Il-kuntest li d-dokument ma jġorrx

Rapport tekniku mhux dejjem jinkludi l-isem tal-awtur, is-sena li fih inkiteb, jew il-livell ta’ kunfidenzjalità tiegħu fit-test prinċipali. Madankollu, dawn id-dettalji jagħmlu d-differenza bejn tfittxija li ssib id-dokument it-tajjeb u waħda li tirritorna tlieta mhux rilevanti. Is-sistema tal-metadejta tal-kollezzjoni sservi eżattament dan l-għan: li tassosja informazzjoni strutturata ma’ kull dokument li t-tfittxija tista’ tisfrutta u li inti tista’ tiffiltra skontha.

Iرفiq oqsma ma’ dokument

Meta żżid dokument, il-parametru fields jaċċetta pari ta’ ċavetta-valur li tiddefinixxi liberament:

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"
    }
)

L-ebda skema ma tiġi infurzata f’dan il-livell: l-ismijiet tal-oqsma huma għalik biex tagħżilhom. Din il-libertà tħossok komdu għall-ewwel dokument u ssir problema bil-mija, meta author, auteur, u Author jikkoegżistu fl-istess kollezzjoni mingħajr ma jaħdem ebda filtru.

Stabbiliment ta’ regoli fil-livell tal-kollezzjoni

Hawnhekk tidħol field_definitions, iddikjarata fuq il-kollezzjoni. Dawn ibiddlu konvenzjoni verbali f’restrizzjoni vverifikata mill-API. Jeżistu tliet settings:

SettingEffett
required: trueKull dokument irid ikollu din il-metadejta
unique: trueŻewġ dokumenti ma jistgħux jaqsmu l-istess valur
inject_into_chunk: trueIl-metadejta tiżdied mal-kontenut indiċjat

Definizzjoni tgħaqqad dawn is-settings qasam b’qasam:

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

Aqra dan l-eżempju bħala politika tad-dokumenti: kull dokument għandu awtur u ID, dik l-ID tappartjeni għal dokument wieħed biss—li jimblokaw id-duplikati waqt l-ingestjoni—u s-sena tibqa’ opzjonali biex tiġi evitata r-rifjut ta’ oġġetti mingħajr data.

L-għażla li tbiddel ir-rilevanza

Minn dawn it-tliet settings, inject_into_chunk hija l-unika waħda li taffettwa l-kwalità tat-tweġiba, u tistħoqqilha ħarsa eqreb. Waqt l-indiċjar, dokument jinqasam f’frammenti—chunks—u l-attivazzjoni ta’ din l-għażla tikkopja l-valur tal-qasam f’kull wieħed minnhom.

Konkretament, b’author: "Marie Dupont" u inject_into_chunk: true, kull chunk indiċjat iġorr dan l-isem. Mistoqsija bħal “X’kitbet Marie Dupont dwar il-latency tan-netwerk?” imbagħad ikollha ċans li tolqot il-mira, peress li l-isem jidher fil-kontenut ifittex. Mingħajr injezzjoni, l-istess mistoqsija tiddependi biss fuq it-test tar-rapport, fejn l-awtur jista’ jidher biss fil-paġna tal-qoxra.

Għalhekk, attiva l-injezzjoni għal oqsma li jġorru kuntest—awtur, dipartiment, sena, kategorija—u ħalliha diżattivata għal oqsma amministrattivi bħal ID interna, data tat-tlugħ, jew status ta’ validazzjoni, li kieku biss iżidu storbju.

Tliet skemi ppruvati

Metadejta utli ma tinventax fl-astratt: toriġina mill-mistoqsijiet magħmula lid-database. Bażi ta’ dokumentazzjoni teknika torganizza ruħha madwar il-prodott u l-verżjoni, peress li l-ewwel mistoqsija tal-utent hija kważi dejjem “liema verżjoni?”:

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

Bażi ta’ għarfien tal-HR, madankollu, taħseb bil-kategorija u d-data effettiva, peress li t-tweġiba ħażina hemmhekk hija l-aktar spiss politika mħassra:

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

Fl-aħħar nett, bażi legali tistruttura ruħha madwar il-partijiet, it-tip ta’ kuntratt, u l-iskadenza, li tippermettilek tiġbed ftehimiet li qed jersqu lejn l-iskadenza f’mistoqsija waħda:

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

Żamma ta’ skema konsistenti

Il-konsistenza dejjem tintilef permezz tal-istess kanali, u ftit drawwiet biżżejjed biex tinżamm. Istandardizza l-formati tal-ismijiet tal-oqsma—snake_case, bl-Ingliż, mingħajr ma tħallat lingwi. Illimita n-numru tagħhom: ħames sa għaxar oqsma jkopru l-biċċa l-kbira tal-ħtiġijiet; lil hinn minn hekk, l-ispejjeż tal-manutenzjoni jisbu l-gwadann fir-rilevanza. Immaniġġja inject_into_chunk b’dixxerniment, peress li kull qasam injettat jikber iċ-chunks u għalhekk l-ispejjeż tal-ħażna. Fl-aħħar nett, iddokumenta l-iskema mistennija għal kull kollezzjoni f’fajl aċċessibbli għat-tim: ladarba diversi nies jipprovduh, dak il-fajl, u mhux il-memorja tal-ħallieq, jiggarantixxi l-konsistenza.

Punti Ewlenin

  • fields jassosja metadejta ta’ pari ċavetta-valur ma’ kull dokument
  • field_definitions fil-livell tal-kollezzjoni jiddefinixxu r-regoli: required, unique, inject_into_chunk
  • L-għażla inject_into_chunk ittejjeb ir-rilevanza tat-tfittxija billi żżid il-metadejta mal-kontenut indiċjat
  • Istandardizza l-iskemi tal-metadejta tiegħek biex iżżomm il-konsistenza tal-kollezzjoni