Tavily AI 搜索

概述

Tavily 是一款专门为大型语言模型和人工智能应用优化的搜索引擎。与传统搜索 API 不同，Tavily 提供 AI 就绪的结果，具备可选的答案生成、纯净内容提取和域名过滤功能。

核心能力：

• 基于搜索结果生成 AI 答案摘要
• 为 LLM 处理优化的、洁净的结构化结果
• 快速（基础）和全面（高级）搜索模式
• 域名过滤（包含/排除特定来源）
• 专注于新闻的时事搜索
• 附带相关视觉内容的图片搜索
• 用于深入分析的原始内容提取

架构

graph TB
    A[用户查询] --> B{搜索模式}
    B -->|基础| C[快速搜索<br/>1-2秒响应]
    B -->|高级| D[全面搜索<br/>5-10秒响应]
    
    C --> E[Tavily API]
    D --> E
    
    E --> F{主题过滤器}
    F -->|通用| G[广泛的网络搜索]
    F -->|新闻| H[新闻来源<br/>最近7天]
    
    G --> I[域名过滤]
    H --> I
    
    I --> J{包含域名？}
    J -->|是| K[过滤到特定域名]
    J -->|否| L{排除域名？}
    K --> M[搜索结果]
    L -->|是| N[移除不需要的域名]
    L -->|否| M
    N --> M
    
    M --> O{响应选项}
    O --> P[AI 答案<br/>摘要]
    O --> Q[结构化结果<br/>标题，URL，内容，评分]
    O --> R[图片<br/>如请求]
    O --> S[原始 HTML 内容<br/>如请求]
    
    P --> T[返回至代理]
    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

搜索模式

基础版与高级版

决策树：

1. 需要快速查找事实或定义？ → 使用基础版
2. 研究复杂主题？ → 使用高级版
3. 需要多角度信息？ → 使用高级版
4. 查询时间敏感？ → 使用基础

通用 vs 新闻

决策树：

1. 查询包含"最新"、"近期"、"当前"、"今天"？ → 使用新闻
2. 寻找历史或长青内容？ → 使用通用
3. 需要最新信息？ → 使用新闻

API密钥设置

选项 1：Clawdbot 配置（推荐）

添加到你的 Clawdbot 配置中：

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

通过Clawdbot的配置系统在脚本中访问。

选项2：环境变量

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 "人工智能政策更新" --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
• 内容：提取的文本片段
• 得分：相关性得分（0-1）
• 原始内容：完整HTML（如果启用 --raw-content）

图像

当启用 --images时，返回搜索期间找到的相关图像的URL。

最佳实践

1. 选择正确的搜索深度

• 对于大多数查询，从基础开始（更快、更经济）
• 仅在以下情况下升级到高级：
  • 初始结果不足
  • 主题复杂或微妙
  • 需要全面覆盖

2. 策略性地使用域名过滤

包含以下域：

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

排除以下域：

• 已知的低质量内容农场
• 无关的内容类型（针对非视觉查询的Pinterest）
• 设有付费墙或访问限制的网站

3. 优化成本

• 使用基础深度作为默认设置
• 限制最大结果数至实际所需数量
• 禁用包含原始内容除非需要
• 本地缓存结果以应对重复查询

4. 优雅地处理错误

脚本提供有用的错误信息：

# API密钥缺失
错误：需要Tavily API密钥
设置：设置TAVILY_API_KEY环境变量或传递--api-key参数

# 包未安装
错误：tavily-python包未安装
安装方法：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对比

对比Brave搜索：

• ✅ AI答案生成
• ✅ 原始内容提取
• ✅ 更好的域名过滤
• ❌ 比Brave慢
• ❌ 消耗积分

对比Perplexity：

• ✅ 对来源有更多控制
• ✅ 提供原始内容
• ✅ 专用新闻模式
• ≈ 相似的答案质量
• ≈ 相似的速度

对比谷歌自定义搜索：

• ✅ 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