Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Haku tiedostoista: Dokumenttien indeksointi ja kyselyt

Oppitunti 7 / 20 Kehittäjä
Tällä sivulla
  1. Haku tiedostoista: Dokumenttien indeksointi ja kyselyt
  2. Vektoritietovaraston luominen
  3. Tiedostojen lataaminen ja indeksointi
  4. Kysely tiedostohaulla
  5. Hakutulosten tarkastelu
  6. Haun konfigurointi
  7. Vektoritietovaraston elinkaaren hallinta
  8. Kokonaisesimerkki: Dokumenttiavustaja
  9. Keskeiset asiat

Haku tiedostoista: Dokumenttien indeksointi ja kyselyt

Tiedostohaku (File Search) antaa mallin selata yksityisiä dokumenttejasi. Lataat tiedostot vektoritietovarastoon, ja malli hakee niistä automaattisesti tietoa aina kun se tarvitsee spesifiä informaatiota. Tämä on RAG:n (Retrieval-Augmented Generation) perusta, joka on rakennettu suoraan OpenAI API:n sisään.

Vektoritietovaraston luominen

Vektoritietovarasto on tiedostohaun organisaatioryhmä, ja tässä valittu rakenne pysyy käytössäsi pitkään. Yksi ainoa varasto koko yritykselle on helppo hallinnoida, mutta se sekoittaa keskenään dokumentteja, joissa on toisistaan poikkeavia sanastoja, mikä heikentää osumien relevanssia. Erilliset varastot tiimeittäin tai toimialoittain vaativat hieman enemmän hallintaa, mutta tekevät jokaisestahausta merkittävästi tarkemman. Jos epäilet, erota ne: yhdistäminen myöhemmin on helpompaa kuin sotkun selvittäminen.

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

Tiedostojen lataaminen ja indeksointi

Indeksointi on asynkroninen prosessi, ja tämä on yleisin virhelähde ensimmäisellä kerralla: lataat tiedostot, teet kyselyn heti, ja malli vastaa löytäneensä nothing – ei siksi, että haku epäonnistui, vaan koska mitään ei ole vielä indeksoitu. Tarkista tila aina ennen kyselyä, kuten elinkaari-osiossa näytetään.

Muutama sana tiedostomuodoista: lista on laaja, mutta kaikki tiedostot eivät ole samanarvoisia. Tekstinkäsittelyohjelmalla luotu PDF purkautuu siististi; skannattu PDF ilman tekstikerrosta ei lisää mitään, sillä siinä ei kirjaimellisesti ole sanoja indeksoitavaksi.

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

Kysely tiedostohaulla

Kutsu on tarkoituksellisen suoraviivainen: määrität työkalun, esität kysymyksesi, ja malli päättää, haetaanko tietoa. Kaikki RAG-työ – paloitteleminen, vektorisointi, sijoittelu järjestykseen ja kontekstiin注入 – tapahtuu palvelimella. Tämä säästää huomattavasti aikaa käynnistyksessä, ja seuraava oppitunti kattaa asetukset, jotka sinun tulee tuntea, kun oletusarvot eivät riitä.

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)

Malli hakee automaattisesti dokumenteistasi ja muotoilee vastauksen löytämänsä sisällön perusteella.

Hakutulosten tarkastelu

Annotaatiot ovat se, mikä erottaa varmennettavan vastauksen pelkästä väittämästä. Näytä ne käyttäjillesi: sisäisessä tietokannassa kyky jäljittää tieto alkuperäiseen dokumenttiin muuttaa täysin järjestelmään kohdistuvan luottamuksen tasoa – ja auttaa sinua havaitsemaan tapaukset, joissa malli osui harhaan.

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

Haun konfigurointi

Tulosten määrä

Läpikäytävien kohtien määrän kasvattaminen ei mekaanisesti paranna vastausta. Yli kymmenen kohdan jälkeen heikosti relevantit otteet laimentavat hyviä ja kuluttavat laskutettavaa kontekstia. Nosta tätä arvoa vain, kun vastaus on näkyvästi puutteellinen, äläkä periaatteen vuoksi.

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

Metatietosuodatus

Metatiedot ovat eniten alikäytetty vipuvarsi tarkkuuden parantamiseksi. Suodatus vuoden, osaston tai dokumenttityypin perusteella ennen vektorihakua poistaa kohinan heti alussa, jonka sijoittelujärjestelyn muuten joutuisi seulomaan. Tämä mahdollistaa myös vastaamisen muotoon “nykyisen menettelyn mukaan” sen sijaan, että sekoitettaisiin kolme peräkkäistä versiota samasta dokumentista.

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

Yhdistelmäsuojaus

Yhdistä useita kriteereitä loogisilla operaattoreilla:

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

Vektoritietovaraston elinkaaren hallinta

Indeksoinnin seuranta

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

Vanhentuneiden tiedostojen poistaminen

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

Kokonaisesimerkki: Dokumenttiavustaja

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
    }

Keskeiset asiat

  • Luo vektoritietovarasto ja lataa tiedostosi ottaaksesi tiedostohaun käyttöön
  • Malli päättää itse, milloin dokumentteja haetaan
  • max_num_results ohjaa haun syvyyttä
  • Metatiedot ja suodattimet mahdollistavat kohdennetun haun
  • Seuraa indeksoinnin tilaa ennen kyselyjen tekemistä