用 Python 调用 Tavily 搜索 API:域名筛选 | SandBase

用 Python 发起单次 Tavily 搜索,设置域名筛选并检查响应。已知 URL 可另行提交 Extract。

Tavily 搜索、抽取和站点映射概念插画,不代表已运行 RAG 工作流

查开发文档时,搜到“看起来相关”的网页还不够:来源可能不对,内容也可能过时。用 Python 调用 Tavily 搜索 API,可以先通过域名筛选限定检索来源,再检查响应是否适合交给应用处理。比如查 Codex 文档时,先把来源限定为 openai.com。这能约束请求范围,但不能替你判断页面里的说法是否准确。

本文使用 Tavily Search 端点,给出一次 Search 请求、一个排除域名的替代 body,以及人工选择 URL 后独立提交 Extract 的格式。新 Python 示例没有执行真实业务请求,不运行网页抽取、模型或 Agent。文档核对日为 2026-11-06;旧响应示意和三张截图保留自 2026-09-27 发布的原文,不能当作今天的调用结果。

先说结论

  • Search 按 query 找候选来源,Extract 接收另外选定的 URL 数组。
  • 调用文档中的 Model API POST 路由,用 SandBase 密钥,body 只放端点参数。
  • HTTP 成功、运行完成后,只读对象类型的 outputs[0].data,不回退到顶层 output。
  • Python 只发一次 Search,打印载荷键名;完成态不代表来源或内容已经核实。

保留的封面是搜索、抽取和站点映射的概念插画。图中的 RAG 场景不表示本文已经执行了这条链路。

先看手里是问题还是 URL

端点要跟输入匹配。只有检索问题时,先找候选来源;已经知道要检查哪一页,就不必再靠搜索替你选 URL。

手里的输入对应端点接下来检查什么
一个问题或主题Search,传 query候选来源是否适合当前任务
已经选好的公开网页Extract,传 urls 数组哪些 URL 有结果,哪些失败
想了解一个站点有哪些页面Map 参考按它自己的 schema 做 URL 发现

Search 和 Extract 是两次独立请求。当前 Extract 参考样例列出 URL、标题、图片字段和 failed_results,没有演示 raw_content。这不证明它永远无法返回正文,也不能据此保证目标网页的全文都能取得。写正文解析器或完整 RAG 教程前,需要带日期的目标响应确认可用文本。

SandBase 提供调用第三方能力的 Model API 路由和鉴权层。密钥相同,不代表各端点的业务字段相同。如果需要更多控制项,可以比较 Tavily 原厂 Search 文档与 SandBase 变体的 schema;原厂支持某个参数,不代表可以直接把它放进本文请求。

历史 SandBase Tavily 目录,显示端点卡片与目录 GET 路径 保留自 2026-09-27 原文的目录截图。图中的 GET 路径和包含 $0.08 在内的旧 From 标价,不是当前 Model API 请求地址或现行报价。

Python 搜索时怎样设置域名筛选

想只查选定来源,用 include_domains;想在较广的检索范围中排除某站点,用 exclude_domains。两者都接收域名字符串数组,键名不带 []。例如 include_domains: ["openai.com"] 表示请求限定这个来源,不是把某篇网页地址作为输入。

不要把同一域名同时放进包含和排除列表,再猜哪条规则优先。本文没有确认重叠时的处理顺序,所以一次只使用一种列表。筛选用域名,已选网页的完整 URL 则交给独立 Extract 请求。

Search 参数当前 SandBase 类型或取值本例选择
query必填字符串OpenAI Codex documentation
include_domains、exclude_domains字符串数组只包含 openai.com
search_depthbasic 或 advancedbasic
max_results整数 1–20,schema 默认 5显式设为 3
topicgeneral、news、finance,默认 general省略
include_answer布尔值false
include_raw_content布尔值false

max_results: 3 是请求上限,结果可能少于三条。首次接入先关闭答案和原始内容选项,便于把来源发现与后续处理分开。需要这些选项时再显式开启,并检查实际返回;请求了某个字段,不等于每一页都返回完整内容。

下面是“排除一个站点”的替代 body。它没有被加入 Python 程序,因此不会多发一次请求:

JSON
{"query": "OpenAI Codex documentation", "exclude_domains": ["reddit.com"], "search_depth": "basic", "max_results": 3, "include_answer": false, "include_raw_content": false}

只提交本变体 Parameters schema 中的字段。这里没有 include_domains_mode、time_range、start_date 或 include_images;答案和原始内容选项也不接收原厂的字符串模式。旧截图或概览文字不能替代这份参数表。

发出一次请求,逐层检查响应

这里使用 Model API POST,不使用目录 GET。先运行 python -m pip install requests,在运行 Python 的环境中设置 SANDBASE_API_KEY,可选设置 TAVILY_QUERY。未设置 query 时使用上面的文档查询;如果显式设置为空字符串或全空白,程序会在联网前报错。将代码保存为 tavily_search.py,运行 python tavily_search.py。

当前 Search 参考说明请求参数与 outputs[0].data 路径。代码设置连接和读取超时,关闭自动重定向,不重试。输出只有载荷键名,不能把它当成整理好的搜索报告。

Python
import os
import requests


def check_error(container):
    error = container.get("error")
    if error is None:
        return
    if isinstance(error, (str, dict)) and len(error) == 0:
        return
    raise RuntimeError("API reported an error or unsupported error shape")


def search_once(params):
    key = os.environ.get("SANDBASE_API_KEY", "").strip()
    if not key:
        raise RuntimeError("Set SANDBASE_API_KEY")
    try:
        response = requests.post(
            "https://api.sandbase.ai/v1/api/tavily/search",
            headers={"Authorization": f"Bearer {key}",
                     "Content-Type": "application/json"},
            json=params, timeout=(10, 60), allow_redirects=False,
        )
    except requests.Timeout:
        raise RuntimeError("Timeout; no retry was sent") from None
    except requests.RequestException:
        raise RuntimeError("Transport failure; no retry was sent") from None
    if not 200 <= response.status_code < 300:
        raise RuntimeError(f"HTTP {response.status_code}; no retry was sent")
    try:
        run = response.json()
    except ValueError:
        raise RuntimeError("Response was not valid JSON") from None
    if not isinstance(run, dict):
        raise RuntimeError("Expected a JSON run object")
    check_error(run)
    if run.get("status") != "completed":
        raise RuntimeError("Run is not completed; no polling was started")
    outputs = run.get("outputs")
    if not isinstance(outputs, list) or not outputs:
        raise RuntimeError("Missing nonempty outputs array")
    first = outputs[0]
    if not isinstance(first, dict):
        raise RuntimeError("Expected an output object")
    check_error(first)
    if "data" not in first or not isinstance(first["data"], dict):
        raise RuntimeError("Missing, null or non-object outputs[0].data")
    return first["data"]  # Preserve {}; never read legacy output.


def main():
    query = os.environ.get("TAVILY_QUERY", "OpenAI Codex documentation")
    if not query.strip():
        raise RuntimeError("TAVILY_QUERY must not be blank")
    data = search_once({
        "query": query,
        "include_domains": ["openai.com"],
        "search_depth": "basic",
        "max_results": 3,
        "include_answer": False,
        "include_raw_content": False,
    })
    print("payload_keys:", sorted(data.keys()))


if __name__ == "__main__":
    main()

检查顺序有实际作用:HTTP 失败就先停下,不假设错误页一定是 JSON;运行层和首个输出层的 error 分别检查,不对字符串错误直接调用 .get()。非完成态也会终止,本例不会转入轮询。缺字段、null、列表或字符串都不能当业务对象使用。

合法空对象 {} 则原样保留,打印空键列表。它和“没读到数据就补一个空对象”不是同一种情况:前者是返回内容为空,后者会掩盖接入错误。即便运行完成且载荷类型正确,来源仍可能不适合你的问题;引用前还要核对链接和页面内容。

历史 Tavily Search 参考,展示 outputs 数组和空 data 样例 保留自 2026-09-27 原文的 Search 参考截图:图中展示 outputs[0].data 与空对象示例。当前 README 的业务样例已经非空,这张图也不是新 Python 请求的运行结果。

保留旧响应,但不再用它写解析器

下面保留原文的历史旧信封示意,本体不变:原记录日期为 2026-09-27 UTC,run id 为 a37e8e9d-b389-479d-ae8c-7822d5fe8629。本次没有重新验证这条历史记录。省略号和零值是示意,不是当前搜索结果或耗时测量;新代码不读取其中的顶层 output。

JSON
{
  "id": "a37e8e9d-b389-479d-ae8c-7822d5fe8629",
  "model": "tavily/search",
  "status": "completed",
  "output": {
    "query": "…",
    "answer": "…",
    "results": [ { "title": "…", "url": "…", "content": "…", "score": 0.0 } ],
    "response_time": 0.0
  }
}

原文“参考业务示例刻意留空”的说法已撤销。2026-11-06 核对的 Search README 有截短结果示例,其中 answer 和 raw_content 为 null。参考请求没有采用本文相同的域名筛选,因此不能把它直接当作新 Python 请求的响应。本文没有宣称新请求已经成功执行。

人工选定 URL,再独立提交 Extract

已经选好公开网页时,查看 Extract 请求参考。地址为 POST https://api.sandbase.ai/v1/api/tavily/extract,必填 urls 是数组,只有一个网页也不改成字符串。当前可选字段只有 extract_depth(basic 或 advanced)和布尔值 include_images。

下面是一个人工选定公开 URL 的独立 body:

JSON
{"urls": ["https://en.wikipedia.org/wiki/Artificial_intelligence"]}

如果应用把选定地址放在 TAVILY_SOURCE_URL 中,应在单独确认该次请求后,用变量的值替换唯一 URL,而不是把变量名当字符串发送。前面的 Python 不读取这个变量,也不调用 Extract,更不会自动把 Search 第一条结果传过去。

当前参考区分 results 和 failed_results。HTTP 成功和运行完成都不等于每个 URL 取得了想要的内容。缺少 raw_content 时保留未知,不能补成空正文就继续喂给下游。真正需要正文的应用,要在这里补上目标网页的实际响应验证;历史示意不能代替这一步。

历史 Tavily Extract 参考,显示请求参数与通用响应示例 保留自 2026-09-27 原文的 Extract 参考截图,并非端点列表。旧 UI 显示 urls_0 和空响应示例;实际请求应使用上文的 urls 数组。该图不证明已经提取到网页全文。

费用与运行边界

截至 2026-11-06,Search 和 Extract 登记基础价均为每次成功调用 $0.012,并参与组织每天共享的免费额度:符合条件的数据 API 调用合计前 100 次免费,00:00 UTC 重置。不是每个端点各有 100 次。以当前端点价格和账户用量为准,不用原厂 usage.credits 推算 SandBase 账单;Map 当前登记为不参与该额度,也不能把规则推广到所有 Tavily 端点。

超时后是否重发,需要单独考虑重复工作和用量。本例遇到超时、网络失败、重定向或无效响应就停止,没有自动重试。它没有测量覆盖率、答案质量、延迟、抽取成功率或多步骤研究任务的总成本。

如果还在选择来源发现方式,可以读 Exa Search 接入教程。那篇使用另一个端点契约,不能据此认定两家的业务字段可以直接互换。

常见问题

可以回退到 output 吗? 不可以。检查 HTTP 成功和完成态后,要求 outputs[0].data 为对象。保留的历史示意不是现行解析规范。

域名筛选怎么传? 使用 include_domains 或 exclude_domains 数组,键名无 []。避免包含与排除列表重叠,不臆定优先级;筛选来源不等于核实内容。

一定返回答案和原始内容吗? 不保证。本例两个布尔选项都为 false。需要时显式开启,并先检查响应,再依赖相应字段。

Extract 能证明全文 RAG 吗? 不能。它独立接收选定 URL,当前参考样例没有展示 raw_content。发布正文解析器或串联示例前,需要带日期的实际响应确认可用文本;样例缺字段不代表永远不能返回正文。

从一次限定来源的 Search 开始,先检查载荷。选好具体网页后,再按独立的 Extract API 参考决定下一步。

觉得有用?分享给更多人