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

Tfittxija ta' Fajls: Indizza u Ikkonsulta Dokumenti

Lezzjoni 7 / 20 Zviluppatur
F'din il-paġna
  1. Tfittxija ta’ Fajls: Indizza u Ikkonsulta Dokumenti
  2. Oħloq Ħażna Vettorjali
  3. Ittella’ u Indizza Fajls
  4. Ikkonsulta bit-Tfittxija ta’ Fajls
  5. Eżamina r-Riżultati tat-Tfittxija
  6. Ikkonfigura t-Tfittxija
  7. Immaniġġja ċ-Ċiklu tal-Ħajja tal-Ħażna Vettorjali
  8. Eżempju Sħiħ: Assistent tad-Dokumentazzjoni
  9. Punti Ewlenin

Tfittxija ta’ Fajls: Indizza u Ikkonsulta Dokumenti

It-Tfittxija ta’ Fajls tippermetti lill-mudell ifittex fid-dokumenti privati tiegħek. Inti ttella’ fajls f’ħażna vettorjali (vector store), u l-mudell jikkonsultawhom awtomatikament kull meta jkollu bżonn informazzjoni speċifika. Din hija l-bażi tar-RAG (Retrieval-Augmented Generation) mibnija direttament fl-API ta’ OpenAI.

Oħloq Ħażna Vettorjali

Il-ħażna vettorjali hija l-unità organizzattiva għat-Tfittxija ta’ Fajls, u l-istruttura li tagħżel hawnhekk se tibqa’ miegħek għal żmien twil. Ħażna waħda għall-kumpanija kollha hija faċli biex tiġi amministrata, iżda tħallat dokumenti b’vokabolarji mhux relatati, li tonqos ir-rilevanza. Ħżien separati skont it-tim jew id-dominju jeħtieġu ftit aktar ġestjoni, iżda jagħmlu kull tfittxija ferm aktar preċiża. Meta jkollok dubju, ifridhom: li tgħaqqadhom wara huwa aktar faċli milli tfixkel taħwida.

from openai import OpenAI

client = OpenAI()

# Create the vector store
vector_store = client.vector_stores.create(
    name="product-documentation"
)
print(f"Vector store created: {vector_store.id}")

Ittella’ u Indizza Fajls

L-indiċjar huwa asinkronu, u din hija l-aktar sors komuni ta’ żball fl-ewwel tentattiv: iżżid fajls, tikkonsulta minnufih, u l-mudell jgħid li ma sab xejn—mhux għax it-tfittxija falliet, iżda għax xejn ma kien ġie indizzat għadu. Dejjem iċċekkja l-istatus qabel ma tikkonsulta, kif muri fit-taqsima dwar iċ-ċiklu tal-ħajja.

Kelma dwar il-formati: il-lista hija wiesgħa, iżda mhux il-fajls kollha huma ugwali. PDF iġġenerat minn proċessur tal-kliem jiġi estratt b’mod nadif; PDF skannjat mingħajr saff ta’ test ma jżid xejn, peress li sempliċiment m’hemm l-ebda kelma biex tiġi indizzata.

import os

# Upload a single file
with open("user-guide.pdf", "rb") as f:
    file_obj = client.files.create(file=f, purpose="assistants")

# Attach to the vector store
client.vector_stores.files.create(
    vector_store_id=vector_store.id,
    file_id=file_obj.id
)

# Batch upload
folder = "./documentation/"
for filename in os.listdir(folder):
    path = os.path.join(folder, filename)
    if os.path.isfile(path):
        with open(path, "rb") as f:
            file_obj = client.files.create(file=f, purpose="assistants")
        client.vector_stores.files.create(
            vector_store_id=vector_store.id,
            file_id=file_obj.id
        )
        print(f"Indexed: {filename}")

Ikkonsulta bit-Tfittxija ta’ Fajls

Is-sejħa hija intenzjonalment sempliċi: tiddikjara l-għodda, tagħmel il-mistoqsija tiegħek, u l-mudell jiddeċiedi jekk ifittxix. Ix-xogħol kollu tar-RAG—il-qsim f’biċċiet (chunking), il-vetturizzazzjoni, il-klassifikazzjoni (ranking), u l-injezzjoni fil-kuntest—iseħħ fuq is-server. Dan iffranka ħin konsiderevoli fil-bidu, u l-lezzjoni li jmiss tkopri l-issettjar li għandek bżonn tkun taf meta d-defaults ma jkunux biżżejjed.

response = client.responses.create(
    model="gpt-5.6-terra",
    input="What is the refund procedure for premium clients?",
    tools=[{
        "type": "file_search",
        "vector_store_ids": [vector_store.id]
    }]
)

print(response.output_text)

Il-mudell awtomatikament ifittex fid-dokumenti tiegħek u jifformula tweġiba bbażata fuq il-kontenut li jsib.

Eżamina r-Riżultati tat-Tfittxija

L-annotazzjonijiet huma dak li jiddistingwi tweġiba verifikabbli minn sempliċi asserzjoni. Urihom lill-utenti tiegħek: fuq bażi ta’ għarfien interna, il-kapaċità li terġa’ lura għad-dokument oriġinali tbiddel kompletament il-livell ta’ fiduċja fis-sistema—u tgħinek tidentifika każijiet fejn il-mudell żbalja.

response = client.responses.create(
    model="gpt-5.6-terra",
    input="What SLAs are guaranteed in the contract?",
    tools=[{
        "type": "file_search",
        "vector_store_ids": [vector_store.id]
    }]
)

# Iterate through annotations
for item in response.output:
    if item.type == "message":
        for block in item.content:
            if hasattr(block, "annotations"):
                for ann in block.annotations:
                    if ann.type == "file_citation":
                        print(f"File: {ann.file_id}")
                        print(f"Position: {ann.start_index}-{ann.end_index}")

Ikkonfigura t-Tfittxija

Numru ta’ Riżultati

Li żżid in-numru ta’ passiġġi ma jtejjibx mekkanikament it-tweġiba. Wara madwar għaxra, estratti b’rilevanza dgħajfa jdillu dawk tajbin u jikkunsmaw kuntest fatturat. Żid dan il-valur biss meta t-tweġiba tkun viżibbilment mhux kompluta, mhux bħala kwistjoni ta’ prinċipju.

response = client.responses.create(
    model="gpt-5.6-terra",
    input="List all penalty clauses in the contract",
    tools=[{
        "type": "file_search",
        "vector_store_ids": [vector_store.id],
        "max_num_results": 20  # Default: 5, max: 50
    }]
)

Filtrazzjoni tal-Metadata

Il-metadata hija l-aktar leva sottovalutata għall-preċiżjoni. Il-filtrazzjoni skont is-sena, id-dipartiment, jew it-tip ta’ dokument qabel it-tfittxija vettorjali telimina n-niżla minn qabel li l-klassifikazzjoni kieku kellha tiffiltra. Dan jippermettilek ukoll twieġeb “skont il-proċedura attwali” minflok ma tħallat tliet verżjonijiet suċċessivi tal-istess dokument.

# Upload with metadata
with open("contract-2026.pdf", "rb") as f:
    file_obj = client.files.create(file=f, purpose="assistants")

client.vector_stores.files.create(
    vector_store_id=vector_store.id,
    file_id=file_obj.id,
    attributes={
        "doc_type": "contract",
        "year": 2026,
        "client": "acme-corp"
    }
)

# Filtered search
response = client.responses.create(
    model="gpt-5.6-terra",
    input="What is the due date?",
    tools=[{
        "type": "file_search",
        "vector_store_ids": [vector_store.id],
        "filters": {
            "type": "eq",
            "key": "doc_type",
            "value": "contract"
        }
    }]
)

Filtri Komposti

Għaqqad kriterji multipli bl-użu ta’ operaturi loġiċi:

response = client.responses.create(
    model="gpt-5.6-terra",
    input="Summarize contractual obligations for 2026",
    tools=[{
        "type": "file_search",
        "vector_store_ids": [vector_store.id],
        "filters": {
            "type": "and",
            "filters": [
                {"type": "eq", "key": "doc_type", "value": "contract"},
                {"type": "gte", "key": "year", "value": 2026}
            ]
        }
    }]
)

Immaniġġja ċ-Ċiklu tal-Ħajja tal-Ħażna Vettorjali

Monitoraġġ tal-Indiċjar

# Check vector store status
vs = client.vector_stores.retrieve(vector_store.id)
print(f"Status: {vs.status}")
print(f"Files: {vs.file_counts.completed} indexed, "
      f"{vs.file_counts.in_progress} in progress, "
      f"{vs.file_counts.failed} failed")

Neħħi Fajls Obsoleti

# List files in the vector store
files = client.vector_stores.files.list(vector_store.id)
for f in files.data:
    print(f"{f.id} - {f.status}")

# Detach a file
client.vector_stores.files.delete(
    vector_store_id=vector_store.id,
    file_id="file_abc123"
)

Eżempju Sħiħ: Assistent tad-Dokumentazzjoni

def documentation_assistant(question: str, vs_id: str) -> dict:
    """Assistant that answers based on internal documentation."""
    response = client.responses.create(
        model="gpt-5.6-terra",
        instructions=(
            "You are a documentation assistant. Answer solely based on the "
            "provided documents. If the information is not in the documents, "
            "state that clearly. Cite your sources."
        ),
        input=question,
        tools=[{
            "type": "file_search",
            "vector_store_ids": [vs_id],
            "max_num_results": 10
        }]
    )

    return {
        "answer": response.output_text,
        "model": response.model,
        "tokens": response.usage.total_tokens
    }

Punti Ewlenin

  • Oħloq ħażna vettorjali u ittella’ l-fajls tiegħek biex tattivaw it-Tfittxija ta’ Fajls
  • Il-mudell jiddeċiedi waħdu meta jfittex fid-dokumenti
  • max_num_results jikkontrolla l-fond tat-tfittxija
  • Il-metadata u l-filtri jippermettu tfittxija mmirata
  • Immonitorja l-istatus tal-indiċjar qabel ma tikkonsulta