Przejdź do głównej treści
Polski— Wybierz język
Menu

Wyszukiwanie plików: indeksowanie i odpytywanie dokumentów

Lekcja 7 z 20 Programista
Na tej stronie
  1. Wyszukiwanie plików: indeksowanie i odpytywanie dokumentów
  2. Tworzenie magazynu wektorowego
  3. Przesyłanie i indeksowanie plików
  4. Odpytywanie z wykorzystaniem wyszukiwania plików
  5. Analiza wyników wyszukiwania
  6. Konfiguracja wyszukiwania
  7. Zarządzanie cyklem życia magazynu wektorowego
  8. Kompletny przykład: Asystent dokumentacji
  9. Kluczowe wnioski

Wyszukiwanie plików: indeksowanie i odpytywanie dokumentów

Funkcja File Search pozwala modelowi przeszukiwać Twoje prywatne dokumenty. Przesyłasz pliki do magazynu wektorowego, a model automatycznie je odpytuje, gdy tylko potrzebuje konkretnych informacji. To fundament architektury RAG wbudowany bezpośrednio w API OpenAI.

Tworzenie magazynu wektorowego

Magazyn wektorowy to jednostka organizacyjna dla funkcji File Search, a wybrana przez Ciebie struktura pozostanie z Tobą na długo. Pojedynczy magazyn dla całej firmy jest łatwy w administracji, ale miesza dokumenty o niezwiązanej ze sobą terminologii, co obniża trafność wyników. Rozdzielenie magazynów według zespołów lub domen wymaga nieco więcej zarządzania, ale sprawia, że każde wyszukiwanie jest znacznie precyzyjniejsze. W razie wątpliwości rozdzielaj je: scalenie później jest łatwiejsze niż rozplątywanie bałaganu.

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

Przesyłanie i indeksowanie plików

Indeksowanie jest procesem asynchronicznym i to najczęstsze źródło błędów przy pierwszej próbie: dodajesz pliki, natychmiast zadajesz pytanie, a model odpowiada, że nic nie znalazł – nie dlatego, że wyszukiwanie zawiodło, ale dlatego, że nic jeszcze nie zostało zaindeksowane. Zawsze sprawdzaj status przed odpytywaniem, jak pokazano w sekcji dotyczącej cyklu życia.

Kilka słów o formatach: lista jest szeroka, ale nie wszystkie pliki są sobie równe. PDF wygenerowany z edytora tekstu ekstrahuje się czysto; zeskanowany PDF bez warstwy tekstowej nic nie wnosi, ponieważ dosłownie nie ma w nim słów do zaindeksowania.

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

Odpytywanie z wykorzystaniem wyszukiwania plików

Wywołanie jest celowo proste: deklarujesz narzędzie, zadajesz pytanie, a model decyduje, czy przeprowadzić wyszukiwanie. Cała praca związana z RAG – dzielenie na fragmenty, wektoryzacja, ranking i wstrzykiwanie do kontekstu – odbywa się po stronie serwera. Oszczędza to sporo czasu przy starcie, a następna lekcja omawia ustawienia, które musisz znać, gdy domyślne wartości nie wystarczają.

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 automatycznie przeszukuje Twoje dokumenty i formułuje odpowiedź na podstawie znalezionych treści.

Analiza wyników wyszukiwania

Adnotacje to właśnie to, co odróżnia odpowiedź weryfikowalną od zwykłego twierdzenia. Udostępniaj je swoim użytkownikom: w przypadku wewnętrznej bazy wiedzy możliwość cofnięcia się do oryginalnego dokumentu całkowicie zmienia poziom zaufania do systemu – i pomaga Ci wykryć przypadki, w których model się pomylił.

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

Konfiguracja wyszukiwania

Liczba wyników

Zwiększanie liczby fragmentów nie poprawia mechanicznie odpowiedzi. Powyżej dziesięciu lub około tyle słabo trafne fragmenty rozcieńczają te dobre i zużywają płatny kontekst. Podnoś tę wartość tylko wtedy, gdy odpowiedź jest widocznie niekompletna, a nie jako zasadę ogólną.

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

Filtrowanie metadanych

Metadane to najczęściej niedoceniany dźwignia precyzji. Filtrowanie według roku, działu lub typu dokumentu przed wyszukiwaniem wektorowym eliminuje szum z góry, który w przeciwnym razie musiałby być odfiltrowany przez ranking. Pozwala to również odpowiadać „zgodnie z aktualną procedurą“, zamiast mieszać trzy kolejne wersje tego samego 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"
        }
    }]
)

Filtry złożone

Łącz wiele kryteriów za pomocą operatorów logicznych:

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

Zarządzanie cyklem życia magazynu wektorowego

Monitorowanie indeksowania

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

Usuwanie przestarzałych plików

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

Kompletny przykład: Asystent dokumentacji

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
    }

Kluczowe wnioski

  • Utwórz magazyn wektorowy i prześlij do niego pliki, aby włączyć funkcję File Search
  • Model samodzielnie decyduje, kiedy przeszukiwać dokumenty
  • max_num_results kontroluje głębokość wyszukiwania
  • Metadane i filtry umożliwiają wyszukiwanie ukierunkowane
  • Monitoruj status indeksowania przed odpytywaniem