Python调用Exa AI搜索API实现语义检索与结果解析教程

把自然语言问题发给搜索接口，再把结果中的标题、网址与相关片段提取出来，就能为资料检索或后续问答准备输入。下面以 Exa 的 Python 接口为例，认识从调用配置到结果对象的各个部分。这里检索的是互联网网页，不是在本地文件夹里建立向量数据库。

概述

Exa 的 Python 包名是 exa-py，导入模块名是 exa_py。官方说明要求 Python 3.9 或更新版本。准备好可用账户、API 密钥及额度后，可以在 Windows 的项目终端中安装：

py -m pip install exa-py

在 Windows 终端中使用 pip 安装 exa-py 包

安装与运行脚本应使用同一个 Python 环境。密钥通过环境变量 EXA_API_KEY 提供，不写进脚本，也不打印到终端或提交到代码仓库。下面展示接口用法与解析逻辑，不把示意代码称为已完成真实联网检索；具体返回内容取决于运行时的检索结果。

关于查询配置区

一次调用最核心的是问题、检索方式和结果数量。自然语言问题应说明真正想找的材料，例如“介绍检索增强生成中语义检索与关键词检索差异的技术文章”，比只输入“AI”更容易判断返回页面是否相关。

Exa 官方将 neural 描述为基于嵌入的语义搜索；auto 则由服务选择方式。这里显式使用 neural，让示例与语义检索目标一致。它不会保证每条结果都正确，也不等于要求接口直接生成一份完整答案。

num_results=3 用来控制本次请求的结果数量。contents={"highlights": True} 则要求获取相关片段，便于先判断网页价值；它与下载全文不是同一个选项。初次接入先保持参数少而明确，再按需要增加范围限制。

关于查询配置区

关于客户端与请求区

将下面代码保存为 search_demo.py。客户端使用环境变量中的密钥，再发出一次查询。检查变量是否存在，可以避免把未配置密钥的问题误认为检索失败。

import os
from exa_py import Exa

api_key = os.getenv("EXA_API_KEY")
if not api_key:
    raise SystemExit("请先配置 EXA_API_KEY 环境变量")

client = Exa(api_key=api_key)
response = client.search(
    "介绍检索增强生成中语义检索与关键词检索差异的技术文章",
    type="neural",
    num_results=3,
    contents={"highlights": True},
)

for index, item in enumerate(response.results, start=1):
    print(f"{index}. {item.title or '无标题'}")
    print(item.url)
    for fragment in item.highlights or []:
        print(fragment)
    print()

if not response.results:
    print("本次没有返回结果，请检查问题表述与筛选条件")

search_demo.py 脚本代码结构示意

在项目终端运行 py search_demo.py。脚本只发送代码中的这一条问题；它没有建立聊天会话，也没有执行检索到的网页内容。查询会传给外部服务，因此示例使用普通技术问题，不把内部文档或密钥混入查询文本。

关于结果对象区

这里使用 SDK 返回的对象，外层通过 response.results 访问结果列表，每一项再读取 title、url 和 highlights。不要把 SDK 对象和直接 HTTP 调用解析得到的字典混用，否则容易出现属性访问与下标访问不匹配的问题。

highlights 是片段列表，代码逐项打印。它可能没有内容，因此用 or [] 处理空值，不能默认总能取得第一段。标题同样可能缺失，显示“无标题”只是本地展示处理，不是接口返回了这样的标题。

如果后续要交给另一个模型，应让网址与片段保持对应，避免把多页片段拼起来后丢失来源。先人工打开相关页面确认内容，再决定是否需要进一步获取全文。检索片段有助于初筛，不能替代完整上下文。

关于结果对象区

关于终端状态与验证区

请求成功后，重点检查三件事：结果是否围绕语义检索与关键词检索的差异，网址是否对应实际页面，片段是否足以支持你的用途。没有固定的文章标题或片段输出可照抄，也不能仅凭出现三条记录就宣称检索质量已经达标。

发生异常时，先区分安装环境、密钥授权、账户额度与服务访问问题，再查看服务给出的错误说明。不要为了排错打印完整密钥，也不要把未知结果的请求放进无限重试循环。

保留脚本、使用的包版本及脱敏后的查询和结果，便于以后复查。至此，你得到的是可以继续筛选和引用的网页检索结果；自动生成回答、建立本地知识库和评估召回质量，属于后续独立工作。

关于终端状态与验证区