Přejít na hlavní obsah
Čeština— Vyberte jazyk
Menu

Vyhledávání souborů: Indexace a dotazování dokumentů

Lekce 7 z 20 Vývojář
Na této stránce
  1. Vyhledávání souborů: Indexace a dotazování dokumentů
  2. Vytvoření úložiště vektorů
  3. Nahrávání a indexování souborů
  4. Dotazování s využitím vyhledávání souborů
  5. Prozkoumání výsledků vyhledávání
  6. Konfigurace vyhledávání
  7. Správa životního cyklu úložiště vektorů
  8. Kompletní příklad: Asistent pro dokumentaci
  9. Klíčové poznatky

Vyhledávání souborů: Indexace a dotazování dokumentů

Vyhledávání souborů umožňuje modelu prohledávat vaše soukromé dokumenty. Nahrajete soubory do úložiště vektorů a model je automaticky dotazuje pokaždé, když potřebuje konkrétní informace. Toto je základ RAG (Retrieval-Augmented Generation) zabudovaný přímo do API OpenAI.

Vytvoření úložiště vektorů

Úložiště vektorů je organizační jednotkou pro vyhledávání souborů a struktura, kterou si zde zvolíte, vás bude doprovázet dlouhou dobu. Jediné úložiště pro celou společnost se snadno spravuje, ale mísí dokumenty s nesouvisející slovní zásobou, což snižuje relevanci výsledků. Oddělená úložiště podle týmů nebo domén vyžadují o něco více správy, ale činí každé vyhledávání výrazně přesnějším. Pokud váháte, oddělte je: pozdější sloučení je snazší než rozmotávání nepořádku.

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

Nahrávání a indexování souborů

Indexování je asynchronní proces a toto je nejčastější zdroj chyb při prvním pokusu: nahrajete soubory, okamžitě položíte dotaz a model odpoví, že nic nenašel – ne proto, že by vyhledávání selhalo, ale protože ještě nic nebylo zaindexováno. Před dotazováním vždy zkontrolujte stav, jak je popsáno v sekci o životním cyklu.

Pár slov k formátům: seznam je široký, ale ne všechny soubory jsou stejné. PDF vygenerované z textového procesoru se čistě extrahuje; naskenované PDF bez textové vrstvy nepřidá nic, protože doslova neobsahuje žádná slova k indexaci.

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

Dotazování s využitím vyhledávání souborů

Volání je záměrně jednoduché: deklarujete nástroj, položíte otázku a model se rozhodne, zda má provést vyhledávání. Veškerá práce spojená s RAG – rozdělování na části (chunking), vektorizace, hodnocení relevance a vkládání do kontextu – probíhá na serveru. To šetří considerable čas při startu a další lekce pokrývá nastavení, která potřebujete znát, když výchozí hodnoty nestačí.

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 automaticky prohledá vaše dokumenty a formulovat odpověď na základě nalezeného obsahu.

Prozkoumání výsledků vyhledávání

Anotace jsou tím, co odlišuje ověřitelnou odpověď od pouhého tvrzení. Zpřístupněte je svým uživatelům: u interní znalostní báze schopnost dohledat původní dokument zcela mění míru důvěry v systém – a pomáhá vám odhalit případy, kdy se model minul cílem.

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

Konfigurace vyhledávání

Počet výsledků

Zvyšování počtu úryvků mechanicky nezlepšuje odpověď. Přibližně nad deset začnou slabě relevantní excerpta ředit ty dobré a spotřebovávat účtovaný kontext. Tuto hodnotu zvyšujte pouze tehdy, když je odpověď viditelně neúplná, nikoliv jako věc principu.

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

Filtrace metadat

Metadata jsou nejvíce podceňovanou pákou pro přesnost. Filtrace podle roku, oddělení nebo typu dokumentu před vektorovým vyhledáváním eliminuje šum již na začátku, který by jinak musel filtrovat algoritmus hodnocení relevance. Umožňuje vám také odpovědět „podle aktuálního postupu“, aniž byste míchali tři po sobě jdoucí verze stejného dokumentu.

# 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žené filtry

Kombinujte více kritérií pomocí logických operátorů:

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

Správa životního cyklu úložiště vektorů

Monitorování indexace

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

Odstraňování zastaralých souborů

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

Kompletní příklad: Asistent pro dokumentaci

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
    }

Klíčové poznatky

  • Vytvořte úložiště vektorů a nahrajte své soubory, abyste povolili vyhledávání souborů.
  • Model se sám rozhoduje, kdy má dokumenty prohledat.
  • max_num_results řídí hloubku vyhledávání.
  • Metadata a filtry umožňují cílené vyhledávání.
  • Před dotazováním monitorujte stav indexace.