Căutare în fișiere: Indexarea și interogarea documentelor
Pe această pagină
- Căutare în fișiere: Indexarea și interogarea documentelor
- Crearea unui stoc vectorial
- Încărcarea și indexarea fișierelor
- Interogarea cu Căutare în fișiere
- Examinarea rezultatelor căutării
- Configurarea căutării
- Gestionarea ciclului de viață al stocului vectorial
- Exemplu complet: Asistent pentru documentație
- Puncte cheie
Căutare în fișiere: Indexarea și interogarea documentelor
Căutarea în fișiere (File Search) permite modelului să analizeze documentele dumneavoastră private. Încărcați fișierele într-un stoc vectorial, iar modelul le interoghează automat ori de câte ori are nevoie de informații specifice. Aceasta reprezintă fundamentul tehnologiei RAG (Retrieval-Augmented Generation) integrat direct în API-ul OpenAI.
Crearea unui stoc vectorial
Stocul vectorial este unitatea organizatorică pentru Căutarea în fișiere, iar structura aleasă aici va avea un impact pe termen lung. Un singur stoc pentru întreaga companie este ușor de administrat, dar amestecă documente cu vocabulare neconexe, ceea ce degradează relevanța rezultatelor. Stocurile separate pe echipe sau domenii necesită puțin mai multă gestionare, dar fac fiecare căutare semnificativ mai precisă. În caz de îndoială, separați-le: este mai ușor să uniți stocuri ulterior decât să dezlănțuiți un haos.
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}")
Încărcarea și indexarea fișierelor
Indexarea este asincronă, iar aceasta este cea mai frecventă sursă de eroare la prima încercare: adăugați fișiere, interogați imediat, iar modelul răspunde că nu a găsit nimic – nu pentru că eșecul aparține căutării, ci pentru că nimic nu fusese încă indexat. Verificați întotdeauna statusul înainte de a interoga, așa cum este detaliat în secțiunea despre ciclul de viață.
Un cuvânt despre formate: lista este largă, dar nu toate fișierele sunt egale. Un PDF generat dintr-un procesor de text se extrage curat; un PDF scanat fără un strat de text nu adaugă nimic, deoarece nu există literalmente niciun cuvânt de indexat.
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}")
Interogarea cu Căutare în fișiere
Apelul este intenționat simplu: declarați instrumentul, puneți întrebarea, iar modelul decide dacă este necesară o căutare. Toată munca specifică RAG – fragmentarea, vectorizarea, clasarea și injectarea în context – are loc pe server. Acest lucru economisește timp considerabil la pornire, iar lecția următoare acoperă setările pe care trebuie să le cunoașteți atunci când valorile implicite nu sunt suficiente.
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)
Modelul caută automat în documentele dumneavoastră și formulează un răspuns bazat pe conținutul găsit.
Examinarea rezultatelor căutării
Anotările sunt cele care disting un răspuns verificabil de o simplă afirmație. Expuneți-le utilizatorilor dumneavoastră: într-o bază de cunoștințe internă, capacitatea de a retrasa sursa până la documentul original schimbă complet nivelul de încredere în sistem – și vă ajută să identificați cazurile în care modelul a greșit.
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}")
Configurarea căutării
Numărul de rezultate
Creșterea numărului de pasaje nu îmbunătățește mecanic răspunsul. Dincolo de aproximativ zece, fragmentele slab relevante diluează pe cele bune și consumă context facturat. Ridicați această valoare doar atunci când răspunsul este vizibil incomplet, nu ca principiu general.
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
}]
)
Filtrarea prin metadate
Metadatele sunt pârghia cea mai subutilizată pentru precizie. Filtrarea după an, departament sau tip de document înainte de căutarea vectorială elimină zgomotul din start, pe care clasarea ar fi trebuit altfel să îl filtreze. Acest lucru vă permite, de asemenea, să răspundeți „conform procedurii curente“, fără a amesteca trei versiuni succesive ale aceluiași document.
# 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"
}
}]
)
Filtre compuse
Combinați multiple criterii folosind operatori logici:
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}
]
}
}]
)
Gestionarea ciclului de viață al stocului vectorial
Monitorizarea indexării
# 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")
Eliminarea fișierelor învechite
# 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"
)
Exemplu complet: Asistent pentru documentație
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
}
Puncte cheie
- Creați un stoc vectorial și încărcați fișierele pentru a activa Căutarea în fișiere
- Modelul decide singur când să caute în documente
max_num_resultscontrolează profunzimea căutării- Metadatele și filtrele permit o căutare țintită
- Monitorizați statusul indexării înainte de a interoga