自 2026 年 4 月起，Gemini 2.0 Flash 出现间歇性错误：google_search 接地返回空结果或完全拒绝触发。 2026 年 3 月的图像接地回归使情况变得更糟。 Flash 无法可靠地调用搜索，尤其是当外部工具也已注册时。本教程构建了一个检测和回退层，以便您的代理始终获得搜索结果。
前置条件
- Google AI Studio 或 Vertex AI 凭据
- Scavio API 密钥
- Python 3.8+
操作指南
步骤 1: 通过 google_search 接地呼叫 Gemini
设置启用接地的标准 Gemini 呼叫。
Python
import google.generativeai as genai
import os
genai.configure(api_key=os.environ['GEMINI_API_KEY'])
model = genai.GenerativeModel('gemini-2.0-flash',
tools=[genai.Tool(google_search=genai.GoogleSearch())])
def gemini_search(query):
response = model.generate_content(query)
return response步骤 2: 检测空的或失败的搜索结果
检查双子座是否确实执行了搜索接地呼叫。 2026 年 4 月的错误返回的候选人没有基础元数据。
Python
def search_failed(response):
# No grounding metadata = search did not trigger
if not hasattr(response, 'candidates') or not response.candidates:
return True
candidate = response.candidates[0]
grounding = getattr(candidate, 'grounding_metadata', None)
if not grounding or not grounding.grounding_chunks:
return True
# Empty chunks = search triggered but returned nothing
return len(grounding.grounding_chunks) == 0步骤 3: 失败时路由至 Scavio
当 Gemini 搜索失败时，提取查询并调用 Scavio。
Python
import requests
H = {'x-api-key': os.environ['SCAVIO_API_KEY']}
def search_with_fallback(query):
response = gemini_search(query)
if search_failed(response):
results = requests.post('https://api.scavio.dev/api/v1/search',
headers=H,
json={'platform': 'google', 'query': query}).json()
return {'source': 'scavio', 'results': results}
return {'source': 'gemini', 'response': response}步骤 4: 用于监控的日志失败率
跟踪 Gemini 搜索失败的频率，以便您知道 Google 何时修复该错误。
Python
import json, datetime
def log_search_event(query, source, failed):
with open('search_fallback_log.jsonl', 'a') as f:
f.write(json.dumps({
'ts': datetime.datetime.now().isoformat(),
'query': query, 'source': source, 'gemini_failed': failed
}) + '\n')Python 示例
Python
import os, requests
import google.generativeai as genai
genai.configure(api_key=os.environ['GEMINI_API_KEY'])
model = genai.GenerativeModel('gemini-2.0-flash',
tools=[genai.Tool(google_search=genai.GoogleSearch())])
H = {'x-api-key': os.environ['SCAVIO_API_KEY']}
def search(query):
resp = model.generate_content(query)
grounding = getattr(resp.candidates[0], 'grounding_metadata', None) if resp.candidates else None
if not grounding or not grounding.grounding_chunks:
return requests.post('https://api.scavio.dev/api/v1/search',
headers=H, json={'platform': 'google', 'query': query}).json()
return respJavaScript 示例
JavaScript
const res = await fetch('https://api.scavio.dev/api/v1/search', {
method: 'POST',
headers: {'x-api-key': process.env.SCAVIO_API_KEY, 'Content-Type': 'application/json'},
body: JSON.stringify({platform: 'google', query: userQuery})
});
const fallbackResults = await res.json();预期输出
JSON
Agent that always returns search results: Gemini grounding when it works, Scavio API when Gemini fails. JSONL log of failure rates for monitoring.