tavily

Tavily AI 搜索

概述

Tavily 是一款专为大模型和 AI 应用优化的搜索引擎。与传统搜索 API 不同，Tavily 提供可直接用于 AI 的结果，并支持可选的答案生成、简洁的内容提取和域名筛选功能。

主要功能：

• 根据搜索结果生成 AI 答案摘要
• 结构清晰的结果，针对大模型处理进行优化
• 快速（basic）和全面（advanced）搜索模式
• 域名筛选（包含／排除特定来源）
• 面向新闻的搜索，适用于时事
• 搜索相关视觉内容的图片
• 提取原始内容以进行深入分析

架构

graph TB
    A[User Query] --> B{Search Mode}
    B -->|basic| C[Fast Search<br/>1-2s response]
    B -->|advanced| D[Comprehensive Search<br/>5-10s response]
    
    C --> E[Tavily API]
    D --> E
    
    E --> F{Topic Filter}
    F -->|general| G[Broad Web Search]
    F -->|news| H[News Sources<br/>Last 7 days]
    
    G --> I[Domain Filtering]
    H --> I
    
    I --> J{Include Domains?}
    J -->|yes| K[Filter to Specific Domains]
    J -->|no| L{Exclude Domains?}
    K --> M[Search Results]
    L -->|yes| N[Remove Unwanted Domains]
    L -->|no| M
    N --> M
    
    M --> O{Response Options}
    O --> P[AI Answer<br/>Summary]
    O --> Q[Structured Results<br/>Title, URL, Content, Score]
    O --> R[Images<br/>if requested]
    O --> S[Raw HTML Content<br/>if requested]
    
    P --> T[Return to 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

快速开始

基本搜索

# Simple query with AI answer
scripts/tavily_search.py "What is quantum computing?"

# Multiple results
scripts/tavily_search.py "Python best practices" --max-results 10

高级搜索

# Comprehensive research mode
scripts/tavily_search.py "Climate change solutions" --depth advanced

# News-focused search
scripts/tavily_search.py "AI developments 2026" --topic news

域名筛选

# Search only trusted domains
scripts/tavily_search.py "Python tutorials" \
  --include-domains python.org docs.python.org realpython.com

# Exclude low-quality sources
scripts/tavily_search.py "How to code" \
  --exclude-domains w3schools.com geeksforgeeks.org

搜索图片

# Include relevant images
scripts/tavily_search.py "Eiffel Tower architecture" --images

搜索模式

基本搜索与高级搜索

模式	速度	覆盖范围	使用场景
basic	1-2s	良好	快速查找事实、简单查询
advanced	5-10s	出色	研究、复杂主题、全面分析

决策树：

1. 需要快速查找事实或定义？→ 使用 basic
2. 正在研究复杂主题？→ 使用 advanced
3. 需要多种观点？→ 使用 advanced
4. 查询对时效性有要求？→ 使用 basic

常规搜索与新闻搜索

主题	时间范围	来源	使用场景
general	所有时间	广泛的网络内容	常青内容、教程、文档
news	最近 7 天	新闻网站	时事、最新进展、突发新闻

决策树：

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

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. 研究与事实核查

# Comprehensive research with answer
scripts/tavily_search.py "Explain quantum entanglement" --depth advanced

# Multiple authoritative sources
scripts/tavily_search.py "Best practices for REST API design" \
  --max-results 10 \
  --include-domains github.com microsoft.com google.com

2. 时事

# Latest news
scripts/tavily_search.py "AI policy updates" --topic news

# Recent developments in a field
scripts/tavily_search.py "quantum computing breakthroughs" \
  --topic news \
  --depth advanced

3. 特定领域的研究

# Academic sources only
scripts/tavily_search.py "machine learning algorithms" \
  --include-domains arxiv.org scholar.google.com ieee.org

# Technical documentation
scripts/tavily_search.py "React hooks guide" \
  --include-domains react.dev

4. 视觉研究

# Gather visual references
scripts/tavily_search.py "modern web design trends" \
  --images \
  --max-results 10

5. 内容提取

# Get raw HTML content for deeper analysis
scripts/tavily_search.py "Python async/await" \
  --raw-content \
  --max-results 5

处理响应

AI 答案

AI 生成的答案会综合搜索结果，提供简洁的摘要：

{
  "answer": "Quantum computing is a type of computing that uses quantum-mechanical phenomena..."
}

适用场景：

• 需要快速摘要
• 想要获取综合多个来源的信息
• 想要直接得到问题的答案

以下情况可跳过（--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 限制在实际需要的数量
• 除非确有需要，否则禁用 include_raw_content
• 将结果缓存在本地，以供重复查询使用

4. 优雅地处理错误

脚本会提供实用的错误消息：

# Missing API key
Error: Tavily API key required
Setup: Set TAVILY_API_KEY environment variable or pass --api-key

# Package not installed
Error: tavily-python package not installed
To install: pip install tavily-python

集成模式

编程方式使用

from tavily_search import search

result = search(
    query="What is machine learning?",
    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 tutorials" --json > results.json

与其他工具串联使用

# Search and extract content
scripts/tavily_search.py "React documentation" --json | \
  jq -r '.results[].url' | \
  xargs -I {} curl -s {}

与其他搜索 API 的比较

与 Brave Search 相比：

• ✅ 可生成 AI 回答
• ✅ 可提取原始内容
• ✅ 域名筛选效果更好
• ❌ 速度比 Brave 慢
• ❌ 会消耗额度

与 Perplexity 相比：

• ✅ 对来源的控制更多
• ✅ 可获取原始内容
• ✅ 提供专用新闻模式
• ≈ 回答质量相近
• ≈ 速度相近

与 Google Custom Search 相比：

• ✅ 结果经过大模型优化
• ✅ 可生成回答
• ✅ API 更简单
• ❌ 索引规模更小
• ≈ 费用结构相近

故障排除

脚本无法运行

# Make executable
chmod +x scripts/tavily_search.py

# Check Python version (requires 3.6+)
python3 --version

# Install dependencies
pip install tavily-python

API 密钥问题

# Verify API key format (should start with tvly-)
echo $TAVILY_API_KEY

# Test with explicit 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