北京通州网站建设,网站备案是域名备案还是主机备案,asp网站js悬浮窗怎么做,乌海做网站的公司在开发大语言模型应用、RAG 系统或者 Agent 时，经常需要让程序获取互联网中的最新信息。
一种直接的方法是自己编写爬虫抓取搜索引擎页面，但这种方式需要处理页面结构变化、反爬虫、验证码、代理和结果解析等问题。
…
在开发大语言模型应用、RAG 系统或者 Agent 时，经常需要让程序获取互联网中的最新信息。
一种直接的方法是自己编写爬虫抓取搜索引擎页面，但这种方式需要处理页面结构变化、反爬虫、验证码、代理和结果解析等问题。
SerpApi 将这些过程封装成了搜索 API。开发者只需要传入搜索关键词和相关参数，就可以获得结构化的搜索结果。
本文介绍 SerpApi 的基本概念、安装与配置方法，并实现一个简单的 Google 网页搜索工具。一、SerpApi 是什么
SERP 是 Search Engine Results Page 的缩写，即“搜索引擎结果页面”。
SerpApi 是一个第三方搜索结果 API 服务。它可以调用 Google、Bing、百度、Google Scholar、Google News、Google Maps、YouTube 等搜索服务，并将搜索页面解析为结构化 JSON 数据。
例如，在 Google 中搜索：
什么是人工智能 Agent普通用户看到的是一个网页，而程序通过 SerpApi 可以获得类似下面的结构化结果：
{"answer_box": {"snippet": "AI Agent 是一种能够自主完成任务的人工智能系统……"},"knowledge_graph": {"title": "AI Agent","description": "……"},"organic_results": [{"position": 1,"title": "网页标题","link": "网页地址","snippet": "网页摘要"}]
}程序可以直接读取：
results.get("answer_box")
results.get("knowledge_graph")
results.get("organic_results")不需要再对 HTML 网页进行手动解析。
SerpApi 比较适合以下场景：为 AI Agent 添加网页搜索工具；
为 RAG 系统补充互联网信息；
获取新闻、图片、论文和普通网页结果；
进行搜索结果分析；
获取特定地区、语言或设备下的搜索结果；
进行 SEO、竞品分析和信息监控。需要注意，SerpApi 是第三方服务，不是 Google 官方提供的 Python SDK。调用 SerpApi 需要注册账号并获取 API Key，同时搜索请求会消耗账户额度。二、安装 SerpApi
1. 安装新版 Python 包
执行：
python -m pip install -U serpapi本文还会使用 .env 文件管理 API Key，因此同时安装 python-dotenv：
python -m pip install -U serpapi python-dotenv也可以一次安装：
python -m pip install -U serpapi python-dotenv2. 新旧版本接口区别
网上很多较早的教程使用：
from serpapi import SerpApiClient或者：
from serpapi import GoogleSearch这些通常对应旧版 google-search-results 包。
新版官方包的安装名称是：
pip install serpapi新版推荐写法是：
import serpapiclient = serpapi.Client(api_key="你的API_KEY"
)因此，如果出现下面的错误：
ImportError: cannot import name 'SerpApiClient' from 'serpapi'通常说明当前安装的是新版 serpapi，但代码使用了旧版接口。
本文统一使用新版写法：
import serpapi以及：
serpapi.Client(...)三、配置 SerpApi
1. 获取 API Key
注册 SerpApi 账号后，可以在账户页面获取自己的 API Key。
API Key 属于敏感信息，不建议直接写入 Python 源码，例如不要这样写：
api_key = "xxxxxxxxxxxxxxxx"更推荐将 API Key 保存到 .env 文件中。
2. 创建 .env 文件
在项目根目录创建 .env 文件：
SERPAPI_API_KEY=你的SerpApi密钥例如项目结构为：
hello-agents/
├── .env
├── .gitignore
└── search.py3. 配置 .gitignore
为了避免将 API Key 上传到 GitHub，在 .gitignore 文件中加入：
.env
__pycache__/
*.pyc4. 在 Python 中读取 API Key
首先加载 .env：
from dotenv import load_dotenvload_dotenv()然后通过 os.getenv() 读取环境变量：
import osapi_key = os.getenv("SERPAPI_API_KEY")如果 .env 文件中配置了：
SERPAPI_API_KEY=abc123那么：
api_key = os.getenv("SERPAPI_API_KEY")读取到的就是字符串：
abc123四、完整例程
下面实现一个简单的网页搜索函数。
程序会按照以下顺序解析搜索结果：优先返回 answer_box 中的直接答案；
如果没有直接答案，则返回 knowledge_graph 中的知识图谱描述；
如果仍然没有，则返回前三条 organic_results 普通网页结果。import osimport serpapi
from dotenv import load_dotenv# 加载项目根目录下 .env 文件中的环境变量
load_dotenv()def search(query: str) - str:"""使用 SerpApi 调用 Google 搜索。结果解析顺序：1. Answer Box 直接答案；2. Knowledge Graph 知识图谱；3. 前三条普通网页搜索结果。"""print(f"🔍 正在执行 [SerpApi] 网页搜索：{query}")# 从环境变量中读取 SerpApi API Keyapi_key = os.getenv("SERPAPI_API_KEY")# 如果没有读取到 API Key，则直接返回错误信息if not api_key:return "错误：SERPAPI_API_KEY 未在 .env 文件中配置。"try:# 创建新版 SerpApi 客户端client = serpapi.Client(api_key=api_key,timeout=20,)# 设置 Google 搜索参数params = {"engine": "google","q": query,"gl": "cn","hl": "zh-cn",}# 发起搜索请求results = client.search(params)# ==================================================# 1. 优先读取 Answer Box# ==================================================answer_box = results.get("answer_box", {})if answer_box:# 不同类型的直接答案可能存放在不同字段中for field in ("answer","result","snippet","definition",):value = answer_box.get(field)if value:return str(value)# 某些直接答案会以列表形式返回answer_list = answer_box.get("list")if isinstance(answer_list, list):return "\n".join(str(item)for item in answer_list)# ==================================================# 2. 读取 Knowledge Graph# ==================================================knowledge_graph = results.get("knowledge_graph",{},)if knowledge_graph:title = knowledge_graph.get("title", "")description = knowledge_graph.get("description","",)if description:if title:return f"{title}\n{description}"return description# ==================================================# 3. 读取普通网页搜索结果# ==================================================organic_results = results.get("organic_results",[],)if organic_results:snippets = []# 最多返回前三条普通网页结果for index, result in enumerate(organic_results[:3],start=1,):title = result.get("title","无标题",)snippet = result.get("snippet","无摘要",)link = result.get("link","",)text = (f"[{index}] {title}\n"f"{snippet}")if link:text += f"\n链接：{link}"snippets.append(text)return "\n\n".join(snippets)# 请求成功，但没有找到可用结果return f"对不起，没有找到关于“{query}”的信息。"except serpapi.TimeoutError:return "搜索时发生错误：SerpApi 请求超时。"except serpapi.HTTPError as error:return f"搜索时发生 HTTP 错误：{error}"except Exception as error:return f"搜索时发生错误：{error}"if __name__ == "__main__":result = search("什么是人工智能 Agent")print("\n搜索结果：")print(result)五、分块详解
1. 加载 .env 文件
load_dotenv()load_dotenv() 会查找项目中的 .env 文件，并将其中的配置加载到当前 Python 进程的环境变量中。
之后便可以使用：
os.getenv("SERPAPI_API_KEY")获取 API Key。
如果环境变量不存在，os.getenv() 默认返回 None：
api_key = os.getenv("SERPAPI_API_KEY")if not api_key:return "错误：SERPAPI_API_KEY 未在 .env 文件中配置。"这里的 not api_key 可以同时判断：api_key 是 None；
api_key 是空字符串；
API Key 没有正确配置。2. 创建 SerpApi 客户端
client = serpapi.Client(api_key=api_key,timeout=20,
)这里使用的是新版 serpapi 包中的 Client。
api_key
用于验证 SerpApi 账户身份：
api_key=api_keytimeout
设置网络请求的超时时间：
timeout=20表示请求超过 20 秒仍未完成时，抛出超时异常。
客户端创建完成后，可以多次调用：
client.search(...)因此，在包含大量搜索操作的项目中，也可以将 client 创建为一个长期复用的对象，而不是每次搜索都重新创建。3. 设置搜索参数
例程中使用的参数为：
params = {"engine": "google","q": query,"gl": "cn","hl": "zh-cn",
}engine
指定搜索引擎：
"engine": "google"常见值包括：
"google"
"google_scholar"
"google_news"
"google_images"
"google_maps"
"bing"
"baidu"
"youtube"不同搜索引擎支持的参数和返回字段可能不同。
例如 Google Scholar：
params = {"engine": "google_scholar","q": "low-light image enhancement",
}百度：
params = {"engine": "baidu","q": "低照度图像增强",
}q
设置搜索关键词：
"q": query它可以是普通关键词：
"q": "人工智能 Agent"也可以使用 Google 搜索表达式：
"q": '"artificial intelligence agent"'限制网站：
"q": "image restoration site:openaccess.thecvf.com"限制标题：
"q": 'intitle:"low-light image enhancement"'排除关键词：
"q": "Python 教程 -广告"gl
设置 Google 搜索使用的国家或地区：
"gl": "cn"常见值包括：
cn：China
us：United States
uk：United Kingdom
jp：Japangl 会影响搜索结果的地区倾向和排序。
hl
设置 Google 搜索使用的语言：
"hl": "zh-cn"常见值包括：
zh-cn：简体中文
en：英文
ja：日文
fr：法文需要注意，hl 主要影响 Google 搜索界面和结果呈现语言，并不意味着结果网页一定全部使用该语言。4. 其他常用搜索参数
虽然完整例程中没有使用下面这些参数，但在实际项目中也比较常见。
location
指定搜索发起位置：
params = {"engine": "google","q": "附近的咖啡店","location": "Beijing, China","gl": "cn",
}它适合本地商家、招聘、地图、新闻和地区相关搜索。
通常建议将 location 设置到城市级别，并与对应的 gl 一起使用。
device
模拟不同设备执行搜索：
"device": "desktop"常见值：
desktop
tablet
mobile不同设备可能得到不同的搜索页面布局和结果排序。
start
设置搜索结果偏移量，主要用于分页：
"start": 0例如：
start=0：第一页
start=10：第二页
start=20：第三页分页搜索示例：
for start in range(0, 30, 10):results = client.search({"engine": "google","q": "人工智能 Agent","start": start,})每次调用 client.search() 都会产生一次新的搜索请求。
safe
控制成人内容过滤：
"safe": "active"常见值：
active：启用过滤
off：关闭过滤tbm
切换 Google 搜索类型：
"tbm": "nws"常见值包括：
isch：图片搜索
lcl：本地搜索
vid：视频搜索
nws：新闻搜索
shop：购物搜索
pts：专利搜索例如搜索新闻：
params = {"engine": "google","q": "人工智能 Agent","tbm": "nws",
}也可以直接使用独立引擎：
params = {"engine": "google_news","q": "人工智能 Agent",
}tbs
设置 Google 高级过滤条件，常用于时间过滤：
"tbs": "qdr:m"常见时间范围：
qdr:h：最近一小时
qdr:d：最近一天
qdr:w：最近一周
qdr:m：最近一个月
qdr:y：最近一年例如搜索最近一个月的 Agent 信息：
params = {"engine": "google","q": "AI Agent","tbs": "qdr:m",
}no_cache
强制获取新的搜索结果：
"no_cache": True默认情况下，SerpApi 可能返回完全相同请求的缓存结果。
需要尽量获取最新结果时，可以设置：
"no_cache": True不过这会重新执行搜索，并消耗搜索额度。
output
设置响应格式：
"output": "json"常见值：
json：返回结构化 JSON，默认值
html：返回原始 HTML通常使用默认的 JSON 即可。
HTML 主要用于调试，或者查看尚未被 SerpApi 解析成结构化字段的页面内容。
async
以异步方式提交搜索任务：
"async": True异步搜索会先提交任务并返回搜索 ID，之后需要通过 Search Archive API 获取最终结果。
普通 Agent 工具通常直接使用同步搜索即可，因此本文例程没有启用异步模式。5. 发起搜索请求
results = client.search(params)client.search() 会将参数发送给 SerpApi，并返回搜索结果。
新版 SDK 返回的是 SerpResults 对象。
它可以像普通 Python 字典一样使用：
results.get("answer_box", {})
results.get("knowledge_graph", {})
results.get("organic_results", [])也可以直接打印完整结果：
print(results)调试时还可以查看所有顶层字段：
print(results.keys())6. 为什么使用 get()
下面的写法直接通过键获取值：
answer_box = results["answer_box"]如果当前搜索结果中没有 answer_box，程序会抛出：
KeyError: 'answer_box'更安全的写法是：
answer_box = results.get("answer_box", {})如果字段存在，则返回对应值。
如果字段不存在，则返回指定的默认值 {}。
列表字段通常使用空列表作为默认值：
organic_results = results.get("organic_results",[],
)因为不同搜索请求返回的字段并不固定，所以解析 SerpApi 结果时通常应优先使用 .get()。7. 解析 answer_box
answer_box = results.get("answer_box", {})answer_box 表示 Google 搜索页面中的直接答案。
不同类型的搜索，直接答案可能存放在不同字段中，例如：
answer_box.get("answer")
answer_box.get("result")
answer_box.get("snippet")
answer_box.get("definition")
answer_box.get("list")因此代码按照顺序检查：
for field in ("answer","result","snippet","definition",
):value = answer_box.get(field)if value:return str(value)只要找到第一个有效字段，就直接返回结果。
例如，某次搜索可能返回：
{"answer_box": {"type": "organic_result","snippet": "AI Agent 是一种能够自主执行任务的系统……"}
}此时代码会读取：
answer_box.get("snippet")并返回对应文本。8. 解析 knowledge_graph
knowledge_graph = results.get("knowledge_graph",{},
)知识图谱通常用于描述某个明确实体，例如：人物；
公司；
学校；
城市；
技术；
产品；
组织。常见字段包括：
knowledge_graph.get("title")
knowledge_graph.get("description")
knowledge_graph.get("source")
knowledge_graph.get("website")
knowledge_graph.get("thumbnail")本文只读取：
title = knowledge_graph.get("title", "")
description = knowledge_graph.get("description","",
)然后将标题和描述拼接起来：
return f"{title}\n{description}"9. 解析 organic_results
organic_results = results.get("organic_results",[],
)organic_results 表示普通的自然搜索结果。
它通常是一个列表：
[{"position": 1,"title": "网页标题","link": "网页链接","snippet": "网页摘要"},{"position": 2,"title": "网页标题","link": "网页链接","snippet": "网页摘要"}
]例程只取前三条：
organic_results[:3]然后通过 enumerate() 同时获得结果编号和结果内容：
for index, result in enumerate(organic_results[:3],start=1,
):其中：
start=1表示编号从 1 开始，而不是从 0 开始。
单条普通搜索结果中比较常见的字段包括：
result.get("position")
result.get("title")
result.get("link")
result.get("displayed_link")
result.get("snippet")
result.get("date")
result.get("thumbnail")
result.get("sitelinks")这些字段同样不保证每次都存在。10. 其他常用返回字段
除了例程中的三个主要字段，SerpApi 还可能返回下面这些内容。
search_metadata
搜索任务的元信息：
metadata = results.get("search_metadata",{},
)常见内容包括：
metadata.get("id")
metadata.get("status")
metadata.get("created_at")
metadata.get("processed_at")
metadata.get("total_time_taken")其中：id：SerpApi 搜索任务 ID；
status：搜索任务状态；
total_time_taken：请求处理时间。search_parameters
记录当前搜索实际使用的参数：
search_parameters = results.get("search_parameters",{},
)调试时可以打印：
print(search_parameters)检查 engine、q、gl、hl、device 等参数是否生效。
search_information
记录搜索结果的基本信息：
search_information = results.get("search_information",{},
)可能包含：
search_information.get("query_displayed")
search_information.get("total_results")
search_information.get("page_number")
search_information.get("time_taken_displayed")related_questions
Google 搜索中的“其他用户还问了”：
related_questions = results.get("related_questions",[],
)单条内容可能包括：
question.get("question")
question.get("snippet")
question.get("title")
question.get("link")related_searches
Google 搜索页面底部的相关搜索词：
related_searches = results.get("related_searches",[],
)常见字段包括：
item.get("query")
item.get("link")serpapi_pagination
分页信息：
pagination = results.get("serpapi_pagination",{},
)可以从中获取下一页搜索地址或其他页码信息。
其他可能出现的字段
根据查询内容和搜索类型，还可能出现：
results.get("images_results")
results.get("news_results")
results.get("top_stories")
results.get("local_results")
results.get("shopping_results")
results.get("video_results")
results.get("recipes_results")
results.get("events_results")
results.get("ai_overview")这些字段并不是每次搜索都会返回。
SerpApi 返回哪些字段，取决于 Google 当前搜索页面中实际出现了哪些模块。
因此，不能假设某个字段一定存在。11. 异常处理
SerpApi 请求可能因为网络、API Key、账户额度或请求参数等原因失败。
请求超时
except serpapi.TimeoutError:return "搜索时发生错误：SerpApi 请求超时。"当请求超过客户端设置的 timeout 时，会进入这个分支。
HTTP 错误
except serpapi.HTTPError as error:return f"搜索时发生 HTTP 错误：{error}"常见 HTTP 错误包括：
400：请求参数错误或缺少必要参数
401：API Key 无效
429：请求频率超过限制或账户额度不足如果需要进一步区分，可以读取状态码：
except serpapi.HTTPError as error:if error.status_code == 401:return "错误：SerpApi API Key 无效。"if error.status_code == 429:return "错误：请求过于频繁或搜索额度不足。"return f"SerpApi HTTP 错误：{error}"其他异常
except Exception as error:return f"搜索时发生错误：{error}"用于捕获未预料到的其他错误，避免搜索工具导致整个 Agent 程序直接退出。12. if __name__ == "__main__" 的作用
if __name__ == "__main__":result = search("什么是人工智能 Agent")print("\n搜索结果：")print(result)直接运行当前文件时：
python search.py测试代码会执行。
如果当前文件被其他模块导入：
from search import search测试代码不会自动执行。
因此，search.py 既可以独立测试，也可以作为 Agent 项目中的搜索工具模块使用。六、运行结果
运行：
python search.py终端输出：
🔍 正在执行 [SerpApi] 网页搜索：什么是人工智能 Agent搜索结果：
AI agent (AI 智能体) 是一种通过使用可用工具设计工作流来自主执行任务的系统。AI agent (AI 智能体) 的功能范围远不止自然语言处理，还包括决策制定、问题求解、与外部环境交互以及执行各种操作。这说明程序成功完成了以下过程：
读取 .env 中的 API Key↓
创建 SerpApi Client↓
向 SerpApi 提交 Google 搜索请求↓
获得结构化搜索结果↓
从 answer_box 中读取直接答案↓
将答案返回并打印由于 Google 搜索结果会受到时间、地区、语言和页面结构的影响，所以不同时间运行时，具体输出内容可能有所不同。
如果搜索结果中没有 answer_box，程序会继续尝试读取 knowledge_graph。
如果知识图谱也不存在，则返回前三条普通网页搜索结果。七、总结
使用新版 SerpApi Python SDK 实现一次搜索，核心代码只有以下几步：
import serpapiclient = serpapi.Client(api_key="你的API_KEY",
)results = client.search({"engine": "google","q": "搜索内容",
})得到结果后，可以根据需求读取不同字段：
results.get("answer_box", {})
results.get("knowledge_graph", {})
results.get("organic_results", [])
results.get("related_questions", [])
results.get("related_searches", [])本文完整例程采用了下面的结果解析优先级：
Answer Box↓
Knowledge Graph↓
Organic Results这种设计适合作为一个简单的 Agent 搜索工具：有直接答案时，快速返回答案；
没有直接答案时，尝试返回知识图谱；
再没有时，返回普通网页标题、摘要和链接。需要特别注意新版与旧版包的区别。
旧版代码可能使用：
from serpapi import SerpApiClient新版官方包应使用：
import serpapiclient = serpapi.Client(...)通过 SerpApi，可以较为方便地为 Agent、RAG 和大语言模型应用增加基础的互联网搜索能力，同时避免自行处理搜索页面抓取、验证码、代理和 HTML 解析等问题。 北京通州网站建设网站备案是域名备案还是主机备案
北京通州网站建设,网站备案是域名备案还是主机备案,asp网站js悬浮窗怎么做,乌海做网站的公司在开发大语言模型应用、RAG 系统或者 Agent 时，经常需要让程序获取互联网中的最新信息。
一种直接的方法是自己编写爬虫抓取搜索引擎页面，但这种方式需要处理页面结构变化、反爬虫、验证码、代理和结果解析等问题。
…
在开发大语言模型应用、RAG 系统或者 Agent 时，经常需要让程序获取互联网中的最新信息。
一种直接的方法是自己编写爬虫抓取搜索引擎页面，但这种方式需要处理页面结构变化、反爬虫、验证码、代理和结果解析等问题。
SerpApi 将这些过程封装成了搜索 API。开发者只需要传入搜索关键词和相关参数，就可以获得结构化的搜索结果。
本文介绍 SerpApi 的基本概念、安装与配置方法，并实现一个简单的 Google 网页搜索工具。一、SerpApi 是什么
SERP 是 Search Engine Results Page 的缩写，即“搜索引擎结果页面”。
SerpApi 是一个第三方搜索结果 API 服务。它可以调用 Google、Bing、百度、Google Scholar、Google News、Google Maps、YouTube 等搜索服务，并将搜索页面解析为结构化 JSON 数据。
例如，在 Google 中搜索：
什么是人工智能 Agent普通用户看到的是一个网页，而程序通过 SerpApi 可以获得类似下面的结构化结果：
{"answer_box": {"snippet": "AI Agent 是一种能够自主完成任务的人工智能系统……"},"knowledge_graph": {"title": "AI Agent","description": "……"},"organic_results": [{"position": 1,"title": "网页标题","link": "网页地址","snippet": "网页摘要"}]
}程序可以直接读取：
results.get("answer_box")
results.get("knowledge_graph")
results.get("organic_results")不需要再对 HTML 网页进行手动解析。
SerpApi 比较适合以下场景：为 AI Agent 添加网页搜索工具；
为 RAG 系统补充互联网信息；
获取新闻、图片、论文和普通网页结果；
进行搜索结果分析；
获取特定地区、语言或设备下的搜索结果；
进行 SEO、竞品分析和信息监控。需要注意，SerpApi 是第三方服务，不是 Google 官方提供的 Python SDK。调用 SerpApi 需要注册账号并获取 API Key，同时搜索请求会消耗账户额度。二、安装 SerpApi
1. 安装新版 Python 包
执行：
python -m pip install -U serpapi本文还会使用 .env 文件管理 API Key，因此同时安装 python-dotenv：
python -m pip install -U serpapi python-dotenv也可以一次安装：
python -m pip install -U serpapi python-dotenv2. 新旧版本接口区别
网上很多较早的教程使用：
from serpapi import SerpApiClient或者：
from serpapi import GoogleSearch这些通常对应旧版 google-search-results 包。
新版官方包的安装名称是：
pip install serpapi新版推荐写法是：
import serpapiclient = serpapi.Client(api_key="你的API_KEY"
)因此，如果出现下面的错误：
ImportError: cannot import name 'SerpApiClient' from 'serpapi'通常说明当前安装的是新版 serpapi，但代码使用了旧版接口。
本文统一使用新版写法：
import serpapi以及：
serpapi.Client(...)三、配置 SerpApi
1. 获取 API Key
注册 SerpApi 账号后，可以在账户页面获取自己的 API Key。
API Key 属于敏感信息，不建议直接写入 Python 源码，例如不要这样写：
api_key = "xxxxxxxxxxxxxxxx"更推荐将 API Key 保存到 .env 文件中。
2. 创建 .env 文件
在项目根目录创建 .env 文件：
SERPAPI_API_KEY=你的SerpApi密钥例如项目结构为：
hello-agents/
├── .env
├── .gitignore
└── search.py3. 配置 .gitignore
为了避免将 API Key 上传到 GitHub，在 .gitignore 文件中加入：
.env
__pycache__/
*.pyc4. 在 Python 中读取 API Key
首先加载 .env：
from dotenv import load_dotenvload_dotenv()然后通过 os.getenv() 读取环境变量：
import osapi_key = os.getenv("SERPAPI_API_KEY")如果 .env 文件中配置了：
SERPAPI_API_KEY=abc123那么：
api_key = os.getenv("SERPAPI_API_KEY")读取到的就是字符串：
abc123四、完整例程
下面实现一个简单的网页搜索函数。
程序会按照以下顺序解析搜索结果：优先返回 answer_box 中的直接答案；
如果没有直接答案，则返回 knowledge_graph 中的知识图谱描述；
如果仍然没有，则返回前三条 organic_results 普通网页结果。import osimport serpapi
from dotenv import load_dotenv# 加载项目根目录下 .env 文件中的环境变量
load_dotenv()def search(query: str) - str:"""使用 SerpApi 调用 Google 搜索。结果解析顺序：1. Answer Box 直接答案；2. Knowledge Graph 知识图谱；3. 前三条普通网页搜索结果。"""print(f"🔍 正在执行 [SerpApi] 网页搜索：{query}")# 从环境变量中读取 SerpApi API Keyapi_key = os.getenv("SERPAPI_API_KEY")# 如果没有读取到 API Key，则直接返回错误信息if not api_key:return "错误：SERPAPI_API_KEY 未在 .env 文件中配置。"try:# 创建新版 SerpApi 客户端client = serpapi.Client(api_key=api_key,timeout=20,)# 设置 Google 搜索参数params = {"engine": "google","q": query,"gl": "cn","hl": "zh-cn",}# 发起搜索请求results = client.search(params)# ==================================================# 1. 优先读取 Answer Box# ==================================================answer_box = results.get("answer_box", {})if answer_box:# 不同类型的直接答案可能存放在不同字段中for field in ("answer","result","snippet","definition",):value = answer_box.get(field)if value:return str(value)# 某些直接答案会以列表形式返回answer_list = answer_box.get("list")if isinstance(answer_list, list):return "\n".join(str(item)for item in answer_list)# ==================================================# 2. 读取 Knowledge Graph# ==================================================knowledge_graph = results.get("knowledge_graph",{},)if knowledge_graph:title = knowledge_graph.get("title", "")description = knowledge_graph.get("description","",)if description:if title:return f"{title}\n{description}"return description# ==================================================# 3. 读取普通网页搜索结果# ==================================================organic_results = results.get("organic_results",[],)if organic_results:snippets = []# 最多返回前三条普通网页结果for index, result in enumerate(organic_results[:3],start=1,):title = result.get("title","无标题",)snippet = result.get("snippet","无摘要",)link = result.get("link","",)text = (f"[{index}] {title}\n"f"{snippet}")if link:text += f"\n链接：{link}"snippets.append(text)return "\n\n".join(snippets)# 请求成功，但没有找到可用结果return f"对不起，没有找到关于“{query}”的信息。"except serpapi.TimeoutError:return "搜索时发生错误：SerpApi 请求超时。"except serpapi.HTTPError as error:return f"搜索时发生 HTTP 错误：{error}"except Exception as error:return f"搜索时发生错误：{error}"if __name__ == "__main__":result = search("什么是人工智能 Agent")print("\n搜索结果：")print(result)五、分块详解
1. 加载 .env 文件
load_dotenv()load_dotenv() 会查找项目中的 .env 文件，并将其中的配置加载到当前 Python 进程的环境变量中。
之后便可以使用：
os.getenv("SERPAPI_API_KEY")获取 API Key。
如果环境变量不存在，os.getenv() 默认返回 None：
api_key = os.getenv("SERPAPI_API_KEY")if not api_key:return "错误：SERPAPI_API_KEY 未在 .env 文件中配置。"这里的 not api_key 可以同时判断：api_key 是 None；
api_key 是空字符串；
API Key 没有正确配置。2. 创建 SerpApi 客户端
client = serpapi.Client(api_key=api_key,timeout=20,
)这里使用的是新版 serpapi 包中的 Client。
api_key
用于验证 SerpApi 账户身份：
api_key=api_keytimeout
设置网络请求的超时时间：
timeout=20表示请求超过 20 秒仍未完成时，抛出超时异常。
客户端创建完成后，可以多次调用：
client.search(...)因此，在包含大量搜索操作的项目中，也可以将 client 创建为一个长期复用的对象，而不是每次搜索都重新创建。3. 设置搜索参数
例程中使用的参数为：
params = {"engine": "google","q": query,"gl": "cn","hl": "zh-cn",
}engine
指定搜索引擎：
"engine": "google"常见值包括：
"google"
"google_scholar"
"google_news"
"google_images"
"google_maps"
"bing"
"baidu"
"youtube"不同搜索引擎支持的参数和返回字段可能不同。
例如 Google Scholar：
params = {"engine": "google_scholar","q": "low-light image enhancement",
}百度：
params = {"engine": "baidu","q": "低照度图像增强",
}q
设置搜索关键词：
"q": query它可以是普通关键词：
"q": "人工智能 Agent"也可以使用 Google 搜索表达式：
"q": '"artificial intelligence agent"'限制网站：
"q": "image restoration site:openaccess.thecvf.com"限制标题：
"q": 'intitle:"low-light image enhancement"'排除关键词：
"q": "Python 教程 -广告"gl
设置 Google 搜索使用的国家或地区：
"gl": "cn"常见值包括：
cn：China
us：United States
uk：United Kingdom
jp：Japangl 会影响搜索结果的地区倾向和排序。
hl
设置 Google 搜索使用的语言：
"hl": "zh-cn"常见值包括：
zh-cn：简体中文
en：英文
ja：日文
fr：法文需要注意，hl 主要影响 Google 搜索界面和结果呈现语言，并不意味着结果网页一定全部使用该语言。4. 其他常用搜索参数
虽然完整例程中没有使用下面这些参数，但在实际项目中也比较常见。
location
指定搜索发起位置：
params = {"engine": "google","q": "附近的咖啡店","location": "Beijing, China","gl": "cn",
}它适合本地商家、招聘、地图、新闻和地区相关搜索。
通常建议将 location 设置到城市级别，并与对应的 gl 一起使用。
device
模拟不同设备执行搜索：
"device": "desktop"常见值：
desktop
tablet
mobile不同设备可能得到不同的搜索页面布局和结果排序。
start
设置搜索结果偏移量，主要用于分页：
"start": 0例如：
start=0：第一页
start=10：第二页
start=20：第三页分页搜索示例：
for start in range(0, 30, 10):results = client.search({"engine": "google","q": "人工智能 Agent","start": start,})每次调用 client.search() 都会产生一次新的搜索请求。
safe
控制成人内容过滤：
"safe": "active"常见值：
active：启用过滤
off：关闭过滤tbm
切换 Google 搜索类型：
"tbm": "nws"常见值包括：
isch：图片搜索
lcl：本地搜索
vid：视频搜索
nws：新闻搜索
shop：购物搜索
pts：专利搜索例如搜索新闻：
params = {"engine": "google","q": "人工智能 Agent","tbm": "nws",
}也可以直接使用独立引擎：
params = {"engine": "google_news","q": "人工智能 Agent",
}tbs
设置 Google 高级过滤条件，常用于时间过滤：
"tbs": "qdr:m"常见时间范围：
qdr:h：最近一小时
qdr:d：最近一天
qdr:w：最近一周
qdr:m：最近一个月
qdr:y：最近一年例如搜索最近一个月的 Agent 信息：
params = {"engine": "google","q": "AI Agent","tbs": "qdr:m",
}no_cache
强制获取新的搜索结果：
"no_cache": True默认情况下，SerpApi 可能返回完全相同请求的缓存结果。
需要尽量获取最新结果时，可以设置：
"no_cache": True不过这会重新执行搜索，并消耗搜索额度。
output
设置响应格式：
"output": "json"常见值：
json：返回结构化 JSON，默认值
html：返回原始 HTML通常使用默认的 JSON 即可。
HTML 主要用于调试，或者查看尚未被 SerpApi 解析成结构化字段的页面内容。
async
以异步方式提交搜索任务：
"async": True异步搜索会先提交任务并返回搜索 ID，之后需要通过 Search Archive API 获取最终结果。
普通 Agent 工具通常直接使用同步搜索即可，因此本文例程没有启用异步模式。5. 发起搜索请求
results = client.search(params)client.search() 会将参数发送给 SerpApi，并返回搜索结果。
新版 SDK 返回的是 SerpResults 对象。
它可以像普通 Python 字典一样使用：
results.get("answer_box", {})
results.get("knowledge_graph", {})
results.get("organic_results", [])也可以直接打印完整结果：
print(results)调试时还可以查看所有顶层字段：
print(results.keys())6. 为什么使用 get()
下面的写法直接通过键获取值：
answer_box = results["answer_box"]如果当前搜索结果中没有 answer_box，程序会抛出：
KeyError: 'answer_box'更安全的写法是：
answer_box = results.get("answer_box", {})如果字段存在，则返回对应值。
如果字段不存在，则返回指定的默认值 {}。
列表字段通常使用空列表作为默认值：
organic_results = results.get("organic_results",[],
)因为不同搜索请求返回的字段并不固定，所以解析 SerpApi 结果时通常应优先使用 .get()。7. 解析 answer_box
answer_box = results.get("answer_box", {})answer_box 表示 Google 搜索页面中的直接答案。
不同类型的搜索，直接答案可能存放在不同字段中，例如：
answer_box.get("answer")
answer_box.get("result")
answer_box.get("snippet")
answer_box.get("definition")
answer_box.get("list")因此代码按照顺序检查：
for field in ("answer","result","snippet","definition",
):value = answer_box.get(field)if value:return str(value)只要找到第一个有效字段，就直接返回结果。
例如，某次搜索可能返回：
{"answer_box": {"type": "organic_result","snippet": "AI Agent 是一种能够自主执行任务的系统……"}
}此时代码会读取：
answer_box.get("snippet")并返回对应文本。8. 解析 knowledge_graph
knowledge_graph = results.get("knowledge_graph",{},
)知识图谱通常用于描述某个明确实体，例如：人物；
公司；
学校；
城市；
技术；
产品；
组织。常见字段包括：
knowledge_graph.get("title")
knowledge_graph.get("description")
knowledge_graph.get("source")
knowledge_graph.get("website")
knowledge_graph.get("thumbnail")本文只读取：
title = knowledge_graph.get("title", "")
description = knowledge_graph.get("description","",
)然后将标题和描述拼接起来：
return f"{title}\n{description}"9. 解析 organic_results
organic_results = results.get("organic_results",[],
)organic_results 表示普通的自然搜索结果。
它通常是一个列表：
[{"position": 1,"title": "网页标题","link": "网页链接","snippet": "网页摘要"},{"position": 2,"title": "网页标题","link": "网页链接","snippet": "网页摘要"}
]例程只取前三条：
organic_results[:3]然后通过 enumerate() 同时获得结果编号和结果内容：
for index, result in enumerate(organic_results[:3],start=1,
):其中：
start=1表示编号从 1 开始，而不是从 0 开始。
单条普通搜索结果中比较常见的字段包括：
result.get("position")
result.get("title")
result.get("link")
result.get("displayed_link")
result.get("snippet")
result.get("date")
result.get("thumbnail")
result.get("sitelinks")这些字段同样不保证每次都存在。10. 其他常用返回字段
除了例程中的三个主要字段，SerpApi 还可能返回下面这些内容。
search_metadata
搜索任务的元信息：
metadata = results.get("search_metadata",{},
)常见内容包括：
metadata.get("id")
metadata.get("status")
metadata.get("created_at")
metadata.get("processed_at")
metadata.get("total_time_taken")其中：id：SerpApi 搜索任务 ID；
status：搜索任务状态；
total_time_taken：请求处理时间。search_parameters
记录当前搜索实际使用的参数：
search_parameters = results.get("search_parameters",{},
)调试时可以打印：
print(search_parameters)检查 engine、q、gl、hl、device 等参数是否生效。
search_information
记录搜索结果的基本信息：
search_information = results.get("search_information",{},
)可能包含：
search_information.get("query_displayed")
search_information.get("total_results")
search_information.get("page_number")
search_information.get("time_taken_displayed")related_questions
Google 搜索中的“其他用户还问了”：
related_questions = results.get("related_questions",[],
)单条内容可能包括：
question.get("question")
question.get("snippet")
question.get("title")
question.get("link")related_searches
Google 搜索页面底部的相关搜索词：
related_searches = results.get("related_searches",[],
)常见字段包括：
item.get("query")
item.get("link")serpapi_pagination
分页信息：
pagination = results.get("serpapi_pagination",{},
)可以从中获取下一页搜索地址或其他页码信息。
其他可能出现的字段
根据查询内容和搜索类型，还可能出现：
results.get("images_results")
results.get("news_results")
results.get("top_stories")
results.get("local_results")
results.get("shopping_results")
results.get("video_results")
results.get("recipes_results")
results.get("events_results")
results.get("ai_overview")这些字段并不是每次搜索都会返回。
SerpApi 返回哪些字段，取决于 Google 当前搜索页面中实际出现了哪些模块。
因此，不能假设某个字段一定存在。11. 异常处理
SerpApi 请求可能因为网络、API Key、账户额度或请求参数等原因失败。
请求超时
except serpapi.TimeoutError:return "搜索时发生错误：SerpApi 请求超时。"当请求超过客户端设置的 timeout 时，会进入这个分支。
HTTP 错误
except serpapi.HTTPError as error:return f"搜索时发生 HTTP 错误：{error}"常见 HTTP 错误包括：
400：请求参数错误或缺少必要参数
401：API Key 无效
429：请求频率超过限制或账户额度不足如果需要进一步区分，可以读取状态码：
except serpapi.HTTPError as error:if error.status_code == 401:return "错误：SerpApi API Key 无效。"if error.status_code == 429:return "错误：请求过于频繁或搜索额度不足。"return f"SerpApi HTTP 错误：{error}"其他异常
except Exception as error:return f"搜索时发生错误：{error}"用于捕获未预料到的其他错误，避免搜索工具导致整个 Agent 程序直接退出。12. if __name__ == "__main__" 的作用
if __name__ == "__main__":result = search("什么是人工智能 Agent")print("\n搜索结果：")print(result)直接运行当前文件时：
python search.py测试代码会执行。
如果当前文件被其他模块导入：
from search import search测试代码不会自动执行。
因此，search.py 既可以独立测试，也可以作为 Agent 项目中的搜索工具模块使用。六、运行结果
运行：
python search.py终端输出：
🔍 正在执行 [SerpApi] 网页搜索：什么是人工智能 Agent搜索结果：
AI agent (AI 智能体) 是一种通过使用可用工具设计工作流来自主执行任务的系统。AI agent (AI 智能体) 的功能范围远不止自然语言处理，还包括决策制定、问题求解、与外部环境交互以及执行各种操作。这说明程序成功完成了以下过程：
读取 .env 中的 API Key↓
创建 SerpApi Client↓
向 SerpApi 提交 Google 搜索请求↓
获得结构化搜索结果↓
从 answer_box 中读取直接答案↓
将答案返回并打印由于 Google 搜索结果会受到时间、地区、语言和页面结构的影响，所以不同时间运行时，具体输出内容可能有所不同。
如果搜索结果中没有 answer_box，程序会继续尝试读取 knowledge_graph。
如果知识图谱也不存在，则返回前三条普通网页搜索结果。七、总结
使用新版 SerpApi Python SDK 实现一次搜索，核心代码只有以下几步：
import serpapiclient = serpapi.Client(api_key="你的API_KEY",
)results = client.search({"engine": "google","q": "搜索内容",
})得到结果后，可以根据需求读取不同字段：
results.get("answer_box", {})
results.get("knowledge_graph", {})
results.get("organic_results", [])
results.get("related_questions", [])
results.get("related_searches", [])本文完整例程采用了下面的结果解析优先级：
Answer Box↓
Knowledge Graph↓
Organic Results这种设计适合作为一个简单的 Agent 搜索工具：有直接答案时，快速返回答案；
没有直接答案时，尝试返回知识图谱；
再没有时，返回普通网页标题、摘要和链接。需要特别注意新版与旧版包的区别。
旧版代码可能使用：
from serpapi import SerpApiClient新版官方包应使用：
import serpapiclient = serpapi.Client(...)通过 SerpApi，可以较为方便地为 Agent、RAG 和大语言模型应用增加基础的互联网搜索能力，同时避免自行处理搜索页面抓取、验证码、代理和 HTML 解析等问题。