Tavily AI 搜索

概述

Tavily 是一款专为大语言模型（LLM）和 AI 应用优化的搜索引擎。与传统搜索 API 不同，Tavily 提供面向 AI 就绪的结果，支持可选的答案生成、干净的内容提取以及域名过滤功能。

核心能力：

• 从搜索结果中生成 AI 摘要答案
• 结构清晰、专为 LLM 处理优化的结果
• 快速模式（basic）与全面模式（advanced）两种搜索方式
• 域名过滤（可指定包含/排除特定来源）
• 聚焦新闻的搜索能力，适用于时效性事件
• 图像搜索，返回相关视觉内容
• 原始内容提取，支持深度分析

架构

graph TB
    A[用户查询] --> B{搜索模式}
    B -->|basic| C[快速搜索
响应时间 1–2 秒]
    B -->|advanced| D[全面搜索
响应时间 5–10 秒]
    
    C --> E[Tavily API]
    D --> E
    
    E --> F{主题过滤}
    F -->|general| G[全网通用搜索]
    F -->|news| H[新闻源
最近 7 天]
    
    G --> I[域名过滤]
    H --> I
    
    I --> J{是否包含指定域名？}
    J -->|yes| K[限定于特定域名]
    J -->|no| L{是否排除指定域名？}
    K --> M[搜索结果]
    L -->|yes| N[移除不相关域名]
    L -->|no| M
    N --> M
    
    M --> O{响应选项}
    O --> P[AI 答案
摘要]
    O --> Q[结构化结果
标题、URL、内容、相关性得分]
    O --> R[图像
如请求]
    O --> S[原始 HTML 内容
如请求]
    
    P --> T[返回给 Agent]
    Q --> T
    R --> T
    S --> T
    
    style E fill:#4A90E2
    style P fill:#7ED321
    style Q fill:#7ED321
    style R fill:#F5A623
    style S fill:#F5A623

快速上手

基础搜索

# 带 AI 答案的简单查询
scripts/tavily_search.py "什么是量子计算？"

# 返回多个结果
scripts/tavily_search.py "Python 最佳实践" --max-results 10

高级搜索

# 全面研究模式
scripts/tavily_search.py "气候变化解决方案" --depth advanced

# 聚焦新闻的搜索
scripts/tavily_search.py "2026 年 AI 发展动态" --topic news

域名过滤

# 仅在可信域名中搜索
scripts/tavily_search.py "Python 教程" 
  --include-domains python.org docs.python.org realpython.com

# 排除低质量来源
scripts/tavily_search.py "如何编程" 
  --exclude-domains w3schools.com geeksforgeeks.org

图像搜索

# 包含相关图像
scripts/tavily_search.py "埃菲尔铁塔建筑风格" --images

搜索模式

basic 与 advanced 对比

决策树：

1. 需要快速获取一个事实或定义？→ 使用 basic
2. 正在研究复杂主题？→ 使用 advanced
3. 需要多角度观点？→ 使用 advanced
4. 查询具有时效敏感性？→ 使用 basic

general 与 news 对比

决策树：

1. 查询中包含“最新”、“近期”、“当前”、“今日”等词？→ 使用 news
2. 查找历史资料或常青内容？→ 使用 general
3. 需要最新信息？→ 使用 news

API 密钥配置

方案一：Clawdbot 配置（推荐）

在 Clawdbot 配置中添加以下内容：

{
  "skills": {
    "entries": {
      "tavily": {
        "enabled": true,
        "apiKey": "tvly-YOUR_API_KEY_HERE"
      }
    }
  }
}

脚本中可通过 Clawdbot 的配置系统访问该密钥。

方案二：环境变量

export TAVILY_API_KEY="tvly-YOUR_API_KEY_HERE"

添加至 ~/.clawdbot/.env 或您的 shell 配置文件中。

获取 API 密钥

1. 访问 https://tavily.com
2. 注册账户
3. 进入控制台仪表板
4. 生成 API 密钥（以 tvly- 开头）
5. 留意您所选套餐的调用频率限制与信用额度分配

常见使用场景

1. 研究与事实核查

# 带答案的全面研究
scripts/tavily_search.py "解释量子纠缠" --depth advanced

# 多个权威来源
scripts/tavily_search.py "REST API 设计最佳实践" 
  --max-results 10 
  --include-domains github.com microsoft.com google.com

2. 当前事件追踪

# 最新新闻
scripts/tavily_search.py "AI 政策更新" --topic news

# 特定领域最新进展
scripts/tavily_search.py "量子计算突破" 
  --topic news 
  --depth advanced

3. 领域专属研究

# 仅限学术来源
scripts/tavily_search.py "机器学习算法" 
  --include-domains arxiv.org scholar.google.com ieee.org

# 技术文档检索
scripts/tavily_search.py "React Hooks 指南" 
  --include-domains react.dev

4. 视觉资料收集

# 收集视觉参考素材
scripts/tavily_search.py "现代网页设计趋势" 
  --images 
  --max-results 10

5. 内容提取

# 获取原始 HTML 内容用于深度分析
scripts/tavily_search.py "Python async/await" 
  --raw-content 
  --max-results 5

响应处理

AI 答案

AI 生成的答案是对搜索结果进行综合提炼后形成的简洁摘要：

{
  "answer": "量子计算是一种利用量子力学现象进行计算的新型计算范式..."
}

建议使用场景：

• 需要快速摘要
• 希望从多个来源中综合信息
• 寻求对问题的直接回答

建议跳过场景（使用 --no-answer 参数）：

• 仅需源 URL 列表
• 希望自行完成信息整合
• 需节省 API 信用额度

结构化结果

每个结果项包含以下字段：

• title：页面标题
• url：来源 URL
• content：提取的文本片段
• score：相关性得分（0–1）
• raw_content：完整 HTML 内容（启用 --raw-content 后返回）

图像

当启用 --images 参数时，将返回搜索过程中发现的相关图像 URL。

最佳实践

1. 选择合适的搜索深度

• 大多数查询优先使用 basic（更快、成本更低）
• 仅在以下情况升级至 advanced：
  • 初始结果不足
  • 主题本身复杂或存在细微差别
  • 需要全面覆盖

2. 策略性使用域名过滤

建议包含的域名类型：

• 学术研究（.edu 域名）
• 官方文档（项目官网）
• 可信新闻源
• 已知权威来源

建议排除的域名类型：

• 已知低质量内容农场
• 无关内容类型（例如非视觉类查询时排除 Pinterest）
• 设有付费墙或访问限制的站点

3. 成本优化

• 默认使用 basic 深度
• 将 max_results 限制为实际所需数量
• 除非必要，禁用 --raw-content
• 对重复查询进行本地缓存

4. 错误处理

脚本提供清晰的错误提示信息：

# 缺失 API 密钥
Error: Tavily API key required
Setup: Set TAVILY_API_KEY environment variable or pass --api-key

# 未安装依赖包
Error: tavily-python package not installed
To install: pip install tavily-python

集成模式

程序化调用

from tavily_search import search

result = search(
    query="什么是机器学习？",
    api_key="tvly-...",
    search_depth="advanced",
    max_results=10
)

if result.get("success"):
    print(result["answer"])
    for item in result["results"]:
        print(f"{item['title']}: {item['url']}")

JSON 输出（便于解析）

scripts/tavily_search.py "Python 教程" --json > results.json

与其他工具链式调用

# 搜索并提取内容
scripts/tavily_search.py "React 文档" --json | 
  jq -r '.results[].url' | 
  xargs -I {} curl -s {}

与其他搜索 API 的对比

vs Brave Search：

• ✅ 支持 AI 答案生成
• ✅ 支持原始内容提取
• ✅ 域名过滤能力更强
• ❌ 响应速度慢于 Brave
• ❌ 消耗信用额度

vs Perplexity：

• ✅ 对数据源拥有更高控制权
• ✅ 可获取原始内容
• ✅ 提供专用新闻搜索模式
• ≈ 答案质量相近
• ≈ 响应速度相近

vs Google Custom Search：

• ✅ 结果专为 LLM 优化
• ✅ 支持答案生成
• ✅ API 更加简洁易用
• ❌ 索引规模较小
• ≈ 成本结构相似

故障排查

脚本无法运行

# 添加可执行权限
chmod +x scripts/tavily_search.py

# 检查 Python 版本（需 3.6+）
python3 --version

# 安装依赖
pip install tavily-python

API 密钥问题

# 验证 API 密钥格式（应以 tvly- 开头）
echo $TAVILY_API_KEY

# 使用显式密钥测试
scripts/tavily_search.py "test" --api-key "tvly-..."

调用频率超限错误

• 前往 https://tavily.com 查看您当前套餐的信用额度分配
• 降低 max_results 数值以节省信用额度
• 改用 basic 深度替代 advanced
• 对重复查询实现本地缓存

资源

详见 api-reference.md 文件，其中包含：

• 完整的 API 参数说明
• 响应格式规范
• 错误处理详情
• 费用与调用频率限制信息
• 高级用法示例

依赖项

• Python 3.6+
• tavily-python 包（安装命令：pip install tavily-python）
• 有效的 Tavily API 密钥

致谢与归属

• Tavily API：https://tavily.com
• Python SDK：https://github.com/tavily-ai/tavily-python
• 文档：https://docs.tavily.com