使用 Google Gemini 檔案搜尋工具進行檢索增強生成 (RAG)

1. 簡介

本程式碼研究室說明如何使用 Gemini 檔案搜尋，在 Agentic 應用程式中啟用 RAG。您可以使用 Gemini 檔案搜尋功能擷取文件並建立索引，不必擔心分塊、嵌入或向量資料庫的詳細資料。

課程內容

  • RAG 的基本概念，以及我們為何需要 RAG。
  • 瞭解 Gemini 檔案搜尋功能及其優點。
  • 如何建立檔案搜尋商店。
  • 如何將自訂檔案上傳至檔案搜尋商店。
  • 如何使用 Gemini 檔案搜尋工具進行 RAG。
  • 使用 Google Agent Development Kit (ADK) 的優點。
  • 瞭解如何在以 ADK 建構的代理解決方案中使用 Gemini 檔案搜尋工具。
  • 如何搭配使用 Gemini 檔案搜尋工具和 Google「原生」工具，例如 Google 搜尋。

學習內容

  • 建立 Google Cloud 專案並設定開發環境。
  • 使用 Google Gen AI SDK (但不使用 ADK) 建立簡單的 Gemini 代理程式，該程式可使用 Google 搜尋，但不具備 RAG 功能。
  • 證明無法提供準確的高品質客製化資訊。
  • 建立 Jupyter 筆記本 (可在本機或 Google Colab 等平台執行)，用於建立及管理 Gemini 檔案搜尋商店。
  • 使用筆記本將自訂內容上傳至檔案搜尋商店。
  • 建立附加檔案搜尋儲存庫的代理，並證明代理可以生成更優質的回覆。
  • 將初始「基本」代理程式轉換為 ADK 代理程式，並加入 Google 搜尋工具。
  • 使用 ADK 網頁介面測試代理程式。
  • 使用 Agent-As-A-Tool 模式，將檔案搜尋商店併入 ADK 代理，以便同時使用檔案搜尋工具和 Google 搜尋工具。

2. 什麼是 RAG？為什麼需要 RAG？

所以... 檢索增強生成。

您應該知道這是什麼，但我們還是快速複習一下。LLM (例如 Gemini) 非常聰明，但有幾個問題：

  1. 資訊永遠過時：模型只會知道訓練期間學到的內容。
  2. 模型並非無所不知：模型雖然龐大，但並非無所不知。
  3. 他們不知道您的專有資訊：他們擁有廣泛的知識，但未讀取您的內部文件、部落格或 Jira 支援單。

因此，當你詢問模型不知道答案的問題時，模型通常會提供不正確或甚至編造的答案。模型通常會自信地給出錯誤答案。這就是所謂的「幻覺」。

其中一個解決方案是直接將專有資訊傾印到對話內容中。如果資訊量不大，這種做法還算可行，但如果資訊量很大，就會迅速產生問題。具體來說，這會導致下列問題：

  1. 延遲：模型的回應速度越來越慢。
  2. 訊號腐化，又稱「中間遺失」：模型無法再從垃圾資料中排序相關資料。模型會忽略大部分的脈絡。
  3. 費用：因為詞元會產生費用。
  4. 脈絡視窗耗盡：此時 Gemini 不會處理您的要求。

如要更有效地解決這個問題，請使用 RAG。這項程序只是從您的資料來源 (使用語意比對) 尋找相關資訊，然後將這些資料的相關區塊連同您的問題提供給模型。根據實際情況建立模型基準。

這項技術的運作方式是匯入外部資料、將資料切分成塊、將資料轉換為向量嵌入，然後將這些嵌入項目儲存並編入合適的向量資料庫。

59f80cd49a8d8fdb.png

因此，如要實作 RAG，通常必須注意以下事項：

  1. 啟動向量資料庫 (Pinecone、Weaviate、Postgres with pgvector...)。
  2. 編寫分塊指令碼，將文件 (例如 PDF、Markdown 等) 分割成多個區塊。
  3. 使用嵌入模型為這些區塊生成嵌入 (向量)。
  4. 將向量儲存在向量資料庫中。

但朋友不會讓朋友過度設計。如果我告訴你有一種更簡單的方法呢？

3. 必要條件

建立 Google Cloud 專案

您需要 Google Cloud 專案才能執行本程式碼研究室。您可以使用現有專案，或建立新專案。

請確認專案已啟用帳單。請參閱這份指南，瞭解如何查看專案的帳單狀態。

請注意，完成本程式碼研究室預計不會產生任何費用。最多只會收取幾分錢。

請準備好專案。我會等。

複製示範存放區

我已建立存放區，其中包含本程式碼研究室的引導式內容。之後一定能派上用場！

從終端機或整合至 Google Cloud Shell 編輯器的終端機執行下列指令。Cloud Shell 和編輯器非常方便，因為所有必要指令都已預先安裝，一切都可「開箱即用」。

git clone https://github.com/derailed-dash/gemini-file-search-demo
cd gemini-file-search-demo

這個樹狀結構會顯示存放區中的重要資料夾和檔案：

gemini-file-search-demo/
├── app/
│   ├── basic_agent_adk/        # Agent with Google Search, using ADK framework
│   │   └── agent.py
│   ├── rag_agent_adk/          # Agent with Google Search and File Search, using ADK framework
│   │   ├── agent.py            
│   │   └── tools_custom.py      
│   ├── sdk_agent.py            # Agent using GenAI SDK (no ADK) with Google Search tool
│   └── sdk_rag_agent.py        # Agent using GenAI SDK (no ADK) with Gemini File Search tool
├── data/
│   └── story.md                # Sample story with "bespoke content" to use with Gemini File Search Store
├── notebooks/
│   └── file_search_store.ipynb # Jupyter notebook for creating and managing Gemini File Search Store
│
├── .env.template               # Template for environment variables - make a copy as .env
├── Makefile                    # Makefile for `make` commands
├── pyproject.toml              # Project configuration and dependencies
└── README.md                   # This file

在 Cloud Shell 編輯器或偏好的編輯器中開啟這個資料夾。(你用過 Antigravity 嗎？如果沒有，現在是試用的好時機。)

請注意，存放區的 data/story.md 檔案中包含範例故事「The Wormhole Incursion」。這篇文章是與 Gemini 共同創作的！故事主角是達茲波指揮官，以及他率領的智慧星艦中隊。(我從《Elite Dangerous》這款遊戲獲得一些靈感。)這個故事是我們的「專屬知識庫」，包含 Gemini 不知道的特定事實，而且 Gemini 無法使用 Google 搜尋尋找這些事實。

設定開發環境

為方便起見，我提供了一個 Makefile，可簡化許多需要執行的指令。不必記住特定指令，只要執行類似 make <target> 的指令即可。不過，make 僅適用於 Linux / MacOS / WSL 環境。如果您使用 Windows (不含 WSL)，則需要執行 make 目標包含的完整指令。

# Install dependencies with make
make install

# If you don't have make...
uv sync --extra jupyter

在 Cloud Shell 編輯器中執行 make install 時，畫面會顯示以下內容：

64ed9878be59adad.png

建立 Gemini API 金鑰

如要使用 Gemini Developer API (使用 Gemini 檔案搜尋工具時需要這個 API)，請先取得 Gemini API 金鑰。取得 API 金鑰最簡單的方法是使用 Google AI Studio，這個工具提供便利的介面，可為 Google Cloud 專案取得 API 金鑰。如需具體步驟，請參閱這份指南。

建立 API 金鑰後，請複製並妥善保管。

現在需要將這個 API 金鑰設為環境變數。我們可以使用 .env 檔案完成這項操作。將隨附的 .env.example 複製到名為 .env 的新檔案。檔案應會如下所示：

export GEMINI_API_KEY="your-api-key"
export MODEL="gemini-2.5-flash"
export STORE_NAME="demo-file-store"

請將 your-api-key 替換成實際的 API 金鑰。現在畫面應如下所示：

70fba02ac80c3790.png

現在請確認環境變數已載入。方法是執行下列指令：

source .env

4. 基本代理程式

首先，我們來建立基準。我們將使用原始 google-genai SDK 執行簡單的代理程式。

程式碼

請看一下 app/sdk_agent.py。這是最簡單的實作方式，可：

  • 將 genai.Client 執行個體化。
  • 啟用 google_search 工具。
  • 就是這麼簡單！沒有 RAG。

請詳閱程式碼，確保瞭解其用途。

執行

# With make
make sdk-agent

# Without make
uv run python app/sdk_agent.py

我們來問一個一般問題：

> What is the stock price of Google?

並使用 Google 搜尋尋找目前價格，正確回答問題：

c1b9b6c7b37290ee.png

現在，讓我們問一個它不知道如何回答的問題。代理人必須先看過我們的故事。

> Who pilots the 'Too Many Pies' ship?

這時模型應該會失敗，甚至產生幻覺。請看以下範例：

945003150f7099cd.png

結果模型果然無法回答問題。完全不知道我們在說什麼！

現在輸入 quit 即可退出代理程式。

5. Gemini 檔案搜尋：說明

a1af82c360b915e9.png

Gemini 檔案搜尋功能基本上結合了兩項功能：

  1. 全代管 RAG 系統：您提供大量檔案，Gemini 檔案搜尋會為您處理分塊、嵌入、儲存和向量索引。
  2. 代理意義上的「工具」：您只要在代理定義中新增 Gemini 檔案搜尋工具，並將工具指向檔案搜尋商店即可。

但最重要的是：這項功能內建於 Gemini API 本身。也就是說，您不需要啟用任何其他 API 或部署任何獨立產品，就能使用這項功能。因此，這項功能out-of-the-box。

Gemini 檔案搜尋功能

其功能包括：

  • 系統會為您 (開發人員) 抽象化分塊、嵌入、儲存和建立索引的詳細資料。也就是說，您不需要瞭解 (或在意) 嵌入模型 (順帶一提，這是 Gemini Embeddings)，也不必知道產生的向量儲存在何處。您不必決定使用哪種向量資料庫。
  • 這項服務支援大量的文件類型，包括但不限於：PDF、DOCX、Excel、SQL、JSON、Jupyter 筆記本、HTML、Markdown、CSV，甚至是 ZIP 檔案。如需完整清單，請參閱這裡。舉例來說，如果想讓代理程式以含有文字、圖片和表格的 PDF 檔案為基礎，就不必預先處理這些 PDF 檔案。只要上傳原始 PDF，剩下的就交給 Gemini 處理。
  • 我們可以為任何上傳的檔案新增自訂中繼資料。這項功能在執行階段篩選工具要使用的檔案時，非常實用。

資料儲存位置

上傳部分檔案。Gemini 檔案搜尋工具已取得這些檔案、建立區塊和嵌入內容，並將這些內容放在某處。但要怎麼做？

答案：檔案搜尋商店。這是全代管的嵌入內容容器，您不需要瞭解 (或在意) 幕後如何完成這項作業。您只需要以程式輔助方式建立一個，然後將檔案上傳至其中即可。

價格實惠！

儲存及查詢嵌入內容皆不需付費。因此您可以無限期儲存嵌入內容，而且不必支付儲存費用！

事實上，您唯一需要支付的費用，是在上傳/建立索引時建立的嵌入。撰寫本文時，每 100 萬個權杖的費用為 $0.15 美元。這很便宜。

6. 如何使用 Gemini 檔案搜尋功能？

這項程序分為兩個階段：

  1. 在檔案搜尋儲存庫中建立及儲存嵌入項目。
  2. 從代理查詢檔案搜尋商店。

第 1 階段 - 使用 Jupyter Notebook 建立及管理 Gemini 檔案搜尋商店

這個階段是初始階段，之後每當你想更新商店時，也需要進行這個階段。舉例來說，當您有新文件要新增，或是來源文件有變更時。

您不需要將這個階段封裝到部署的代理程式應用程式。當然可以，舉例來說，如果您想為代理程式應用程式的管理員使用者建立某種 UI，但通常只要有可隨選執行的程式碼片段就已足夠。而隨選執行這段程式碼的絕佳方式之一，Jupyter 筆記本！

手札情緣

在編輯器中開啟 notebooks/file_search_store.ipynb 檔案。如果系統提示您安裝任何 Jupyter VS Code 擴充功能，請繼續安裝。

在 Cloud Shell 編輯器中開啟時，檔案內容如下：

b87aed3c36a44e81.png

讓我們逐一執行儲存格。請先執行 Setup 儲存格，匯入所需項目。如果先前未執行過筆記本，系統會要求您安裝必要擴充功能。請繼續這麼做。接著，系統會要求你選取核心。選取「Python environments...」，然後選取我們在稍早執行 make install 時安裝的本機 .venv：

1101585f7bd5040f.png

然後：

  • 執行「Local Only」(僅限本機) 儲存格，以提取環境變數。
  • 執行「Client Initialisation」(用戶端初始化) 儲存格，初始化 Gemini Gen AI 用戶端。
  • 使用輔助函式依名稱擷取 Gemini 檔案搜尋商店，然後執行「Retrieve the Store」(擷取商店) 儲存格。

現在可以開始建立商店。

  • 執行「Create the Store (One Time)」儲存格，建立商店。這項操作只需要執行一次。如果程式碼執行成功，您應該會看到 "Created store: fileSearchStores/<someid>" 訊息
  • 執行「View the Store」(查看商店) 儲存格，查看商店內容。此時，您應該會看到該集合包含 0 份文件。

太好了！現在我們已準備好 Gemini 檔案搜尋商店。

上傳資料

我們想將 data/story.md 上傳至商店。請完成下列步驟：

  • 執行設定上傳路徑的儲存格。這會指向我們的 data/ 資料夾。
  • 執行下一個儲存格，為將檔案上傳至商店建立公用程式函式。請注意，這個儲存格中的程式碼也會使用 Gemini，從每個上傳的檔案擷取中繼資料。我們會擷取這些值，並以自訂中繼資料的形式儲存在商店中。(您不必這麼做，但這項操作很有用)。
  • 執行儲存格來上傳檔案。請注意，如果我們先前已上傳同名檔案，筆記本會先刪除現有版本，再上傳新版本。畫面上應會顯示檔案已上傳的訊息。

4aeb3d5c91a66358.png

第 2 階段 - 在我們的代理程式中實作 Gemini 檔案搜尋 RAG

我們已建立 Gemini 檔案搜尋商店，並將故事上傳至該商店。現在，我們要在代理程式中使用檔案搜尋商店。現在來建立新的代理程式，使用檔案搜尋儲存庫而非 Google 搜尋。請參閱app/sdk_rag_agent.py。

首先，請注意我們已實作函式，可透過傳入商店名稱來擷取商店：

def get_store(client: genai.Client, store_name: str) -> types.FileSearchStore | None:
    """Retrieve a store by display name"""
    try:
        for a_store in client.file_search_stores.list():
            if a_store.display_name == store_name:
                return a_store
    except Exception as e:
        logger.error(f"Error listing stores: {e}")
    return None

有了商店後，只要將其附加為代理程式的工具即可使用，如下所示：

   file_search_tool = types.Tool(file_search=types.FileSearch(file_search_store_names=[store.name]))

執行 RAG 代理程式

啟動方式如下：

make sdk-rag-agent

# Or, without make:
uv run python app/sdk_rag_agent.py

讓我們詢問先前服務專員無法回答的問題：

> Who pilots the 'Too Many Pies' ship?

結果如何？

15659914bcdee9c7.png

成功！從回覆中，我們可以得知：

  • 我們使用檔案儲存空間來回答問題。
  • 找到 5 個相關區塊。
  • 答案完全正確！

輸入 quit 即可關閉代理程式。

7. 將代理程式轉換為使用 ADK

Google Agent Development Kit (ADK) 是開放原始碼的模組化架構和 SDK，可供開發人員建構代理和代理系統。讓我們輕鬆建立及自動調度管理多代理系統。雖然 ADK 已針對 Gemini 和 Google 生態系統最佳化，但與模型和部署方式無關，且可與其他架構相容。如果您尚未用過 ADK，請前往 ADK 文件瞭解詳情。

請看一下 app/basic_agent_adk/agent.py。在這個程式碼範例中，您可以看到我們實際實作了兩個代理程式：

  1. root_agent，可處理與使用者的互動，並提供主要系統指令。
  2. 使用 google.adk.tools.google_search 做為工具的獨立 SearchAgent。

root_agent 實際上會使用 SearchAgent 做為工具，而這項工具是透過下列程式碼行實作：

   tools=[AgentTool(agent=search_agent)],

根層級代理程式的系統提示如下所示：

You are a helpful AI assistant designed to provide accurate and useful information.
If you don't know the answer, use the SearchAgent to perform a Google search.
Do not attempt to search more than ONCE.
If the search yields no relevant results or returns unrelated content, you MUST immediately respond with: "I could not find any information about that."
Do NOT retry the search with different terms. Do NOT ask for clarification. FAIL FAST.

試用代理

ADK 提供多種現成介面，方便開發人員測試 ADK 代理。其中一個介面是網頁 UI。這樣我們就能在瀏覽器中測試代理程式，完全不必撰寫任何使用者介面程式碼！

我們可以執行下列指令來啟動這個介面：

make adk-playground

# Or, without make:
uv run adk web app --port 8501 --reload_agents

請注意，這項指令會將 adk web 工具指向 app 資料夾，並自動探索實作 root_agent 的任何 ADK 代理程式。讓我們試試看：

89218e7915011dd3.png

幾秒後，應用程式就會準備就緒。如果您在本機執行程式碼，只要將瀏覽器指向 http://127.0.0.1:8501 即可。如果您在 Cloud Shell 編輯器中執行，請按一下「Web preview」，然後將通訊埠變更為 8501：

1b416cc40d67d794.png

使用者介面隨即顯示，請從下拉式選單中選取 basic_agent_adk，然後即可提問：

a2acc9901de49e20.gif

到目前為止都很順利！網頁 UI 甚至會顯示根代理程式何時委派給 SearchAgent。這項功能非常實用。

現在，請提出需要瞭解故事內容的問題：

5a9f9ec06a29160.png

歡迎親自試試。您應該會發現，系統會按照指示快速失敗。

將檔案搜尋商店併入 ADK 代理

現在我們將所有內容整合在一起。我們將執行 ADK 代理程式，該程式可同時使用檔案搜尋商店和 Google 搜尋。查看 app/rag_agent_adk/agent.py 中的程式碼。

這段程式碼與上一個範例類似，但有幾項主要差異：

  1. 我們有一個根代理，可協調兩個專用代理：
  2. RagAgent：專屬知識專家 - 使用我們的 Gemini 檔案搜尋商店
  3. SearchAgent：一般知識專家 - 使用 Google 搜尋
  4. 由於 ADK 尚未提供 FileSearch 的內建包裝函式，我們使用自訂包裝函式類別 FileSearchTool 包裝 FileSearch 工具，將 file_search_store_names 設定注入低階模型要求。這項功能已實作到個別指令碼 app/rag_agent_adk/tools_custom.py 中。

此外，還有一個「陷阱」需要注意。撰寫本文時，您無法在同一個要求中，對同一個代理程式同時使用原生 GoogleSearch 工具和 FileSearch 工具。如果嘗試這麼做，就會收到類似以下的錯誤訊息：

錯誤 - 發生錯誤：400 INVALID_ARGUMENT。{‘error': {‘code': 400, ‘message': ‘Search as a tool and file search tool are not supported together', ‘status': ‘INVALID_ARGUMENT'}}

錯誤：400 INVALID_ARGUMENT。{‘error': {‘code': 400, ‘message': ‘Search as a tool and file search tool are not supported together', ‘status': ‘INVALID_ARGUMENT'}}

解決方法是將這兩位專家代理程式實作為個別的子代理程式，並使用「代理程式即工具」模式將其傳遞至根代理程式。最重要的是，根代理程式的系統指令會提供非常明確的指引，要求先使用 RagAgent：

我是實用的 AI 助理，可提供準確實用的資訊。

你可以諮詢兩位專員：

  1. RagAgent：從內部知識庫取得專屬資訊。
  2. SearchAgent：提供 Google 搜尋的一般資訊。

請務必先嘗試使用 RagAgent。如果無法獲得實用答案，請嘗試使用 SearchAgent。

最終測試

如常執行 ADK 網頁版 UI：

make adk-playground

# Or, without make:
uv run adk web app --port 8501 --reload_agents

這次請在 UI 中選取 rag_agent_adk。實際運作情況：c4d2cdaa3257e115.gif

從畫面中可以看到，系統會根據問題選擇適當的子代理。

8. 結語

恭喜您完成本程式碼研究室！

您已從簡單的指令碼，變成支援 RAG 的多代理程式系統，完全不需要任何嵌入程式碼，也不必實作向量資料庫！

我們學到下列事項：

  • Gemini 檔案搜尋是代管式 RAG 解決方案，可節省時間並保持理智。
  • ADK 提供複雜多代理程式應用程式所需的結構，並透過 Web UI 等介面，為開發人員帶來便利。
  • "Agent-as-a-Tool"模式可解決工具相容性問題。

希望這個實驗室對您有幫助。下次見！