جستجوی فایل

رابط برنامه‌نویسی نرم‌افزار Gemini از طریق ابزار جستجوی فایل، امکان بازیابی افزوده ("RAG") را فراهم می‌کند. جستجوی فایل، داده‌های شما را وارد، تکه‌بندی و فهرست‌بندی می‌کند تا بازیابی سریع اطلاعات مرتبط را بر اساس درخواست کاربر امکان‌پذیر سازد. سپس این اطلاعات به عنوان زمینه در مدل ارائه می‌شود و به مدل اجازه می‌دهد پاسخ‌های دقیق‌تر و مرتبط‌تری ارائه دهد.

شما می‌توانید از API uploadToFileSearchStore برای آپلود مستقیم یک فایل موجود در فروشگاه جستجوی فایل خود استفاده کنید، یا اگر می‌خواهید همزمان فایل را ایجاد کنید، آن را جداگانه آپلود و سپس وارد کنید.

مستقیماً در فروشگاه جستجوی فایل بارگذاری کنید

این مثال‌ها نحوه آپلود مستقیم فایل در یک فروشگاه فایل را نشان می‌دهند:

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)

وارد کردن فایل‌ها

روش دیگر، آپلود یک فایل موجود و وارد کردن آن به فروشگاه فایل شماست:

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)

پیکربندی قطعه‌بندی

وقتی فایلی را به یک فروشگاه جستجوی فایل وارد می‌کنید، به طور خودکار به تکه‌هایی تقسیم می‌شود، جاسازی می‌شود، فهرست‌بندی می‌شود و در فروشگاه جستجوی فایل شما آپلود می‌شود. اگر به کنترل بیشتری بر استراتژی قطعه‌بندی نیاز دارید، می‌توانید تنظیم chunking_config را برای تنظیم حداکثر تعداد توکن‌ها در هر قطعه و حداکثر تعداد توکن‌های همپوشانی مشخص کنید.

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

برای استفاده از مخزن جستجوی فایل خود، آن را به عنوان ابزاری به متد generateContent ارسال کنید، همانطور که در مثال‌های آپلود و وارد کردن نشان داده شده است.

چگونه کار می‌کند؟

جستجوی فایل از تکنیکی به نام جستجوی معنایی برای یافتن اطلاعات مرتبط با درخواست کاربر استفاده می‌کند. برخلاف جستجوی سنتی مبتنی بر کلمات کلیدی، جستجوی معنایی معنا و زمینه‌ی عبارت مورد نظر شما را درک می‌کند.

وقتی فایلی را وارد می‌کنید، به نمایش‌های عددی به نام جاسازی تبدیل می‌شود که معنای معنایی متن را در بر می‌گیرد. این جاسازی‌ها در یک پایگاه داده تخصصی جستجوی فایل ذخیره می‌شوند. وقتی پرس‌وجو می‌کنید، آن نیز به جاسازی تبدیل می‌شود. سپس سیستم یک جستجوی فایل انجام می‌دهد تا شبیه‌ترین و مرتبط‌ترین تکه‌های سند را از فروشگاه جستجوی فایل پیدا کند.

در اینجا خلاصه‌ای از فرآیند استفاده از API جستجوی فایل uploadToFileSearchStore آمده است:

1. ایجاد یک مخزن جستجوی فایل : یک مخزن جستجوی فایل شامل داده‌های پردازش‌شده از فایل‌های شما است. این مخزن، محفظه‌ای دائمی برای جاسازی‌هایی است که جستجوی معنایی روی آنها عمل خواهد کرد.

2. آپلود فایل و وارد کردن آن به فروشگاه جستجوی فایل : همزمان یک فایل را آپلود کنید و نتایج را به فروشگاه جستجوی فایل خود وارد کنید. این کار یک شیء موقت File ایجاد می‌کند که مرجعی برای سند خام شما است. سپس این داده‌ها تکه‌تکه می‌شوند، به جاسازی‌های جستجوی فایل تبدیل می‌شوند و فهرست‌بندی می‌شوند. شیء File پس از ۴۸ ساعت حذف می‌شود، در حالی که داده‌های وارد شده به فروشگاه جستجوی فایل تا زمانی که تصمیم به حذف آن بگیرید، به طور نامحدود ذخیره می‌شوند.

3. پرس‌وجو با جستجوی فایل : در نهایت، شما از ابزار FileSearch در فراخوانی generateContent استفاده می‌کنید. در پیکربندی ابزار، یک FileSearchRetrievalResource مشخص می‌کنید که به FileSearchStore مورد نظر شما برای جستجو اشاره می‌کند. این به مدل می‌گوید که یک جستجوی معنایی در آن فروشگاه جستجوی فایل خاص انجام دهد تا اطلاعات مرتبط را برای پایه‌گذاری پاسخ خود پیدا کند.

در این نمودار، خط چین از مدل Documents به Embedding (با استفاده از gemini-embedding-001 ) نشان دهنده API uploadToFileSearchStore (با صرف نظر از File storage ) است. در غیر این صورت، استفاده از Files API برای ایجاد و سپس وارد کردن جداگانه فایل‌ها، فرآیند ایندکس گذاری را از Documents به File storage و سپس به Embedding model منتقل می‌کند.

فروشگاه‌های جستجوی فایل

یک مخزن جستجوی فایل، محفظه‌ای برای جاسازی اسناد شماست. در حالی که فایل‌های خام آپلود شده از طریق API فایل پس از ۴۸ ساعت حذف می‌شوند، داده‌های وارد شده به یک مخزن جستجوی فایل به طور نامحدود ذخیره می‌شوند تا زمانی که آن را به صورت دستی حذف کنید. می‌توانید چندین مخزن جستجوی فایل برای سازماندهی اسناد خود ایجاد کنید. API FileSearchStore به شما امکان می‌دهد تا مخازن جستجوی فایل خود را ایجاد، فهرست، دریافت و حذف کنید. نام‌های مخزن جستجوی فایل به صورت سراسری تعریف شده‌اند.

در اینجا چند نمونه از نحوه مدیریت فروشگاه‌های جستجوی فایل شما آورده شده است:

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

فراداده فایل

شما می‌توانید فراداده‌های سفارشی را به فایل‌های خود اضافه کنید تا به فیلتر کردن آنها یا ارائه زمینه‌های اضافی کمک کنید. فراداده مجموعه‌ای از جفت‌های کلید-مقدار است.

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

این زمانی مفید است که چندین سند در یک فروشگاه جستجوی فایل دارید و می‌خواهید فقط زیرمجموعه‌ای از آنها را جستجو کنید.

# 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 را می‌توانید در google.aip.dev/160 بیابید.

نقل قول‌ها

وقتی از جستجوی فایل استفاده می‌کنید، پاسخ مدل ممکن است شامل استنادهایی باشد که مشخص می‌کند کدام بخش‌های اسناد آپلود شده شما برای تولید پاسخ استفاده شده‌اند. این به بررسی و تأیید صحت اطلاعات کمک می‌کند.

شما می‌توانید از طریق ویژگی grounding_metadata پاسخ، به اطلاعات استناد دسترسی پیدا کنید.

print(response.candidates[0].grounding_metadata)

مدل‌های پشتیبانی‌شده

مدل‌های زیر از جستجوی فایل پشتیبانی می‌کنند:

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

انواع فایل‌های پشتیبانی‌شده

جستجوی فایل از طیف گسترده‌ای از فرمت‌های فایل پشتیبانی می‌کند که در بخش‌های زیر فهرست شده‌اند.

محدودیت‌های نرخ

API جستجوی فایل برای افزایش پایداری سرویس، محدودیت‌های زیر را دارد:

• حداکثر اندازه فایل / به ازای هر سند : ۱۰۰ مگابایت
• جستجوی فایل در هر پروژه : 10
• حجم کل انباره‌های جستجوی فایل پروژه (بر اساس سطح کاربری):
  • رایگان : ۱ گیگابایت
  • سطح ۱ : ۱۰ گیگابایت
  • ردیف ۲ : ۱۰۰ گیگابایت
  • ردیف ۳ : ۱ ترابایت
• توصیه : اندازه هر مخزن جستجوی فایل را به کمتر از 20 گیگابایت محدود کنید تا از تأخیر بهینه در بازیابی اطمینان حاصل شود.

قیمت‌گذاری

• توسعه‌دهندگان در زمان ایندکس کردن، بر اساس قیمت‌گذاری موجود برای جاسازی‌ها (۰.۱۵ دلار به ازای هر ۱ میلیون توکن) هزینه‌ای برای جاسازی‌ها دریافت می‌کنند.
• انبارداری رایگان است.
• جاسازی‌های زمان پرس‌وجو رایگان هستند.
• توکن‌های سند بازیابی‌شده به عنوان توکن‌های زمینه‌ای معمولی محاسبه می‌شوند.