tavily

Tavily Search

由 Tavily API 提供支持的网页搜索和 URL 内容提取。返回经过整理的结构化结果， 适合 AI 使用——没有 HTML 噪声、Cookie 横幅或分页内容。

何时使用 Tavily，何时使用其他工具

情况	工具	原因
需要了解某个主题的最新信息	search.mjs	Tavily 汇总并排序实时结果
需要最近 N 天的新闻	search.mjs --topic news --days N	新闻模式会筛选近期内容
已有特定 URL，需要全文	extract.mjs	从 URL 提取整洁的文章内容
需要某个库的文档	search.mjs --deep	深度模式会全面覆盖文档站点
需要已知的静态资源	直接获取或读取	如果不需要实时查询，就跳过 Tavily
需要多个相互竞争的观点	search.mjs -n 10	增加结果数量以拓宽视野

脚本

两个脚本都位于 scripts/，并要求在环境中设置 TAVILY_API_KEY。

• scripts/search.mjs — 基于查询的网页搜索
• scripts/extract.mjs — 从 URL 提取完整内容

搜索

node {baseDir}/scripts/search.mjs "query"
node {baseDir}/scripts/search.mjs "query" -n 10
node {baseDir}/scripts/search.mjs "query" --deep
node {baseDir}/scripts/search.mjs "query" --topic news
node {baseDir}/scripts/search.mjs "query" --topic news --days 3

搜索选项

选项	默认值	说明
-n <count>	5	返回的结果数量（最多 20 个）。增大此值可扩大覆盖范围。
--deep	off	高级搜索模式——速度较慢，但内容更全面。适用于复杂的研究问题、深入的技术探究，或标准结果不足时。
--topic <topic>	general	general 表示标准搜索；news 表示按时效筛选的时事新闻。
--days <n>	—	仅在使用 --topic news 时有效。将结果限制为过去 n 天内发布的文章。

从 URL 提取内容

node {baseDir}/scripts/extract.mjs "https://example.com/article"

当你已有 URL 并需要完整的页面内容时使用——Tavily 会去除导航、 广告和冗余内容，并返回结构化的文章文本。

输出格式

搜索结果以 JSON 数组形式返回。每个结果包含：

[
  {
    "title": "Article or page title",
    "url": "https://source.com/path",
    "content": "Clean text snippet (AI-optimized excerpt)",
    "score": 0.92
  }
]

score 是 Tavily 的相关性排名（0–1）。数值越高，相关性越强。解析结果时， 使用 content 进行摘要，并使用 url 标明出处。不要将 content 视为完整 文章——如果需要完整文本，请对该 URL 使用 extract.mjs。

提取结果以单个对象形式返回：

{
  "url": "https://source.com/path",
  "raw_content": "Full extracted page text..."
}

错误处理

错误	原因	解决方法
TAVILY_API_KEY not set	缺少环境变量	运行前设置 TAVILY_API_KEY。请前往 https://tavily.com 获取密钥。
401 Unauthorized	API 密钥无效	检查密钥值；如有需要，请在 Tavily 控制面板中重新生成。
429 Too Many Requests	触发速率限制	降低请求频率；免费套餐每月提供 1000 个 API 积分。
空结果数组 []	未找到匹配项	扩大或改写查询；对于小众主题，请尝试使用 --deep。
ETIMEDOUT / timeout	网络或 API 延迟	重试一次；--deep 搜索耗时较长（最长 30s）。
Extract 返回空内容	页面屏蔽了爬虫	使用其他来源，或改用手动获取方式。

局限性

• 速率限制：免费套餐每月提供 1000 个 API 积分。每次搜索消耗 1 个积分；--deep 消耗更多积分。
• 内容时效性：结果取决于 Tavily 的索引；非常近期的内容（最近几小时内）可能不会出现在 general 模式下。对于对时效性敏感的查询，请使用 --topic news。
• 结果质量：Tavily 针对适合 AI 阅读的内容进行了优化，但无法保证事实准确性。请从一手来源核实重要说法。
• 付费墙内容：付费墙后的文章只会返回公开可访问的摘录。
• 非文本内容：PDF、图像和媒体页面的提取效果较差，或无法提取。
• 语言：英文查询的效果最佳。支持其他语言，但结果质量不一。