Gemini 联网搜索 API

用灵眸 Gemini 原生 v1beta 接口开启 Google Search 联网搜索(Grounding),获取基于实时网页的回答,以及搜索词、引用来源和逐句引用关系。

在 Gemini 原生 generateContent 请求里加入 google_search 工具,模型就会按需联网搜索,并基于搜索结果作答。响应会额外返回搜索词、引用来源和每句话对应的来源,适合需要实时信息或需要展示出处的场景。

请求必须落到「Gemini-官方Vertex」分组

联网搜索要由上游执行,只有 Gemini-官方Vertex 分组会执行。其他 Gemini 分组的上游可能不执行搜索:请求照常返回 200,但响应里没有 groundingMetadata,回答也不是基于实时搜索结果。

  • 分组密钥(推荐):在控制台「API 密钥」新建一把密钥,分组选「Gemini-官方Vertex」,专门用于联网搜索。
  • 通用密钥:默认不会落到这个分组。需要在「API 密钥」列表点这把通用密钥的徽标,进入「扣费方式」,把「Gemini 系列」的按量档位改成「Gemini-官方Vertex」。改完后,这把密钥的所有 Gemini 调用都会走该分组、按该分组倍率计费。

国内站看不到这个分组?

国内站的分组列表不展示「Gemini-官方Vertex」,请在国际站创建该分组的 API Key。


1. 接口总览

项值
Base URLhttps://api.lmuai.com
非流式POST /v1beta/models/{model}:generateContent
流式POST /v1beta/models/{model}:streamGenerateContent?alt=sse
鉴权x-goog-api-key: <你的 sk- API Key>
开启搜索请求体加 "tools": [{"google_search": {}}]
引用来源响应 candidates[0].groundingMetadata

2. 快速开始

curl -X POST \
  'https://api.lmuai.com/v1beta/models/gemini-3.5-flash-lite:generateContent' \
  -H 'x-goog-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [{"text": "api.lmuai.com 是什么网站?请给出来源。"}]
    }],
    "tools": [{"google_search": {}}],
    "generationConfig": {"maxOutputTokens": 2048}
  }'

响应示例(已省略部分字段):

{
  "candidates": [{
    "content": {
      "role": "model",
      "parts": [{"text": "api.lmuai.com 是灵眸 AI 的大模型 API 接入平台……"}]
    },
    "finishReason": "STOP",
    "groundingMetadata": {
      "webSearchQueries": ["api lmuai com", "lmuai com"],
      "groundingChunks": [
        {"web": {"uri": "https://vertexaisearch.cloud.google.com/grounding-api-redirect/...", "title": "lmuai.com", "domain": "lmuai.com"}},
        {"web": {"uri": "https://vertexaisearch.cloud.google.com/grounding-api-redirect/...", "title": "lmuai.ai", "domain": "lmuai.ai"}}
      ],
      "groundingSupports": [{
        "segment": {"endIndex": 42, "text": "api.lmuai.com 是灵眸 AI 的大模型 API 接入平台"},
        "groundingChunkIndices": [0, 1]
      }],
      "searchEntryPoint": {"renderedContent": "<style>...</style><div>...</div>"}
    }
  }],
  "usageMetadata": {"promptTokenCount": 43, "candidatesTokenCount": 288}
}

3. 请求参数

在普通 Gemini 请求的基础上,只需要加 tools:

字段必填说明
contents是对话内容,写法与普通 Gemini 请求相同
tools是固定写 [{"google_search": {}}]。模型会自己决定是否搜索、搜几次
generationConfig.maxOutputTokens建议建议不少于 2048。带思考的模型(如 gemini-4-hydrogen)需要更大,否则可能因 MAX_TOKENS 截断,正文和来源都拿不到

一次请求可能搜索多次

模型会根据问题拆出多个搜索词。实际执行了哪些搜索,以响应里的 webSearchQueries 为准。


4. 响应字段:groundingMetadata

字段说明
webSearchQueries本次实际执行的搜索词列表
groundingChunks[].web.uri来源链接。是 Google 的跳转链接(vertexaisearch.cloud.google.com/...),打开后跳到原网页
groundingChunks[].web.title来源标题,通常就是网站域名
groundingChunks[].web.domain来源网站的域名,如 lmuai.com
groundingSupports[].segment回答中的一段文字:text 为内容,startIndex / endIndex 为位置(从开头算起时 startIndex 会省略)
groundingSupports[].groundingChunkIndices这段文字引用了哪些来源,值是 groundingChunks 的下标
searchEntryPoint.renderedContentGoogle 搜索建议的 HTML 片段

展示给终端用户时

如果你把联网搜索的回答展示给终端用户,Google 要求同时展示 searchEntryPoint.renderedContent 中的搜索建议。详见 Google 官方说明。


5. Python 示例:读取来源和逐句引用

import requests

API_KEY = "YOUR_API_KEY"
url = "https://api.lmuai.com/v1beta/models/gemini-3.5-flash-lite:generateContent"

resp = requests.post(
    url,
    headers={"x-goog-api-key": API_KEY},
    json={
        "contents": [{"role": "user", "parts": [{"text": "国内有哪些大模型 API 平台?请给出来源。"}]}],
        "tools": [{"google_search": {}}],
        "generationConfig": {"maxOutputTokens": 2048},
    },
    timeout=180,
)
resp.raise_for_status()
cand = resp.json()["candidates"][0]

answer = "".join(p.get("text", "") for p in cand["content"]["parts"])
meta = cand.get("groundingMetadata", {})
chunks = meta.get("groundingChunks", [])

print("回答:", answer)
print("搜索词:", meta.get("webSearchQueries", []))

for i, c in enumerate(chunks):
    print(f"[{i}] {c['web'].get('domain')}  {c['web'].get('uri')}")

for s in meta.get("groundingSupports", []):
    refs = [chunks[i]["web"].get("domain") for i in s.get("groundingChunkIndices", [])]
    print(s["segment"].get("text"), "->", refs)

if not meta:
    print("本次没有联网:模型判断无需搜索,或当前分组不支持联网搜索。")

6. 流式调用

把端点换成 streamGenerateContent?alt=sse,请求体不变:

curl -N -X POST \
  'https://api.lmuai.com/v1beta/models/gemini-3.5-flash-lite:streamGenerateContent?alt=sse' \
  -H 'x-goog-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "contents": [{"role": "user", "parts": [{"text": "今天有哪些 AI 行业新闻?"}]}],
    "tools": [{"google_search": {}}],
    "generationConfig": {"maxOutputTokens": 2048}
  }'

每个 data: 事件带一段文本。groundingMetadata 只出现在最后一个事件里:先拼接所有事件的文本,再从最后一个事件读取来源。


7. 支持的模型

以下模型已实测可联网:

模型特点
gemini-3.5-flash-lite速度最快、价格最低,适合批量调用
gemini-3.8-flash引用来源通常更多,适合对出处要求高的场景
gemini-3.6-flash / gemini-3.7-flash与 3.8 Flash 接近
gemini-3-flash-preview可用
gemini-4-hydrogen搜索次数多、耗时长,maxOutputTokens 需要设大

当前分组实际可用的模型,以控制台「可用模型」页面为准。


8. 用 OpenAI 或 Anthropic 协议调用

Gemini 模型也可以用 OpenAI 或 Anthropic 协议 调用,并通过各协议的搜索工具触发联网:

协议搜索工具写法能否联网结构化引用来源
Gemini 原生{"google_search": {}}✅✅ groundingMetadata
OpenAI Chat Completions{"type": "web_search"}✅❌ 链接只在正文中
OpenAI Responses{"type": "web_search"}✅❌ 链接只在正文中
Anthropic Messages{"type": "web_search_20250305", "name": "web_search"}✅❌ 链接只在正文中

需要来源列表或逐句引用时,请使用 Gemini 原生协议。

名字叫 google_search 的普通 function 工具("type": "function")不会触发联网,它仍然是一个由你的程序执行的函数。


9. 费用

联网搜索请求按所用模型计费,每次请求的费用可在控制台「使用记录」中查看。一次请求可能执行多次搜索,输出也会比普通请求长。


10. 排错速查

现象原因处理
200 但没有 groundingMetadata模型判断无需搜索,或分组上游不执行搜索换用「Gemini-官方Vertex」分组的 Key;在提问里明确要求联网或给出来源
用通用密钥,始终没有 groundingMetadata通用密钥的 Gemini 系列还在默认档位,没有落到「Gemini-官方Vertex」按本页开头的说明改「扣费方式」,或新建一把分组密钥
finishReason 为 MAX_TOKENS,正文为空思考占满了输出额度调大 maxOutputTokens
404 Not Found路径写错,或模型不在当前分组检查是否为 /v1beta/models/{model}:generateContent,并在「可用模型」页确认模型名
401 UnauthorizedKey 写错或未放在 x-goog-api-key 请求头检查请求头

更多协议说明见 接入协议,常见错误见 错误码说明。

最后更新:

京ICP备2020034311号-7

本页目录