Lähe põhisisu juurde
Eesti— Vali keel
Menüü

Failide otsing: dokumentide indekseerimine ja päringud

Õppetund 7 / 20 Arendajatele
Sellel lehel
  1. Failide otsing: dokumentide indekseerimine ja päringud
  2. Vektorpoee loomine
  3. Failide üleslaadimine ja indekseerimine
  4. Päring failide otsinguga
  5. Otsingutulemuste uurimine
  6. Otsingu konfigureerimine
  7. Vektorpoee elutsükli haldamine
  8. Täielik näide: dokumentatsiooni assistent
  9. Peamised punktid

Failide otsing: dokumentide indekseerimine ja päringud

Failide otsing võimaldab mudelil sirvida sinu privaatseid dokumente. Laadid failid vektorpoodi üles ja mudel küsitleb neid automaatselt iga kord, kui tal on vaja spetsiifilist teavet. See on RAG-i (Retrieval-Augmented Generation) alustala, mis on sisse ehitatud otse OpenAI API-sse.

Vektorpoee loomine

Vektorpood on failide otsingu organisatsiooniline üksus ja siin valitud struktuur jääb sinuga pikaks ajaks. Üksainus pood kogu ettevõtte jaoks on lihtne hallata, kuid segab omavahel seotumata sõnavaraga dokumente, mis halvendab asjakohasust. Eraldi poed meeskonniti või valdkonniti nõuavad veidi rohkem haldust, kuid muudavad iga otsingu oluliselt täpsemaks. Kui kahtled, eralda need: hiljem on lihtsam ühendada kui segadust lahti harutada.

from openai import OpenAI

client = OpenAI()

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

Failide üleslaadimine ja indekseerimine

Indekseerimine on asünkroonne ja see on esimesel korral kõige levinum veaallikas: laadid failid üles, esitad kohe päringu ja mudel vastab, et midagi ei leidnud – mitte seetõttu, et otsing ebaõnnestus, vaid seetõttu, et midagi polnud veel indekseeritud. Enne päringu esitamist kontrolli alati olekut, nagu on näidatud elutsükli osas.

Märkus vormingute kohta: nimekiri on lai, kuid kõik failid ei ole võrdsed. Tekstitöötlejast genereeritud PDF eraldub puhtalt; skaneeritud PDF ilma tekstikihita ei lisa midagi, kuna seal pole sõna otseses mõttes ühtegi sõna, mida indekseerida.

import os

# Laadi üles üks fail
with open("user-guide.pdf", "rb") as f:
    file_obj = client.files.create(file=f, purpose="assistants")

# Lisa vektorpoodi
client.vector_stores.files.create(
    vector_store_id=vector_store.id,
    file_id=file_obj.id
)

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

Päring failide otsinguga

Väljakutse on tahtlikult lihtne: deklareerid tööriista, esitad oma küsimuse ja mudel otsustab, kas otsida. Kogu RAG-i töö – tükeldamine, vektoriseerimine, järjestamine ja konteksti sisestamine – toimub serveris. See säästab käivitamisel palju aega ja järgmises tunnis käsitleme seadeid, mida pead teadma, kui vaikimisi väärtustest ei piisa.

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)

Mudel otsib automaatselt sinu dokumente ja formuleerib vastuse leitud sisu põhjal.

Otsingutulemuste uurimine

Annotatsioonid on see, mis eristab kontrollitavat vastust pelgast väitest. Tee need oma kasutajatele nähtavaks: siseteadmiste baasi puhul muudab võimalus algdokumendini tagasi jõuda täielikult usaldustaset süsteemi vastu – ja aitab tuvastada juhtumeid, kus mudel eksis.

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

# Itereeri annotatsioonide üle
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}")

Otsingu konfigureerimine

Tulemuste arv

Lõikude arvu suurendamine ei paranda vastust mehaaniliselt. Umbes kümnest enam hakkavad nõrgalt asjakohased väljavõtted lahjendama häid ja tarbivad arveldatavat konteksti. Tõsta seda väärtust ainult siis, kui vastus on nähtavalt puudulik, mitte printsiibi pärast.

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

Metaandmete filtreerimine

Metaandmed on täpsuse jaoks kõige alakasutatud hoob. Filtreerimine aasta, osakonna või dokumendi tüübi järgi enne vektorotsingut kõrvaldab müra juba alguses, mida muidu peaks järjestamine välja filtreerima. See võimaldab vastata ka „vastavalt kehtivale protseduurile“, segamata sama dokumendi kolme järjestikust versiooni.

# Laadi üles metaandmetega
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"
    }
)

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

Liitfiltrid

Kombineeri mitut kriteeriumi loogiliste operaatorite abil:

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

Vektorpoee elutsükli haldamine

Indekseerimise jälgimine

# Kontrolli vektorpoee olekut
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")

Aegunud failide eemaldamine

# Loetle failid vektorpoes
files = client.vector_stores.files.list(vector_store.id)
for f in files.data:
    print(f"{f.id} - {f.status}")

# Eemalda fail
client.vector_stores.files.delete(
    vector_store_id=vector_store.id,
    file_id="file_abc123"
)

Täielik näide: dokumentatsiooni assistent

def documentation_assistant(question: str, vs_id: str) -> dict:
    """Assistent, mis vastab sisese dokumentatsiooni põhjal."""
    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
    }

Peamised punktid

  • Loo vektorpood ja laadi oma failid üles, et võimaldada failide otsingut
  • Mudel otsustab ise, millal dokumente otsida
  • max_num_results kontrollib otsingu sügavust
  • Metaandmed ja filtrid võimaldavad sihipärast otsingut
  • Jälgi indekseerimise olekut enne päringu esitamist