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

Pretraživanje datoteka: indeksiranje i upiti nad dokumentima

Lekcija 7 od 20 Programer
Na ovoj stranici
  1. Pretraživanje datoteka: indeksiranje i upiti nad dokumentima
  2. Stvaranje vektorske pohrane
  3. Učitavanje i indeksiranje datoteka
  4. Upiti uz pretraživanje datoteka
  5. Pregled rezultata pretraživanja
  6. Konfiguriranje pretraživanja
  7. Upravljanje životnim ciklusom vektorske pohrane
  8. Potpuni primjer: asistent za dokumentaciju
  9. Ključne točke

Pretraživanje datoteka: indeksiranje i upiti nad dokumentima

Pretraživanje datoteka omogućuje modelu da pretražuje tvoje privatne dokumente. Datoteke učitavaš u vektorsku pohranu (vector store), a model ih automatski ispituje kad god mu zatrebaju specifične informacije. To je temelj RAG-a (Retrieval-Augmented Generation) ugrađen izravno u OpenAI API.

Stvaranje vektorske pohrane

Vektorska pohrana organizacijska je jedinica za pretraživanje datoteka, a struktura koju ovdje odabereš ostat će s tobom dugo vremena. Jedna pohrana za cijelu tvrtku jednostavna je za administraciju, ali miješa dokumente s nepovezanim rječnicima, što smanjuje relevantnost rezultata. Odvojene pohrane po timovima ili domenama zahtijevaju malo više upravljanja, ali čine svako pretraživanje znatno preciznijim. Ako nisi siguran, razdvoj ih: kasnije spajanje lakše je od raspletavanja nereda.

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

Učitavanje i indeksiranje datoteka

Indeksiranje je asinkrono, a to je najčešći izvor pogrešaka pri prvom pokušaju: dodaš datoteke, odmah pokreneš upit, a model kaže da ništa nije pronašao – ne zato što je pretraživanje propalo, već zato što još ništa nije indeksirano. Uvijek provjeri status prije pokretanja upita, kako je prikazano u odjeljku o životnom ciklusu.

Što se tiče formata: popis je širok, ali nisu sve datoteke jednake. PDF generiran iz tekstualnog procesora čisto se ekstrahira; skenirani PDF bez tekstualnog sloja ne dodaje ništa jer doslovno nema riječi za indeksiranje.

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

Upiti uz pretraživanje datoteka

Poziv je namjerno jednostavan: deklariraš alat, postaviš pitanje, a model odlučuje treba li pretraživati. Sav RAG posao – cijepanje na dijelove, vektorizacija, rangiranje i ubacivanje u kontekst – odvija se na poslužitelju. To štedi znatno vrijeme pri pokretanju, a sljedeća lekcija pokriva postavke koje moraš znati kada zadane vrijednosti nisu dovoljne.

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)

Model automatski pretražuje tvoje dokumente i formulira odgovor na temelju sadržaja koji pronađe.

Pregled rezultata pretraživanja

Anotacije su ono što razlikuje provjerljiv odgovor od pukog tvrdnje. Izloži ih svojim korisnicima: u internoj bazi znanja mogućnost praćenja izvora do originalnog dokumenta potpuno mijenja razinu povjerenja u sustav – i pomaže ti uočiti slučajeve gdje je model promašio cilj.

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

Konfiguriranje pretraživanja

Broj rezultata

Povećanje broja odlomaka mehanički ne poboljšava odgovor. Iznad desetak, slabo relevantni isječci razrjeđuju dobre i troše naplaćeni kontekst. Podigni ovu vrijednost samo kada je odgovor vidljivo nepotpun, a ne kao stvar principa.

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

Filtriranje metapodataka

Metapodaci su najnedovoljno iskorištena poluga za preciznost. Filtriranje po godini, odjelu ili vrsti dokumenta prije vektorskog pretraživanja unaprijed uklanja šum koji bi inače morao filtrirati algoritam rangiranja. To ti također omogućuje odgovoriti „prema trenutnom postupku“ umjesto miješanja triju uzastopnih verzija istog dokumenta.

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

Složeni filtri

Kombiniraj više kriterija koristeći logičke operatore:

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

Upravljanje životnim ciklusom vektorske pohrane

Praćenje indeksiranja

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

Uklanjanje zastarjelih datoteka

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

Potpuni primjer: asistent za dokumentaciju

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
    }

Ključne točke

  • Stvori vektorsku pohranu i učitaj svoje datoteke kako bi omogućio/la pretraživanje datoteka
  • Model samostalno odlučuje kada treba pretraživati dokumente
  • max_num_results kontrolira dubinu pretraživanja
  • Metapodaci i filtri omogućuju ciljano pretraživanje
  • Prati status indeksiranja prije pokretanja upita