Penelusuran File

Gemini API memungkinkan Retrieval Augmented Generation ("RAG") melalui alat Penelusuran File. Penelusuran File mengimpor, membagi, dan mengindeks data Anda untuk memungkinkan pengambilan informasi yang relevan dengan cepat berdasarkan perintah pengguna. Informasi ini kemudian diberikan sebagai konteks ke model, sehingga model dapat memberikan jawaban yang lebih akurat dan relevan.

Anda dapat menggunakan uploadToFileSearchStore API untuk mengupload file yang ada secara langsung ke penyimpanan penelusuran file, atau mengupload dan mengimpor file secara terpisah jika Anda ingin membuat file pada saat yang sama.

Mengupload langsung ke toko penelusuran file

Contoh ini menunjukkan cara mengupload file secara langsung ke penyimpanan file:

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)

Mengimpor file

Atau, Anda dapat mengupload file yang ada dan mengimpornya ke penyimpanan file Anda:

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)

Konfigurasi pemotongan

Saat Anda mengimpor file ke penyimpanan penelusuran file, file tersebut akan otomatis dipecah menjadi beberapa bagian, disematkan, diindeks, dan diupload ke penyimpanan penelusuran file Anda. Jika Anda membutuhkan kontrol yang lebih besar atas strategi chunking, Anda dapat menentukan setelan chunking_config untuk menetapkan jumlah maksimum token per chunk dan jumlah maksimum token yang tumpang-tindih.

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

Untuk menggunakan penyimpanan penelusuran file Anda, teruskan sebagai alat ke metode generateContent, seperti yang ditunjukkan dalam contoh Upload dan Impor.

Cara kerjanya

Penelusuran File menggunakan teknik yang disebut penelusuran semantik untuk menemukan informasi yang relevan dengan perintah pengguna. Tidak seperti penelusuran berbasis kata kunci tradisional, penelusuran semantik memahami makna dan konteks kueri Anda.

Saat Anda mengimpor file, file tersebut akan dikonversi menjadi representasi numerik yang disebut embedding, yang menangkap makna semantik teks. Embedding ini disimpan dalam database penelusuran file khusus. Saat Anda membuat kueri, kueri tersebut juga dikonversi menjadi embedding. Kemudian, sistem melakukan penelusuran file untuk menemukan potongan dokumen yang paling mirip dan relevan dari penyimpanan penelusuran file.

Berikut perincian proses penggunaan File Search uploadToFileSearchStore API:

1. Membuat penyimpanan penelusuran file: Penyimpanan penelusuran file berisi data yang diproses dari file Anda. Ini adalah penampung persisten untuk sematan yang akan dioperasikan oleh penelusuran semantik.

2. Mengupload file dan mengimpor ke penyimpanan penelusuran file: Mengupload file dan mengimpor hasil ke penyimpanan penelusuran file secara bersamaan. Tindakan ini akan membuat objek File sementara, yang merupakan referensi ke dokumen mentah Anda. Data tersebut kemudian dibagi-bagi, dikonversi menjadi embedding penelusuran file, dan diindeks. Objek File akan dihapus setelah 48 jam, sedangkan data yang diimpor ke penyimpanan penelusuran file akan disimpan tanpa batas waktu hingga Anda memilih untuk menghapusnya.

3. Kueri dengan Penelusuran File: Terakhir, Anda menggunakan alat FileSearch dalam panggilan generateContent. Dalam konfigurasi alat, Anda menentukan FileSearchRetrievalResource, yang mengarah ke FileSearchStore yang ingin Anda telusuri. Hal ini memberi tahu model untuk melakukan penelusuran semantik di penyimpanan penelusuran file tertentu tersebut untuk menemukan informasi yang relevan guna mendasari responsnya.

Dalam diagram ini, garis putus-putus dari Documents ke Embedding model (menggunakan gemini-embedding-001) merepresentasikan uploadToFileSearchStore API (melewati File storage). Jika tidak, menggunakan Files API untuk membuat dan mengimpor file secara terpisah akan memindahkan proses pengindeksan dari Dokumen ke Penyimpanan file, lalu ke Model sematan.

Penyimpanan penelusuran file

Penyimpanan penelusuran file adalah container untuk embedding dokumen Anda. Meskipun file mentah yang diupload melalui File API dihapus setelah 48 jam, data yang diimpor ke toko penelusuran file disimpan tanpa batas waktu hingga Anda menghapusnya secara manual. Anda dapat membuat beberapa penyimpanan penelusuran file untuk mengatur dokumen Anda. API FileSearchStore memungkinkan Anda membuat, mencantumkan, mendapatkan, dan menghapus untuk mengelola penyimpanan penelusuran file Anda. Nama toko penelusuran file memiliki cakupan global.

Berikut beberapa contoh cara mengelola toko penelusuran file Anda:

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

Metadata file

Anda dapat menambahkan metadata kustom ke file untuk membantu memfilter atau memberikan konteks tambahan. Metadata adalah sekumpulan key-value pair.

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

Hal ini berguna jika Anda memiliki beberapa dokumen di penyimpanan penelusuran file dan ingin menelusuri hanya sebagian dokumen tersebut.

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

Panduan tentang penerapan sintaksis filter daftar untuk metadata_filter dapat ditemukan di google.aip.dev/160

Kutipan

Saat Anda menggunakan Penelusuran File, respons model dapat menyertakan kutipan yang menentukan bagian dokumen yang Anda upload yang digunakan untuk membuat jawaban. Hal ini membantu dalam pengecekan fakta dan verifikasi.

Anda dapat mengakses informasi kutipan melalui atribut grounding_metadata respons.

print(response.candidates[0].grounding_metadata)

Model yang didukung

Model berikut mendukung Penelusuran File:

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

Jenis file yang didukung

Penelusuran File mendukung berbagai format file, yang tercantum di bagian berikut.

Batas kapasitas

File Search API memiliki batas berikut untuk menerapkan stabilitas layanan:

• Ukuran file maksimum / batas per dokumen: 100 MB
• Penyimpanan penelusuran file per project: 10
• Total ukuran penyimpanan penelusuran file project (berdasarkan tingkat pengguna):
  • Gratis: 1 GB
  • Tingkat 1: 10 GB
  • Paket 2: 100 GB
  • Tingkat 3: 1 TB
• Rekomendasi: Batasi ukuran setiap penyimpanan penelusuran file hingga di bawah 20 GB untuk memastikan latensi pengambilan yang optimal.

Harga

• Developer dikenai biaya untuk penyematan pada waktu pengindeksan berdasarkan harga penyematan yang ada ($0,15 per 1 juta token).
• Penyimpanan tidak dikenai biaya.
• Penyematan waktu kueri tidak dikenai biaya.
• Token dokumen yang diambil akan ditagih sebagai token konteks reguler.