Dosya Arama

Gemini API, Dosya Arama aracıyla almayla artırılmış üretim ("RAG") sağlar. Dosya Arama, kullanıcının istemine göre alakalı bilgilerin hızlıca alınmasını sağlamak için verilerinizi içe aktarır, parçalara ayırır ve dizine ekler. Bu bilgiler daha sonra modele bağlam olarak sağlanır ve modelin daha doğru ve alakalı yanıtlar vermesine olanak tanır.

Mevcut bir dosyayı doğrudan dosya arama mağazanıza yüklemek için uploadToFileSearchStore API'yi kullanabilir veya dosyayı aynı anda oluşturmak istiyorsanız dosyayı ayrı olarak yükleyip içe aktarabilirsiniz.

Doğrudan dosya arama mağazasına yükleme

Bu örnekte, bir dosyanın doğrudan dosya deposuna nasıl yükleneceği gösterilmektedir:

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)

Dosyaları içe aktarma

Alternatif olarak, mevcut bir dosyayı yükleyip dosya deponuza aktarabilirsiniz:

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)

Parçalara ayırma yapılandırması

Bir dosyayı dosya arama deposuna aktardığınızda dosya otomatik olarak parçalara ayrılır, yerleştirilir, dizine eklenir ve dosya arama deponuza yüklenir. Parçalama stratejisi üzerinde daha fazla kontrol sahibi olmak istiyorsanız parça başına maksimum jeton sayısı ve maksimum çakışan jeton sayısı belirlemek için bir chunking_config ayarı belirtebilirsiniz.

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

Dosya arama mağazanızı kullanmak için generateContent yöntemine araç olarak iletin. Bu işlem, Yükleme ve İçe Aktarma örneklerinde gösterilmiştir.

İşleyiş şekli

Dosya Arama, kullanıcı istemiyle alakalı bilgileri bulmak için semantik arama adı verilen bir teknik kullanır. Geleneksel anahtar kelime tabanlı aramanın aksine, semantik arama sorgunuzun anlamını ve bağlamını anlar.

İçe aktardığınız dosyalar, metnin semantik anlamını yakalayan yerleştirmeler adı verilen sayısal gösterimlere dönüştürülür. Bu yerleştirmeler, özel bir dosya arama veritabanında saklanır. Sorgularınız da yerleştirmeye dönüştürülür. Ardından sistem, dosya arama deposunda en benzer ve alakalı belge parçalarını bulmak için dosya araması yapar.

Dosya Arama API'sini kullanma sürecinin dökümünü aşağıda bulabilirsiniz: uploadToFileSearchStore

1. Dosya arama deposu oluşturma: Dosya arama deposu, dosyalarınızdaki işlenmiş verileri içerir. Bu, semantik aramanın üzerinde çalışacağı yerleştirmeler için kalıcı kapsayıcıdır.

2. Dosya yükleme ve dosya arama deposuna aktarma: Aynı anda dosya yükleyin ve sonuçları dosya arama deponuza aktarın. Bu işlem, ham dokümanınıza referans veren geçici bir File nesnesi oluşturur. Bu veriler daha sonra parçalara ayrılır, dosya arama yerleştirmelerine dönüştürülür ve dizine eklenir. File Nesne 48 saat sonra silinir. Dosya arama deposuna aktarılan veriler ise siz silmeyi seçene kadar süresiz olarak saklanır.

3. Dosya Arama ile sorgu: Son olarak, generateContent görüşmesinde FileSearch aracını kullanırsınız. Araç yapılandırmasında, aramak istediğiniz FileSearchStore öğesini işaret eden bir FileSearchRetrievalResource belirtirsiniz. Bu, modele yanıtını temellendirmek için alakalı bilgileri bulmak üzere söz konusu dosya arama deposunda anlamsal arama yapmasını söyler.

Bu şemada, Belgeler'den Yerleştirme modeli'ne (gemini-embedding-001 kullanılarak) giden noktalı çizgi, uploadToFileSearchStore API'yi (Dosya depolama'yı atlayarak) temsil eder. Aksi takdirde, dosyaları ayrı ayrı oluşturup içe aktarmak için Files API'yi kullanmak, dizine ekleme sürecini Belgeler'den Dosya depolama'ya ve ardından Yerleştirme modeli'ne taşır.

Dosya arama mağazaları

Dosya arama deposu, doküman yerleştirmelerinizin bulunduğu bir kapsayıcıdır. File API aracılığıyla yüklenen ham dosyalar 48 saat sonra silinirken, dosya arama deposuna aktarılan veriler siz manuel olarak silene kadar süresiz olarak saklanır. Dokümanlarınızı düzenlemek için birden fazla dosya arama deposu oluşturabilirsiniz. FileSearchStore API, dosya arama depolarınızı yönetmek için oluşturma, listeleme, alma ve silme işlemlerini yapmanıza olanak tanır. Dosya arama mağazası adları küresel kapsamlıdır.

Dosya arama depolarınızı nasıl yönetebileceğinize dair bazı örnekleri aşağıda bulabilirsiniz:

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

Dosya meta verileri

Dosyalarınızı filtrelemenize veya ek bağlam bilgisi sağlamanıza yardımcı olması için dosyalarınıza özel meta veriler ekleyebilirsiniz. Meta veriler, anahtar/değer çiftlerinden oluşan bir settir.

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

Bu özellik, bir dosya arama deposunda birden fazla dokümanınız olduğunda ve yalnızca bunların bir alt kümesinde arama yapmak istediğinizde kullanışlıdır.

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

metadata_filter için liste filtresi söz dizimini uygulama ile ilgili yönergeleri google.aip.dev/160 adresinde bulabilirsiniz.

Alıntılar

Dosya Arama'yı kullandığınızda modelin yanıtı, yüklenen dokümanlarınızın hangi bölümlerinin yanıtı oluşturmak için kullanıldığını belirten alıntılar içerebilir. Bu, doğruluk kontrolü ve doğrulama işlemlerine yardımcı olur.

Alıntı bilgilerine yanıtın grounding_metadata özelliği üzerinden erişebilirsiniz.

print(response.candidates[0].grounding_metadata)

Desteklenen modeller

Aşağıdaki modellerde Dosya Arama özelliği desteklenir:

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

Desteklenen dosya türleri

Dosya Arama, aşağıdaki bölümlerde listelenen çok çeşitli dosya biçimlerini destekler.

Hız sınırları

File Search API, hizmet kararlılığını sağlamak için aşağıdaki sınırlara sahiptir:

• Maksimum dosya boyutu / belge başına sınır: 100 MB
• Proje başına dosya arama depolama alanı: 10
• Proje dosyası arama depolarının toplam boyutu (kullanıcı katmanına göre):
  • Ücretsiz: 1 GB
  • Katman 1: 10 GB
  • 2. katman: 100 GB
  • 3. Katman: 1 TB
• Öneri: Optimal alma gecikmeleri sağlamak için her dosya arama deposunun boyutunu 20 GB'ın altında tutun.

Fiyatlandırma

• Geliştiricilerden, mevcut gömme fiyatlandırmasına (1 milyon jeton başına 0,15 ABD doları) göre dizine ekleme sırasında gömmeler için ücret alınır.
• Depolama alanı ücretsizdir.
• Sorgu zamanı yerleştirmeleri ücretsizdir.
• Alınan doküman jetonları normal bağlam jetonları olarak ücretlendirilir.