Tìm kiếm tệp

Gemini API cho phép tạo thông tin tăng cường dựa trên truy xuất ("RAG") thông qua công cụ Tìm kiếm tệp. Tính năng Tìm kiếm tệp nhập, chia thành khối và lập chỉ mục dữ liệu của bạn để cho phép truy xuất nhanh thông tin liên quan dựa trên câu lệnh của người dùng. Sau đó, thông tin này được cung cấp dưới dạng bối cảnh cho mô hình, cho phép mô hình đưa ra câu trả lời chính xác và phù hợp hơn.

Bạn có thể dùng API uploadToFileSearchStore để tải trực tiếp một tệp hiện có lên kho lưu trữ tìm kiếm tệp hoặc tải lên riêng rồi nhập tệp nếu muốn tạo tệp cùng lúc.

Tải trực tiếp lên kho lưu trữ tìm kiếm tệp

Ví dụ này cho thấy cách tải trực tiếp một tệp lên một kho lưu trữ tệp:

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)

Nhập tệp

Ngoài ra, bạn có thể tải một tệp hiện có lên và nhập tệp đó vào kho lưu trữ tệp:

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)

Cấu hình phân đoạn

Khi bạn nhập một tệp vào kho lưu trữ tìm kiếm tệp, tệp đó sẽ tự động được chia thành các đoạn, được nhúng, lập chỉ mục và tải lên kho lưu trữ tìm kiếm tệp. Nếu cần kiểm soát thêm về chiến lược phân đoạn, bạn có thể chỉ định chế độ cài đặt chunking_config để đặt số lượng mã thông báo tối đa cho mỗi đoạn và số lượng mã thông báo trùng lặp tối đa.

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

Để sử dụng kho lưu trữ tìm kiếm tệp, hãy truyền kho lưu trữ đó dưới dạng một công cụ cho phương thức generateContent, như trong ví dụ Tải lên và Nhập.

Cách hoạt động

Tính năng Tìm kiếm tệp sử dụng một kỹ thuật gọi là tìm kiếm ngữ nghĩa để tìm thông tin liên quan đến câu lệnh của người dùng. Không giống như tìm kiếm truyền thống dựa trên từ khoá, tìm kiếm ngữ nghĩa hiểu được ý nghĩa và bối cảnh của cụm từ tìm kiếm.

Khi bạn nhập một tệp, tệp đó sẽ được chuyển đổi thành các biểu diễn bằng số gọi là embedding (dữ liệu nhúng), giúp nắm bắt ý nghĩa ngữ nghĩa của văn bản. Các vectơ nhúng này được lưu trữ trong một cơ sở dữ liệu tìm kiếm tệp chuyên biệt. Khi bạn đưa ra một câu hỏi, câu hỏi đó cũng sẽ được chuyển đổi thành một vectơ nhúng. Sau đó, hệ thống sẽ thực hiện tìm kiếm tệp để tìm các đoạn tài liệu tương tự và phù hợp nhất trong kho lưu trữ tìm kiếm tệp.

Sau đây là quy trình sử dụng API Tìm kiếm tệp uploadToFileSearchStore:

1. Tạo một kho lưu trữ tìm kiếm tệp: Kho lưu trữ tìm kiếm tệp chứa dữ liệu đã xử lý từ các tệp của bạn. Đây là vùng chứa liên tục cho các mục nhúng mà tính năng tìm kiếm ngữ nghĩa sẽ hoạt động.

2. Tải tệp lên và nhập vào kho lưu trữ tìm kiếm tệp: Tải đồng thời một tệp lên và nhập kết quả vào kho lưu trữ tìm kiếm tệp. Thao tác này sẽ tạo một đối tượng File tạm thời, là một tham chiếu đến tài liệu thô của bạn. Sau đó, dữ liệu đó sẽ được chia thành các khối, chuyển đổi thành các mục nhúng tìm kiếm tệp và được lập chỉ mục. Đối tượng File sẽ bị xoá sau 48 giờ, trong khi dữ liệu được nhập vào kho lưu trữ tìm kiếm tệp sẽ được lưu trữ vô thời hạn cho đến khi bạn chọn xoá dữ liệu đó.

3. Truy vấn bằng tính năng Tìm kiếm tệp: Cuối cùng, bạn sử dụng công cụ FileSearch trong lệnh gọi generateContent. Trong cấu hình công cụ, bạn chỉ định một FileSearchRetrievalResource, trỏ đến FileSearchStore mà bạn muốn tìm kiếm. Điều này yêu cầu mô hình thực hiện một tìm kiếm ngữ nghĩa trên kho lưu trữ tìm kiếm tệp cụ thể đó để tìm thông tin liên quan nhằm củng cố câu trả lời của mô hình.

Trong sơ đồ này, đường nét đứt từ Documents (Tài liệu) đến Embedding model (Mô hình nhúng) (sử dụng gemini-embedding-001) biểu thị API uploadToFileSearchStore (bỏ qua File storage (Bộ nhớ tệp)). Nếu không, việc sử dụng Files API để tạo riêng rồi nhập tệp sẽ di chuyển quy trình lập chỉ mục từ Documents (Tài liệu) sang File storage (Bộ nhớ tệp) rồi đến Embedding model (Mô hình nhúng).

Lưu trữ nội dung tìm kiếm tệp

Kho lưu trữ tìm kiếm tệp là một vùng chứa cho các vectơ nhúng tài liệu của bạn. Mặc dù các tệp thô được tải lên thông qua File API sẽ bị xoá sau 48 giờ, nhưng dữ liệu được nhập vào một kho lưu trữ tìm kiếm tệp sẽ được lưu trữ vô thời hạn cho đến khi bạn xoá dữ liệu đó theo cách thủ công. Bạn có thể tạo nhiều kho lưu trữ tìm kiếm tệp để sắp xếp tài liệu. API FileSearchStore cho phép bạn tạo, liệt kê, nhận và xoá để quản lý các kho lưu trữ tìm kiếm tệp. Tên cửa hàng tìm kiếm tệp có phạm vi trên toàn cầu.

Sau đây là một số ví dụ về cách quản lý các kho lưu trữ tìm kiếm tệp:

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

Siêu dữ liệu tệp

Bạn có thể thêm siêu dữ liệu tuỳ chỉnh vào tệp để lọc hoặc cung cấp thêm bối cảnh. Siêu dữ liệu là một tập hợp các cặp khoá-giá trị.

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

Điều này sẽ hữu ích khi bạn có nhiều tài liệu trong một kho lưu trữ tìm kiếm tệp và chỉ muốn tìm kiếm một nhóm nhỏ trong số đó.

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

Bạn có thể xem hướng dẫn về cách triển khai cú pháp bộ lọc danh sách cho metadata_filter tại google.aip.dev/160

Trích dẫn

Khi bạn sử dụng tính năng Tìm kiếm tệp, câu trả lời của mô hình có thể bao gồm các trích dẫn nêu rõ những phần nào trong tài liệu bạn tải lên được dùng để tạo câu trả lời. Điều này giúp ích cho việc kiểm chứng và xác minh.

Bạn có thể truy cập thông tin trích dẫn thông qua thuộc tính grounding_metadata của phản hồi.

print(response.candidates[0].grounding_metadata)

Mô hình được hỗ trợ

Các mô hình sau đây hỗ trợ tính năng Tìm kiếm tệp:

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

Các loại tệp được hỗ trợ

Tính năng Tìm kiếm tệp hỗ trợ nhiều định dạng tệp, được liệt kê trong các phần sau.

Giới hạn số lượng yêu cầu

API Tìm kiếm tệp có các giới hạn sau để đảm bảo tính ổn định của dịch vụ:

• Kích thước tệp tối đa / giới hạn cho mỗi tài liệu: 100 MB
• Số lượt tìm kiếm tệp được lưu trữ cho mỗi dự án: 10
• Tổng kích thước của các kho lưu trữ tìm kiếm tệp dự án (dựa trên cấp người dùng):
  • Miễn phí: 1 GB
  • Cấp 1: 10 GB
  • Lớp 2: 100 GB
  • Cấp 3: 1 TB
• Đề xuất: Giới hạn kích thước của mỗi kho lưu trữ tìm kiếm tệp dưới 20 GB để đảm bảo độ trễ truy xuất tối ưu.

Giá

• Nhà phát triển bị tính phí cho các mục nhúng tại thời điểm lập chỉ mục dựa trên mức giá hiện tại của mục nhúng (0,15 USD cho mỗi 1 triệu mã thông báo).
• Bộ nhớ miễn phí.
• Bạn không phải trả phí cho các vectơ nhúng thời gian truy vấn.
• Các mã thông báo tài liệu đã truy xuất được tính phí như mã thông báo ngữ cảnh thông thường.