Kërkimi i skedarëve

API-ja Gemini mundëson Gjenerimin e Shtuar të Rikthimit ("RAG") përmes mjetit të Kërkimit të Skedarëve. Kërkimi i Skedarëve importon, ndan në pjesë dhe indekson të dhënat tuaja për të mundësuar rikthimin e shpejtë të informacionit përkatës bazuar në kërkesën e përdoruesit. Ky informacion më pas ofrohet si kontekst për modelin, duke i lejuar modelit të ofrojë përgjigje më të sakta dhe përkatëse.

Mund të përdorni API-n uploadToFileSearchStore për të ngarkuar drejtpërdrejt një skedar ekzistues në dyqanin tuaj të kërkimit të skedarëve, ose të ngarkoni veçmas dhe më pas të importoni një skedar nëse doni ta krijoni skedarin në të njëjtën kohë.

Ngarkoni direkt në dyqanin e kërkimit të skedarëve

Ky shembull tregon se si të ngarkoni direkt një skedar në një depo skedarësh:

from google import genai
from google.genai import types
import time

client = genai.Client()

# Create the file search store with an optional display name that shows in the grounding metadata
file_search_store = client.file_search_stores.create(config={'display_name': 'your-fileSearchStore-name'})

# Upload and import a file into the file search store, supply a unique file name which will be visible in citations
operation = client.file_search_stores.upload_to_file_search_store(
  file='path/to/your/file.txt',
  file_search_store_name='unique_file_name'
)

# Wait until import is complete
while not operation.done:
    time.sleep(5)
    operation = client.operations.get(operation)

# Ask a question about the file
response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="""Can you tell me about Robert Graves""",
    config=types.GenerateContentConfig(
        tools=[
            file_search=(
                  file_search_store_names=[file_search_store.name]
            )
        ]
    )
)

print(response.text)

Importimi i skedarëve

Si alternativë, mund të ngarkoni një skedar ekzistues dhe ta importoni atë në depon tuaj të skedarëve:

from google import genai
from google.genai import types
import time

client = genai.Client()

# Upload the file using the Files API, supply a unique file name which will be visible in citations
sample_file = client.files.upload(file='sample.txt', config={'name': 'unique_file_name'})

# Create the file search store with an optional display name that shows in the grounding metadata
file_search_store = client.file_search_stores.create(config={'display_name': 'your-fileSearchStore-name'})

# Import the file into the file search store
operation = client.file_search_stores.import_file(
    file_search_store_name=file_search_store.name,
    file_name=sample_file.name
)

# Wait until import is complete
while not operation.done:
    time.sleep(5)
    operation = client.operations.get(operation)

# Ask a question about the file
response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="""Can you tell me about Robert Graves""",
    config=types.GenerateContentConfig(
        tools=[
            file_search=(
                  file_search_store_names=[file_search_store.name]
            )
        ]
    )
)

print(response.text)

Konfigurimi i ndarjes në grupe

Kur importoni një skedar në një depo kërkimi skedarësh, ai ndahet automatikisht në pjesë, integrohet, indeksohet dhe ngarkohet në depon tuaj të kërkimit të skedarëve. Nëse keni nevojë për më shumë kontroll mbi strategjinë e ndarjes në pjesë, mund të specifikoni një cilësim chunking_config për të vendosur një numër maksimal të tokenëve për pjesë dhe numrin maksimal të tokenëve që mbivendosen.

# Upload and import and upload the file into the file search store with a custom chunking configuration
operation = client.file_search_stores.upload_to_file_search_store(
    file_search_store_name=file_search_store.name,
    file_name=sample_file.name,
    config={
        'chunking_config': {
          'white_space_config': {
            'max_tokens_per_chunk': 200,
            'max_overlap_tokens': 20
          }
        }
    }
)

Për të përdorur dyqanin tuaj të kërkimit të skedarëve, kalojeni atë si një mjet te metoda generateContent , siç tregohet në shembujt e Ngarkimit dhe Importit .

Si funksionon

Kërkimi i Skedarëve përdor një teknikë të quajtur kërkim semantik për të gjetur informacion që lidhet me kërkesën e përdoruesit. Ndryshe nga kërkimi tradicional i bazuar në fjalë kyçe, kërkimi semantik e kupton kuptimin dhe kontekstin e pyetjes suaj.

Kur importoni një skedar, ai konvertohet në përfaqësime numerike të quajtura ngulitje , të cilat kapin kuptimin semantik të tekstit. Këto ngulitje ruhen në një bazë të dhënash të specializuar për kërkimin e skedarëve. Kur bëni një pyetje, edhe ajo konvertohet në një ngulitje. Pastaj sistemi kryen një kërkim skedarësh për të gjetur pjesët më të ngjashme dhe më relevante të dokumentit nga ruajtja e kërkimit të skedarëve.

Ja një përshkrim i hollësishëm i procesit për përdorimin e File Search uploadToFileSearchStore API:

1. Krijo një depo kërkimi skedarësh : Një depo kërkimi skedarësh përmban të dhënat e përpunuara nga skedarët tuaj. Është kontejneri i përhershëm për ngulitje mbi të cilin do të veprojë kërkimi semantik.

2. Ngarko një skedar dhe importo në një depo kërkimi skedarësh : Ngarko njëkohësisht një skedar dhe importo rezultatet në depon tënde të kërkimit të skedarëve. Kjo krijon një objekt të përkohshëm File , i cili është një referencë për dokumentin tënd të papërpunuar. Këto të dhëna më pas ndahen në copa, konvertohen në ngulitje të kërkimit të skedarëve dhe indeksohen. Objekti File fshihet pas 48 orësh, ndërsa të dhënat e importuara në depon e kërkimit të skedarëve do të ruhen për një kohë të pacaktuar derisa të zgjedhësh t'i fshish.

3. Pyetje me Kërkimin e Skedarëve : Së fundmi, përdorni mjetin FileSearch në një thirrje generateContent . Në konfigurimin e mjetit, specifikoni një FileSearchRetrievalResource , i cili tregon te FileSearchStore që dëshironi të kërkoni. Kjo i tregon modelit të kryejë një kërkim semantik në atë depo specifike të kërkimit të skedarëve për të gjetur informacionin përkatës për të bazuar përgjigjen e tij.

Në këtë diagram, vija me pika nga Dokumentet në modelin Embedding (duke përdorur gemini-embedding-001 ) përfaqëson API- uploadToFileSearchStore (duke anashkaluar ruajtjen e skedarëve ). Përndryshe, përdorimi i API-së së skedarëve për të krijuar dhe më pas importuar veçmas skedarë e zhvendos procesin e indeksimit nga Dokumentet në ruajtjen e skedarëve dhe më pas në modelin Embedding .

Dyqanet e kërkimit të skedarëve

Një depo kërkimi skedarësh është një kontejner për ngulitje dokumentesh. Ndërsa skedarët e papërpunuar të ngarkuar përmes File API fshihen pas 48 orësh, të dhënat e importuara në një depo kërkimi skedarësh ruhen për një kohë të pacaktuar derisa t'i fshini manualisht. Mund të krijoni depo të shumta kërkimi skedarësh për të organizuar dokumentet tuaja. FileSearchStore API ju lejon të krijoni, listoni, merrni dhe fshini për të menaxhuar depot tuaja të kërkimit të skedarëve. Emrat e depove të kërkimit të skedarëve janë të shtrirë globalisht.

Ja disa shembuj se si të menaxhoni dyqanet e kërkimit të skedarëve:

# Create a file search store (including optional display_name for easier reference)
file_search_store = client.file_search_stores.create(config={'display_name': 'my-file_search-store-123'})

# List all your file search stores
for file_search_store in client.file_search_stores.list():
    print(file_search_store)

# Get a specific file search store by name
my_file_search_store = client.file_search_stores.get(name='fileSearchStores/my-file_search-store-123')

# Delete a file search store
client.file_search_stores.delete(name='fileSearchStores/my-file_search-store-123', config={'force': True})

Metadatat e skedarit

Mund të shtoni meta të dhëna të personalizuara në skedarët tuaj për t'i filtruar ato ose për të ofruar kontekst shtesë. Meta të dhënat janë një grup çiftesh çelës-vlerë.

# Import the file into the file search store with custom metadata
op = client.file_search_stores.import_file(
    file_search_store_name=file_search_store.name,
    file_name=sample_file.name,
    custom_metadata=[
        {"key": "author", "string_value": "Robert Graves"},
        {"key": "year", "numeric_value": 1934}
    ]
)

Kjo është e dobishme kur keni dokumente të shumta në një dyqan kërkimi skedarësh dhe dëshironi të kërkoni vetëm në një nëngrup të tyre.

# Use the metadata filter to search within a subset of documents
response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="""Tell me about the book 'I, Claudius'""",
    config=types.GenerateContentConfig(
        tools=[
            types.Tool(
                file_search=types.FileSearch(
                  file_search_store_names=[file_search_store.name],
                  metadata_filter = 'author=Robet Graves',
                  )
            )
        ]
    )
)

print(response.text)

Udhëzime mbi zbatimin e sintaksës së filtrit të listës për metadata_filter mund të gjenden në google.aip.dev/160

Citime

Kur përdorni Kërkimin e Skedarëve, përgjigjja e modelit mund të përfshijë citime që specifikojnë se cilat pjesë të dokumenteve të ngarkuara janë përdorur për të gjeneruar përgjigjen. Kjo ndihmon me verifikimin dhe verifikimin e fakteve.

Mund të qaseni në informacionin e citimeve përmes atributit grounding_metadata të përgjigjes.

print(response.candidates[0].grounding_metadata)

Modelet e mbështetura

Modelet e mëposhtme mbështesin Kërkimin e Skedarëve:

• gemini-2.5-pro
• gemini-2.5-flash

Llojet e skedarëve të mbështetur

Kërkimi i skedarëve mbështet një gamë të gjerë formatesh skedarësh, të listuara në seksionet vijuese.

Limitet e tarifave

API-ja e Kërkimit të Skedarëve ka kufizimet e mëposhtme për të zbatuar stabilitetin e shërbimit:

• Madhësia maksimale e skedarit / limiti për dokument : 100 MB
• Ruajtja e kërkimit të skedarëve për projekt : 10
• Madhësia totale e depove të kërkimit të skedarëve të projektit (bazuar në nivelin e përdoruesit):
  • Falas : 1 GB
  • Niveli 1 : 10 GB
  • Niveli 2 : 100 GB
  • Niveli 3 : 1 TB
• Rekomandim : Kufizoni madhësinë e secilës hapësirë ​​​​ruajtjeje për kërkimin e skedarëve në më pak se 20 GB për të siguruar vonesa optimale të rikuperimit.

Çmimet

• Zhvilluesve u faturohen ngulitje në kohën e indeksimit bazuar në çmimet ekzistuese të ngulitjeve (0,15 dollarë për 1 milion tokenë).
• Magazinimi është falas.
• Integrimet në kohën e pyetjeve janë pa pagesë.
• Tokenët e dokumentit të marrë tarifohen si tokenë të rregullt konteksti .