Vyhľadávanie súborov Google v rozhraní Gemini API: Praktický a kompletný sprievodca od RAG

Príchod vyhľadávania súborov do ekosystému rozhrania Gemini API bol prelomovým krokom pre tých, ktorí chcú vytvárať aplikácie založené na RAG bez toho, aby sa museli trápiť s infraštruktúrou. Vďaka tejto spravovanej službe Google automatizuje ukladanie súborov, segmentovanie, vkladanie a dynamické vkladanie kontextu v čase zostavovania, takže sa môžete sústrediť na vytváranie produktu, nie na budovanie vývojových kanálov.

Okrem prijímania dokumentov poskytuje vyhľadávanie súborov pokročilé sémantické vyhľadávanieKompatibilita s rôznymi formátmi, automatické citácie a jednoduchá cenová štruktúraA ak potrebujete aktuálne informácie z webu, API to tiež ponúka. google_search pre uzemnenie pomocou vyhľadávania Google, s veľmi užitočné overovacie metadáta pre rozhrania so sledovateľnými termínmi.

Čo presne je vyhľadávanie súborov v rozhraní Gemini API?

Vyhľadávanie súborov je plne spravované riešenie RAG integrované do rozhrania Gemini API. V praxi nahrajete súbory (alebo ich importujete zo súborovej služby) a systém sa postará o ich rozdelenie na fragmenty, generovanie vnorení, indexovanie v úložisku vyhľadávania súborov a ich použitie ako základu pre odpovede na používateľské dotazy prostredníctvom vektorového vyhľadávania.

Cieľom je, aby ste sa s tým nemuseli zaoberať Vektorové bázy, indexovacie fronty alebo stratégie rozdelenia do blokov sami. Nástroj je založený na modeli vkladania od spoločnosti Google (napríklad gemini-embedding-001) a natívne sa integruje s generateContentkde vyhlasujete, Nástroj na vyhľadávanie súborov a obchod to musí skontrolovať.

Ako to funguje: od dokumentu ku kontextovej odpovedi

Koncepčný tok je jednoduchý, hoci sa za ním skrýva veľa podstaty. Najprv sa vaše dokumenty prevedú na numerické reprezentácie (vnorenia) , ktoré zachytávajú význam. Tieto vektory sa uložia v špecializovanom úložisku. Potom, keď odošlete dopyt, API prevedie výzvu na iné vnorenie a vykoná sémantické vyhľadávanie , aby načítalo najrelevantnejšie úryvky.

Nakoniec, vo výzve na generateContent s nástrojom FileSearch, pridáš jeden Zdroj vyhľadávania súborov ktorý ukazuje na konkrétny obchod. Model tak vie, že musí obnoviť kontext z vášho obchodu a použite ho na podporu vašej reakcie. Toto všetko sa deje bez toho, aby ste museli plánovať manuálne obnovenie alebo používať externé služby.

Nahrávanie a importovanie dokumentov: dve kompatibilné cesty

Na prenos dát do vášho obchodu máte dve možnosti. Ak chcete ísť rovno k veci, použite API. uploadToFileSearchStore pre nahrajte súbor priamo a indexujte ho v jednej operácii. Ak uprednostňujete oddelené kroky, môžete súbor nahrať pomocou rozhrania API súborov a potom importovať s importFile do úložiska vyhľadávania súborov.

Keď sa rozhodnete nahrať a importovať všetko naraz, File dočasné ako odkaz na surový dokument; že Predmet sa odstráni po 48 hodinách.Indexované údaje však zostanú v úložisku, kým sa ich nerozhodnete odstrániť. Ak Používate rozhranie API súborov A potom importujete; kanál prechádza cez úložisko súborov pred fázou vkladania.

Riadenie rozdelenia: presnosť a prekrytie

API štandardne rozhoduje o stratégii inteligentné krájanieAk však potrebujete doladiť, môžete špecifikovať chunking_config s parametrami ako napríklad maximálny počet tokenov na shard y prekrývajúce sa tokenyS menším počtom tokenov na blok získate granularitu vyhľadávania; s väčším počtom si zachováte viac kontextu fragmentom.

Toto jemné doladenie je užitočné v prípadoch, ako je zdrojový kód, rozsiahle dokumenty alebo technické manuály , kde je vhodné upraviť rovnováhu medzi presnosťou vyhľadávania a kontextovou kontinuitou.

Úložiská vyhľadávania súborov: Perzistencia, rozsah a správa

Úložisko vyhľadávania súborov je trvalý kontajner, v ktorom sa nachádzajú spracované vložené súbory . Na rozdiel od nespracovaných súborov rozhrania Files API (ktoré zmiznú po 48 hodinách) sa obsah importovaný do úložiska uchováva, kým sa explicitne neodstráni . Na usporiadanie svojich znalostných domén môžete vytvoriť viacero úložísk a ich názvy sú globálne jedinečné.

API rozhrania FileSearchStore umožňuje ti to vytvárať, zobrazovať, získavať a odstraňovať obchodyOkrem toho existuje rozhranie API pre dokumenty na správu obsahu v každom obchode a môžete k nemu pripojiť vlastné metadáta (páry kľúč-hodnota) do súborov na filtrovanie vyhľadávaní podľa podmnožín. Pre filter sa používa syntax zoznamy filtrov opísané v google.aip.dev/160.

Podrobný postup používania API

Z prevádzkového hľadiska typický proces pozostáva z troch krokov. Po prvé, Vytvoríte úložisko vyhľadávania súborov, potom, nahrávanie a importovanie súborov (Alebo nahráte a potom importujete.) Nakoniec, dopytovania k modelu s generateContent označujúci nástroj FileSearch a cieľový obchod prostredníctvom FileSearchRetrievalResource.

V prostrediach JavaScript/TypeScript je bežnou praxou používanie súbežné operácie (napríklad Promise.all) na načítanie viacerých súborov naraz a monitorovanie operation.done Predtým, ako budete pokračovať. Je tiež bežné vyhľadávať obchod podľa jeho zobraziť meno (čitateľné pre človeka), ak si nepamätáte identifikátor fileSearchStores/....

Správa dokumentov: vyhľadávanie, aktualizácia a mazanie

V rámci úložiska je niekedy užitočné vyhľadať konkrétny dokument podľa jeho zobrazovaného názvu na účely správy. Dôležitý detail: dokumenty sú po indexovaní nemenné . Ak ich potrebujete aktualizovať, odporúča sa odstrániť existujúci dokument a nahrať novú verziu.

Ako osvedčený postup mnoho pracovných postupov automatizuje tento cyklus: vyhľadávanie → odstránenie → nahrávanie . A keď skončíte so zdrojmi (napríklad vo vývoji), nezabudnite, že existuje limit 10 úložísk na projekt , takže je dobré ich vyčistiť, ak ich už nepotrebujete.

Citácie a overovanie: založené na vašich dokumentoch

Kľúčovou výhodou vyhľadávania súborov je, že odpovede modelu môžu zahŕňať automatické citácie ktoré označujú fragmenty vašich dokumentov použitých na podporu výstupu. Táto sledovateľnosť sa zobrazuje v atribúte grounding_metadata odpovede a je kľúčová pre audit, overovanie a dôvera v podnikateľskom prostredí.

Takto môžete po odpovedi asistenta zobraziť presné odkazy na relevantné časti vašich súborov, čo uľahčí kontrolu nárokov a vytváranie rozhraní s online citáciami .

Podporované formáty súborov

Vyhľadávanie súborov podporuje široká škála formátovMedzi najbežnejšie patria application/pdf, application/vnd.openxmlformats-officedocument.wordprocessingml.document (DOCX), application/vnd.openxmlformats-officedocument.spreadsheetml.sheet (XLSX), application/vnd.openxmlformats-officedocument.presentationml.presentation (PPTX), application/json, application/xml, application/zip, okrem mnohých jazykov programovanie y textové typy ako text/plain, text/html, text/css, text/csv, text/markdown, text/javascript, text/yaml, Atď

Zahŕňa aj množstvo špecifických typov (napríklad kód a skripty ako application/x-php, application/x-powershell, application/x-sh, application/x-tex, application/x-zsh; a textové ako text/x-python, text/x-java, text/x-ruby-script, text/x-rust, text/x-go, text/x-kotlin, text/x-sql, text/x-c, text/x-csharp, text/x-swift, text/x-tex, text/x-scss, text/x-tcl, text/x-asm(okrem mnohých iných). Ak váš prípad vyžaduje nezvyčajný typ, je veľmi pravdepodobné, že je uvažovaný v oficiálnej dokumentácii.

Obmedzenia služieb a architektonické odporúčania

Pre zachovanie stability služby rozhranie API stanovuje jasné limity: maximálna veľkosť súboru je 100 MB ; celková veľkosť agregovaná v obchodoch závisí od úrovne používateľa: Bezplatne 1 GB , 1. úroveň 10 GB , 2. úroveň 100 GB a 3. úroveň 1 TB.

Ako smernica pre výkon sa odporúča udržiavať každé úložisko pod 20 GB, aby sa zabezpečila optimálna latencia. Majte na pamäti, že veľkosť úložiska sa na strane servera vypočíta ako vstupná veľkosť plus všetky vložené dáta , ktoré zvyčajne strojnásobia pôvodný objem dát.

Ceny: jednoduché a predvídateľné

Model fakturácie je jednoduchý: platíte iba za vytvorenie vnorení v indexe za cenu 0,15 USD za 1 milión tokenov (v závislosti od ceny príslušného modelu vnorenia). Ukladanie a generovanie vnorení pri dopyte je bezplatné a načítané tokeny sa pri generovaní účtujú ako bežné kontextové tokeny.

Táto schéma zjednodušuje zostavovanie rozpočtu: vysoké náklady sú sústredené v počiatočnom príjme (a v následných aktualizáciách dokumentov, ak nejaké existujú), čím sa minimalizuje prekvapenie v spotrebe v dôsledku objemu dopytov.

Kompatibilné modely pre vyhľadávanie súborov

Nástroj funguje so súčasnými modelmi v rodine Gemini. Referenčné materiály zdôrazňujú jeho dostupnosť v Gemini 2.5 Pro a Gemini 2.5 Flash pre vyhľadávanie súborov s podporou uzemnenia, filtrov metadát a citácií, ktoré pomáhajú vytvárať overiteľné skúsenosti.

Pokiaľ ide o uzemnenie pomocou Vyhľadávania Google (o ktorom sa hovorí nižšie), existuje širší sortiment podporovaných modelov a je uvedené, že experimentálne a ukážkové modely nie sú zahrnuté.

Uzemnenie pomocou Vyhľadávania Google: aktuálne informácie a webové citácie

Ak okrem dokladov potrebujete webový obsah v reálnom časeNástroj môžete aktivovať google_searchModel spravuje celý tokrozhodnúť, či je vhodné vyhľadávať, generovať a vykonávať dotazy, spracovávať výsledky, syntetizovať a vracať odpoveď s uzemňovacími metadátami (konzultácie, výsledky a citácie).

Ak je uzemnenie vykonané správne, reakcia zahŕňa groundingMetadata s poľami ako webSearchQueries (použité konzultácie), vyhľadávacíVstupnýBod (Pre návrhy vyhľadávania je potrebný HTML a CSS, pričom požiadavky na používanie sú podrobne uvedené v Podmienkach služby), uzemňovacie kúsky (webové zdroje s uri y title) A uzemneniePodpery (fragmenty, ktoré spájajú textové segmenty modelu s indexmi groundingChunks stavať online citácie).

Ceny a modely uzemnenia pomocou vyhľadávania Google

Použitie google_search faktúra pre každú žiadosť ktorý aktivuje daný nástroj, aj keď model spustí niekoľko interných dopytov pre tú istú požiadavku; toto všetko sa počíta ako jednorazové fakturovateľné použitieModely kompatibilné s týmto nástrojom sú uvedené nižšie. Gemini 2.5 Pro, Gemini 2.5 Flash, Gemini 2.5 Flash-Lite, Gemini 2.0 Flash, Gemini 1.5 Pro y Gemini 1.5 Flash.

Pre modely staršie ako verzia 1.5 je k dispozícii starší nástroj. google_search_retrieval s režimom dynamickýkde nakonfigurujete dynamický_prah (0.0–1.0) a model sa rozhodne, či sa vyhľadávanie vykoná alebo nie na základe jeho dôvera kde potrebujete aktuálne informácie.

Prípady použitia: od interných asistentov až po zákaznícku podporu

Vyhľadávanie súborov je zamerané na podnikové prostredia , kde sú prvoradé súkromie, presnosť a sledovateľnosť. Je užitočné pre asistentov znalostí, ktorí vyhľadávajú v chránenej dokumentácii, automatizujú podporu s odkazmi na manuály a zásady alebo urýchľujú vyhľadávanie a kontrolu v informačne náročných odvetviach (právo, zdravotníctvo, financie).

Taktiež urýchľuje vývojové a ladenie pracovných postupov tým, že umožňuje interakciu s kódovými základňami alebo technickými špecifikáciami. Jeho kombinácia s ďalšími funkciami Gemini (ako je vykonávanie kódu alebo funkcií) umožňuje integrácie bohaté na procesy dodržiavania predpisov, auditu alebo analytiky.

Operácie a stav: práca s API

Povrch REST sprístupňuje metódy ako napríklad fileSearchStores.create (vytvorí prázdny obchod), fileSearchStores.delete (odstraňuje obchod), fileSearchStores.get (získava informácie z obchodu), fileSearchStores.list (zoznam obchodov používateľov) a importFile (záleží na tom File (zo súborovej služby do úložiska). Koncové body operácie vám umožní skontrolovať stav dlhodobé operácies formulármi žiadostí, ktoré v niekoľkých prípadoch idú prázdny podľa špecifikácie.

Na priamej trase do kopca (uploadToFileSearchStoreSada operácie Špeciálne navrhnuté na meranie pokroku. Tento vzorec je typický: kopije operácia, skontrolujete pravidelne, ak je hotové a kedy kompletný, pokračujete v postupe (napríklad spustením RAG dotazov).

Najlepšie postupy: filtre, označovanie a latencia

Ak očakávate veľa otázok, označte si dokumenty metadáta a zamestnať metadataFilter obmedziť vyhľadávanie na relevantné podmnožiny. Uchovávajte úložiská v rámci odporúčaná veľkosť Pomáha to s latenciou a stabilitou. A ak sa chystáte nabíjať plné priečinkyVyužíva súbežný nárast na skrátenie času požitia.

V technických scenároch definujte stratégie rozdelenia do blokov podľa obsahu: napríklad kratšie bloky s miernym prekrytím pre kód (lepšia presnosť vo funkciách/triedach) a o niečo dlhšie bloky v naratívnej dokumentácii na zachovanie sémantického kontextu.

Kompatibilita s inými nástrojmi Gemini

Uzemnenie pomocou Vyhľadávania Google je možné kombinovať s kontextom URL (na poskytnutie konkrétnych URL) a s vykonávaním kódu alebo ďalšími funkciami nástrojov v závislosti od prípadu použitia. To vám umožňuje spojiť interné znalosti vyhľadávania súborov s aktuálnymi webovými informáciami a vždy zachovať citácie a stopy zdrojov.

Pri navrhovaní používateľského rozhrania využite funkcie groundingSupports a groundingChunks na poskytovanie klikateľných citácií popri texte modelu. Toto je najprehľadnejší spôsob, ako si používatelia môžu overiť zdroj každého tvrdenia.

Vyhľadávanie súborov v rozhraní Gemini API ponúka priamu cestu k poskytovaniu dobre podložených odpovedí vašim aplikáciám na základe vašich vlastných údajov a minimalizuje prevádzkové trenie. Jeho kombinácia predvídateľných nákladov na indexovanie, podpory rôznych formátov, filtrov metadát, automatických citácií a prepojenia s Vyhľadávaním Google vytvára balík pripravený na produkciu, ktorý zjednodušuje implementáciu RAG v tímoch všetkých veľkostí.