البحث عن الملفات

تتيح Gemini API ميزة "التوليد المعزّز بالاسترجاع" (RAG) من خلال أداة "البحث في الملفات". تستورد ميزة "البحث عن الملفات" بياناتك وتقسّمها وتفهرسها لتتيح استرجاع المعلومات ذات الصلة بسرعة استنادًا إلى طلب المستخدم. ثم يتم تقديم هذه المعلومات كسياق للنموذج، ما يتيح له تقديم إجابات أكثر دقة وملاءمةً.

يمكنك استخدام واجهة برمجة التطبيقات 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، كما هو موضّح في المثالَين تحميل واستيراد.

آلية العمل

تستخدم ميزة "البحث عن الملفات" أسلوبًا يُعرف باسم البحث الدلالي للعثور على معلومات ذات صلة بطلب المستخدم. على عكس البحث التقليدي المستند إلى الكلمات الرئيسية، يفهم البحث الدلالي المعنى والسياق الخاصين بطلب البحث الذي تجريه.

عند استيراد ملف، يتم تحويله إلى تمثيلات رقمية تُعرف باسم التضمينات، وهي تلتقط المعنى الدلالي للنص. يتم تخزين هذه التضمينات في قاعدة بيانات متخصصة للبحث عن الملفات. عند إجراء طلب بحث، يتم تحويله أيضًا إلى تضمين. بعد ذلك، يجري النظام بحثًا عن الملفات للعثور على أجزاء المستندات الأكثر تشابهًا وملاءمةً من مستودع البحث عن الملفات.

في ما يلي تفصيل لعملية استخدام واجهة برمجة التطبيقات File Search uploadToFileSearchStore:

1. إنشاء مستودع بحث عن الملفات: يحتوي مستودع البحث عن الملفات على البيانات المعالَجة من ملفاتك. وهي الحاوية الدائمة لعمليات التضمين التي سيتم إجراء البحث الدلالي عليها.

2. تحميل ملف واستيراده إلى مستودع بحث عن الملفات: يمكنك تحميل ملف واستيراد النتائج إلى مستودع بحث عن الملفات في الوقت نفسه. يؤدي ذلك إلى إنشاء كائن File مؤقت، وهو مرجع إلى مستندك الأولي. يتم بعد ذلك تقسيم هذه البيانات إلى أجزاء، وتحويلها إلى تضمينات للبحث عن الملفات، وفهرستها. يتم حذف Fileالكائن بعد 48 ساعة، بينما يتم تخزين البيانات التي تم استيرادها إلى مساحة تخزين البحث عن الملفات إلى أجل غير مسمى إلى أن تختار حذفها.

3. طلب البحث باستخدام "البحث عن الملفات": أخيرًا، يمكنك استخدام أداة FileSearch في مكالمة generateContent. في إعدادات الأداة، عليك تحديد FileSearchRetrievalResource، يشير إلى FileSearchStore الذي تريد البحث فيه. يطلب ذلك من النموذج إجراء بحث دلالي في مخزن البحث عن الملفات المحدّد هذا للعثور على معلومات ذات صلة يستند إليها في رده.

في هذا الرسم التخطيطي، يمثّل الخط المتقطّع من المستندات إلى نموذج التضمين (باستخدام gemini-embedding-001) واجهة برمجة التطبيقات uploadToFileSearchStore (مع تجاوز تخزين الملفات). في ما عدا ذلك، يؤدي استخدام Files API لإنشاء الملفات بشكل منفصل ثم استيرادها إلى نقل عملية الفهرسة من المستندات إلى مساحة تخزين الملفات ثم إلى نموذج التضمين.

متاجر البحث عن الملفات

مخزن البحث عن الملفات هو حاوية لتضمينات المستندات. في حين يتم حذف الملفات الأولية التي تم تحميلها من خلال File API بعد 48 ساعة، يتم تخزين البيانات التي تم استيرادها إلى مستودع بحث الملفات إلى أجل غير مسمى إلى أن تحذفها يدويًا. يمكنك إنشاء عدة مخازن للبحث عن الملفات لتنظيم مستنداتك. تتيح لك واجهة برمجة التطبيقات 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

أنواع الملفات المعتمدة

يتيح "بحث الملفات" مجموعة كبيرة من تنسيقات الملفات، وهي مدرَجة في الأقسام التالية.

حدود معدّل الاستخدام

تفرض واجهة File Search API الحدود التالية لضمان استقرار الخدمة:

• الحد الأقصى لحجم الملف / الحد الأقصى لكل مستند: 100 ميغابايت
• عمليات البحث عن الملفات المخزّنة لكل مشروع: 10
• إجمالي حجم مساحات تخزين البحث عن ملفات المشاريع (استنادًا إلى فئة المستخدم):
  • مجانًا: 1 غيغابايت
  • المستوى 1: 10 غيغابايت
  • المستوى 2: ‏100 غيغابايت
  • المستوى 3: 1 تيرابايت
• اقتراح: يجب ألا يتجاوز حجم كل مستودع بحث عن الملفات 20 غيغابايت لضمان أفضل أوقات استرجاع.

الأسعار

• يتم تحصيل رسوم من المطوّرين مقابل عمليات التضمين في وقت الفهرسة استنادًا إلى أسعار التضمين الحالية (0.15 دولار أمريكي لكل مليون رمز مميز).
• تتوفر خدمة تخزين الأمتعة مجانًا.
• إنّ تضمينات وقت طلب البحث مجانية.
• يتم تحصيل رسوم من الرموز المميزة للمستندات التي تم استردادها باعتبارها رموزًا مميزة للسياق عادية.