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ë një kërkesë të dhënë. Ky informacion përdoret më pas si kontekst për modelin, duke i lejuar modelit të ofrojë përgjigje më të sakta dhe përkatëse.

Për ta bërë Kërkimin e Skedarëve të thjeshtë dhe të përballueshëm për zhvilluesit, ne po e bëjmë ruajtjen e skedarëve dhe gjenerimin e ngulitjeve në kohën e pyetjes falas. Ju paguani vetëm për krijimin e ngulitjeve kur indeksoni për herë të parë skedarët tuaj (me koston përkatëse të modelit të ngulitjeve) dhe koston normale të tokenëve hyrës/dalës të modelit Gemini. Kjo paradigmë e re faturimi e bën Mjetin e Kërkimit të Skedarëve më të lehtë dhe më kosto-efektiv për t'u ndërtuar dhe për t'u shkallëzuar.

Ngarkoje direkt në dyqanin e Kërkimit të Skedarëve

Ky shembull tregon se si të ngarkoni drejtpërdrejt një skedar në dyqanin e kërkimit të skedarëve :

Python 

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

client = genai.Client()

# File name will be visible in citations
file_search_store = client.file_search_stores.create(config={'display_name': 'your-fileSearchStore-name'})

operation = client.file_search_stores.upload_to_file_search_store(
  file='sample.txt',
  file_search_store_name=file_search_store.name,
  config={
      'display_name' : 'display-file-name',
  }
)

while not operation.done:
    time.sleep(5)
    operation = client.operations.get(operation)

response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="""Can you tell me about [insert question]""",
    config=types.GenerateContentConfig(
        tools=[
            types.Tool(
                file_search=types.FileSearch(
                    file_search_store_names=[file_search_store.name]
                )
            )
        ]
    )
)

print(response.text)

JavaScript 

const { GoogleGenAI } = require('@google/genai');

const ai = new GoogleGenAI({});

async function run() {
  // File name will be visible in citations
  const fileSearchStore = await ai.fileSearchStores.create({
    config: { displayName: 'your-fileSearchStore-name' }
  });

  let operation = await ai.fileSearchStores.uploadToFileSearchStore({
    file: 'file.txt',
    fileSearchStoreName: fileSearchStore.name,
    config: {
      displayName: 'file-name',
    }
  });

  while (!operation.done) {
    await new Promise(resolve => setTimeout(resolve, 5000));
    operation = await ai.operations.get({ operation });
  }

  const response = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: "Can you tell me about [insert question]",
    config: {
      tools: [
        {
          fileSearch: {
            fileSearchStoreNames: [fileSearchStore.name]
          }
        }
      ]
    }
  });

  console.log(response.text);
}

run();

Kontrolloni referencën API për uploadToFileSearchStore për më shumë informacion.

Importimi i skedarëve

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

Python 

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

client = genai.Client()

# File name will be visible in citations
sample_file = client.files.upload(file='sample.txt', config={'name': 'display_file_name'})

file_search_store = client.file_search_stores.create(config={'display_name': 'your-fileSearchStore-name'})

operation = client.file_search_stores.import_file(
    file_search_store_name=file_search_store.name,
    file_name=sample_file.name
)

while not operation.done:
    time.sleep(5)
    operation = client.operations.get(operation)

response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="""Can you tell me about [insert question]""",
    config=types.GenerateContentConfig(
        tools=[
            types.Tool(
                file_search=types.FileSearch(
                    file_search_store_names=[file_search_store.name]
                )
            )
        ]
    )
)

print(response.text)

JavaScript 

const { GoogleGenAI } = require('@google/genai');

const ai = new GoogleGenAI({});

async function run() {
  // File name will be visible in citations
  const sampleFile = await ai.files.upload({
    file: 'sample.txt',
    config: { name: 'file-name' }
  });

  const fileSearchStore = await ai.fileSearchStores.create({
    config: { displayName: 'your-fileSearchStore-name' }
  });

  let operation = await ai.fileSearchStores.importFile({
    fileSearchStoreName: fileSearchStore.name,
    fileName: sampleFile.name
  });

  while (!operation.done) {
    await new Promise(resolve => setTimeout(resolve, 5000));
    operation = await ai.operations.get({ operation: operation });
  }

  const response = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: "Can you tell me about [insert question]",
    config: {
      tools: [
        {
          fileSearch: {
            fileSearchStoreNames: [fileSearchStore.name]
          }
        }
      ]
    }
  });

  console.log(response.text);
}

run();

Kontrolloni referencën API për importFile për më shumë informacion.

Konfigurimi i ndarjes në grupe

Kur importoni një skedar në një dyqan të Kërkimit të Skedarëve, ai ndahet automatikisht në pjesë, integrohet, indeksohet dhe ngarkohet në dyqanin tuaj të Kërkimit të Skedarëve. Nëse keni nevojë për më shumë kontroll mbi strategjinë e ndarjes së pjesëve, 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.

Python 

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

JavaScript 

let operation = await ai.fileSearchStores.uploadToFileSearchStore({
  file: 'file.txt',
  fileSearchStoreName: fileSearchStore.name,
  config: {
    displayName: 'file-name',
    chunkingConfig: {
      whiteSpaceConfig: {
        maxTokensPerChunk: 200,
        maxOverlapTokens: 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 standard 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 të Kërkimit të 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 dyqani i 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 të Kërkimit të Skedarëve : Një depo e Kërkimit të Skedarëve 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 të Kërkimit të Skedarëve : Ngarko njëkohësisht një skedar dhe importo rezultatet në depon tënd 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ë dyqan specifik të Kërkimit të Skedarëve për të gjetur informacionin përkatës për të bazuar përgjigjen e tij.

Procesi i indeksimit dhe pyetjeve të Kërkimit të Skedarëve
Procesi i indeksimit dhe pyetjeve të Kërkimit të Skedarëve

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 File Search ë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 File Search ruhen për një kohë të pacaktuar derisa t'i fshini manualisht. Mund të krijoni disa depo File Search për të organizuar dokumentet tuaja. FileSearchStore API ju lejon të krijoni, listoni, merrni dhe fshini për të menaxhuar depot e kërkimit të skedarëve. Emrat e depove File Search janë të shtrira globalisht.

Ja disa shembuj se si të menaxhoni dyqanet e Kërkimit të Skedarëve:

Python 

file_search_store = client.file_search_stores.create(config={'display_name': 'my-file_search-store-123'})

for file_search_store in client.file_search_stores.list():
    print(file_search_store)

my_file_search_store = client.file_search_stores.get(name='fileSearchStores/my-file_search-store-123')

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

JavaScript 

const fileSearchStore = await ai.fileSearchStores.create({
  config: { displayName: 'my-file_search-store-123' }
});

const fileSearchStores = await ai.fileSearchStores.list();
for await (const store of fileSearchStores) {
  console.log(store);
}

const myFileSearchStore = await ai.fileSearchStores.get({
  name: 'fileSearchStores/my-file_search-store-123'
});

await ai.fileSearchStores.delete({
  name: 'fileSearchStores/my-file_search-store-123',
  config: { force: true }
});

PUSHTIM 

curl -X POST "https://generativelanguage.googleapis.com/v1beta/fileSearchStores?key=${GEMINI_API_KEY}" \
    -H "Content-Type: application/json" 
    -d '{ "displayName": "My Store" }'

curl "https://generativelanguage.googleapis.com/v1beta/fileSearchStores?key=${GEMINI_API_KEY}" \

curl "https://generativelanguage.googleapis.com/v1beta/fileSearchStores/my-file_search-store-123?key=${GEMINI_API_KEY}"

curl -X DELETE "https://generativelanguage.googleapis.com/v1beta/fileSearchStores/my-file_search-store-123?key=${GEMINI_API_KEY}"

Referenca e API-t të Dokumenteve të Kërkimit të Skedarëve për metodat dhe fushat që lidhen me menaxhimin e dokumenteve në depot tuaja të skedarëve.

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ë.

Python 

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

JavaScript 

let operation = await ai.fileSearchStores.importFile({
  fileSearchStoreName: fileSearchStore.name,
  fileName: sampleFile.name,
  config: {
    customMetadata: [
      { key: "author", stringValue: "Robert Graves" },
      { key: "year", numericValue: 1934 }
    ]
  }
});

Kjo është e dobishme kur keni dokumente të shumta në një dyqan të Kërkimit të Skedarëve dhe dëshironi të kërkoni vetëm në një nëngrup të tyre.

Python 

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=Robert Graves",
                )
            )
        ]
    )
)

print(response.text)

JavaScript 

const response = await ai.models.generateContent({
  model: "gemini-2.5-flash",
  contents: "Tell me about the book 'I, Claudius'",
  config: {
    tools: [
      {
        fileSearch: {
          fileSearchStoreNames: [fileSearchStore.name],
          metadataFilter: 'author="Robert Graves"',
        }
      }
    ]
  }
});

console.log(response.text);

PUSHTIM 

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent?key=${GEMINI_API_KEY}" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
            "contents": [{
                "parts":[{"text": "Tell me about the book I, Claudius"}]          
            }],
            "tools": [{
                "file_search": { 
                    "file_search_store_names":["'$STORE_NAME'"],
                    "metadata_filter": "author = \"Robert Graves\""
                }
            }]
        }' 2> /dev/null > response.json

cat response.json

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.

Python 

print(response.candidates[0].grounding_metadata)

JavaScript 

console.log(JSON.stringify(response.candidates?.[0]?.groundingMetadata, null, 2));

Modelet e mbështetura

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

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.

Llojet e skedarëve të aplikacionit

  • application/dart
  • application/ecmascript
  • application/json
  • application/ms-java
  • application/msword
  • application/pdf
  • application/sql
  • application/typescript
  • application/vnd.curl
  • application/vnd.dart
  • application/vnd.ibm.secure-container
  • application/vnd.jupyter
  • application/vnd.ms-excel
  • application/vnd.oasis.opendocument.text
  • application/vnd.openxmlformats-officedocument.presentationml.presentation
  • application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
  • application/vnd.openxmlformats-officedocument.wordprocessingml.document
  • application/vnd.openxmlformats-officedocument.wordprocessingml.template
  • application/x-csh
  • application/x-hwp
  • application/x-hwp-v5
  • application/x-latex
  • application/x-php
  • application/x-powershell
  • application/x-sh
  • application/x-shellscript
  • application/x-tex
  • application/x-zsh
  • application/xml
  • application/zip

Llojet e skedarëve të tekstit

  • text/1d-interleaved-parityfec
  • text/RED
  • text/SGML
  • text/cache-manifest
  • text/calendar
  • text/cql
  • text/cql-extension
  • text/cql-identifier
  • text/css
  • text/csv
  • text/csv-schema
  • text/dns
  • text/encaprtp
  • text/enriched
  • text/example
  • text/fhirpath
  • text/flexfec
  • text/fwdred
  • text/gff3
  • text/grammar-ref-list
  • text/hl7v2
  • text/html
  • text/javascript
  • text/jcr-cnd
  • text/jsx
  • text/markdown
  • text/mizar
  • text/n3
  • text/parameters
  • text/parityfec
  • text/php
  • text/plain
  • text/provenance-notation
  • text/prs.fallenstein.rst
  • text/prs.lines.tag
  • text/prs.prop.logic
  • text/raptorfec
  • text/rfc822-headers
  • text/rtf
  • text/rtp-enc-aescm128
  • text/rtploopback
  • text/rtx
  • text/sgml
  • text/shaclc
  • text/shex
  • text/spdx
  • text/strings
  • text/t140
  • text/tab-separated-values
  • text/texmacs
  • text/troff
  • text/tsv
  • text/tsx
  • text/turtle
  • text/ulpfec
  • text/uri-list
  • text/vcard
  • text/vnd.DMClientScript
  • text/vnd.IPTC.NITF
  • text/vnd.IPTC.NewsML
  • text/vnd.a
  • text/vnd.abc
  • text/vnd.ascii-art
  • text/vnd.curl
  • text/vnd.debian.copyright
  • text/vnd.dvb.subtitle
  • text/vnd.esmertec.theme-descriptor
  • text/vnd.exchangeable
  • text/vnd.familysearch.gedcom
  • text/vnd.ficlab.flt
  • text/vnd.fly
  • text/vnd.fmi.flexstor
  • text/vnd.gml
  • text/vnd.graphviz
  • text/vnd.hans
  • text/vnd.hgl
  • text/vnd.in3d.3dml
  • text/vnd.in3d.spot
  • text/vnd.latex-z
  • text/vnd.motorola.reflex
  • text/vnd.ms-mediapackage
  • text/vnd.net2phone.commcenter.command
  • text/vnd.radisys.msml-basic-layout
  • text/vnd.senx.warpscript
  • text/vnd.sosi
  • text/vnd.sun.j2me.app-descriptor
  • text/vnd.trolltech.linguist
  • text/vnd.wap.si
  • text/vnd.wap.sl
  • text/vnd.wap.wml
  • text/vnd.wap.wmlscript
  • text/vtt
  • text/wgsl
  • text/x-asm
  • text/x-bibtex
  • text/x-boo
  • text/xc
  • text/x-c++hdr
  • text/x-c++src
  • text/x-cassandra
  • text/x-chdr
  • text/x-coffeescript
  • text/x-component
  • text/x-csh
  • text/x-csharp
  • text/x-csrc
  • text/x-cuda
  • text/xd
  • text/x-diff
  • text/x-dsrc
  • text/x-emacs-lisp
  • text/x-erlang
  • text/x-gff3
  • text/x-go
  • text/x-haskell
  • text/x-java
  • text/x-java-properties
  • text/x-java-source
  • text/x-kotlin
  • text/x-lilypond
  • text/x-lisp
  • text/x-literate-haskell
  • text/x-lua
  • text/x-moc
  • text/x-objcsrc
  • text/x-pascal
  • text/x-pcs-gcd
  • text/x-perl
  • text/x-perl-script
  • text/x-python
  • text/x-python-script
  • text/xr-markdown
  • text/x-rsrc
  • text/x-rst
  • text/x-ruby-script
  • text/x-rust
  • text/x-sass
  • text/x-scala
  • text/x-scheme
  • text/x-script.python
  • text/x-scss
  • text/x-setext
  • text/x-sfv
  • text/x-sh
  • text/x-siesta
  • text/x-sos
  • text/x-sql
  • text/x-swift
  • text/x-tcl
  • text/x-tex
  • text/x-vbasic
  • text/x-vcalendar
  • text/xml
  • text/xml-dtd
  • text/xml-external-parsed-entity
  • text/yaml

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
  • Madhësia totale e ruajtjeve 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 të Kërkimit të Skedarëve në nën 20 GB për të siguruar vonesa optimale të rikuperimit.

Çmimet

Çfarë vjen më pas