חיפוש קבצים

‫Gemini API מאפשר יצירה משופרת של מידע (RAG) באמצעות הכלי FileSearch. הכלי 'חיפוש קבצים' מייבא את הנתונים, מחלק אותם לחלקים קטנים ויוצר אינדקס כדי לאפשר שליפה מהירה של מידע רלוונטי על סמך הנחיה של משתמש. המידע הזה מסופק למודל כהקשר, וכך המודל יכול לספק תשובות מדויקות ורלוונטיות יותר.

אתם יכולים להשתמש ב-uploadToFileSearchStore API כדי להעלות ישירות קובץ קיים למאגר הקבצים של חיפוש, או להעלות קובץ בנפרד ואז לייבא אותו אם אתם רוצים ליצור את הקובץ בו-זמנית.

העלאה ישירה למאגר של חיפוש קבצים

בדוגמה הזו אפשר לראות איך מעלים קובץ ישירות למאגר קבצים:

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, כמו בדוגמאות של העלאה וייבוא.

איך זה עובד

בחיפוש קבצים נעשה שימוש בטכניקה שנקראת חיפוש סמנטי כדי למצוא מידע שרלוונטי להנחיה של המשתמש. בניגוד לחיפוש מסורתי שמבוסס על מילות מפתח, חיפוש סמנטי מבין את המשמעות וההקשר של השאילתה.

כשמייבאים קובץ, הוא מומר לייצוגים מספריים שנקראים הטמעות, שמשקפים את המשמעות הסמנטית של הטקסט. ההטמעות האלה מאוחסנות במסד נתונים מיוחד לחיפוש קבצים. כשמבצעים שאילתה, היא מומרת גם להטמעה. לאחר מכן, המערכת מבצעת חיפוש בקובץ כדי למצוא את חלקי המסמך הכי דומים ורלוונטיים ממאגר החיפוש בקובץ.

פירוט התהליך לשימוש ב-File Search uploadToFileSearchStore API:

1. יצירת מאגר לחיפוש קבצים: מאגר לחיפוש קבצים מכיל את הנתונים המעובדים מהקבצים שלכם. זהו מאגר קבוע של ההטמעות שהחיפוש הסמנטי יפעל עליהן.

2. העלאת קובץ וייבוא שלו למאגר לחיפוש קבצים: העלאה של קובץ וייבוא של התוצאות למאגר לחיפוש קבצים. הפעולה הזו יוצרת אובייקט File זמני, שהוא הפניה למסמך הגולמי. הנתונים האלה מחולקים לחלקים, מומרים להטמעות של חיפוש קבצים ונוספים לאינדקס. File האובייקט נמחק אחרי 48 שעות, אבל הנתונים שיובאו למאגר של חיפוש הקבצים יישמרו ללא הגבלת זמן עד שתבחרו למחוק אותם.

3. שאילתה באמצעות חיפוש קבצים: לבסוף, משתמשים בכלי FileSearch בשיחה עם generateContent. בהגדרת הכלי, מציינים FileSearchRetrievalResource, שמפנה אל FileSearchStore שרוצים לחפש. ההנחיה הזו אומרת למודל לבצע חיפוש סמנטי במאגר החיפוש של הקובץ הספציפי הזה כדי למצוא מידע רלוונטי שישמש כבסיס לתשובה.

בתרשים הזה, הקו המקווקו מDocuments אל Embedding model (באמצעות gemini-embedding-001) מייצג את uploadToFileSearchStore API (בלי לעבור דרך File storage). אחרת, שימוש ב-Files API כדי ליצור בנפרד ואז לייבא קבצים מעביר את תהליך האינדוקס ממסמכים לאחסון קבצים ואז למודל הטמעה.

חיפוש בחנויות קבצים

מאגר חיפוש קבצים הוא מאגר להטמעות של המסמכים שלכם. קובצי RAW שהועלו דרך File API נמחקים אחרי 48 שעות, אבל הנתונים שיובאו למאגר חיפוש קבצים נשמרים ללא הגבלת זמן עד למחיקה ידנית. אתם יכולים ליצור כמה מאגרי חיפוש של קבצים כדי לארגן את המסמכים שלכם. ‫FileSearchStore API מאפשר לכם ליצור, לרשום, לקבל ולמחוק כדי לנהל את חנויות החיפוש של הקבצים. שמות החנויות בחיפוש קבצים הם בהיקף גלובלי.

ריכזנו כאן כמה דוגמאות לניהול של חנויות לחיפוש קבצים:

# 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

סוגי קבצים נתמכים

חיפוש קבצים תומך במגוון רחב של פורמטים של קבצים, שמפורטים בקטעים הבאים.

מגבלות קצב

כדי לשמור על יציבות השירות, יש הגבלות על File Search API:

• גודל קובץ מקסימלי / מגבלה לכל מסמך: 100MB
• חיפוש קבצים מאוחסן לכל פרויקט: 10
• הגודל הכולל של מאגרי החיפוש של קבצי הפרויקט (על סמך רמת המשתמש):
  • בחינם: 1GB
  • רמה 1: 10GB
  • רמה 2: 100GB
  • רמה 3: 1TB
• המלצה: כדי להבטיח חביון אופטימלי של אחזור נתונים, מומלץ להגביל את הגודל של כל קובץ של חנות חיפוש ל-20GB.

תמחור

• מפתחים מחויבים על הטמעות בזמן יצירת האינדקס על סמך תמחור ההטמעות הקיים (‎0.15$‎ למיליון טוקנים).
• האחסון הוא בחינם.
• הטמעות בזמן השאילתה הן בחינם.
• האסימונים של המסמכים שאוחזרו מחויבים כאסימוני הקשר רגילים.