名称： tavily
描述： 使用 Tavily Search API 进行 AI 优化的网络搜索。适用于需要全面网络研究、时事查询、特定领域搜索或 AI 生成答案摘要的场景。Tavily 针对大语言模型消费进行了优化，提供清晰的结构化结果、答案生成和原始内容提取。最适合研究任务、新闻查询、事实核查和收集权威来源。

Tavily AI 搜索

概述

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

核心功能：
- 基于搜索结果生成 AI 答案摘要
- 为 LLM 处理优化的清晰、结构化结果
- 快速（basic）和全面（advanced）两种搜索模式
- 域名过滤（包含/排除特定来源）
- 专注于当前事件的新闻搜索
- 附带相关视觉内容的图片搜索
- 用于深度分析的原始内容提取

架构

graph TB
    A[用户查询] --> B{搜索模式}
    B -->|basic| C[快速搜索<br/>响应时间 1-2 秒]
    B -->|advanced| D[全面搜索<br/>响应时间 5-10 秒]

    C --> E[Tavily API]
    D --> E

    E --> F{主题过滤}
    F -->|general| G[广泛网络搜索]
    F -->|news| 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

搜索模式

基础模式 vs 高级模式

决策树：
1. 需要快速事实或定义？ → 使用 basic
2. 研究复杂主题？ → 使用 advanced
3. 需要多角度信息？ → 使用 advanced
4. 时间敏感查询？ → 使用 basic

通用搜索 vs 新闻搜索

决策树：
1. 查询包含"最新"、"近期"、"当前"、"今天"？ → 使用 news
2. 寻找历史或常青内容？ → 使用 general
3. 需要最新信息？ → 使用 news

API 密钥设置

选项 1：Clawdbot 配置（推荐）

添加到你的 Clawdbot 配置中：

{
  "skills": {
    "entries": {
      "tavily": {
        "enabled": true,
        "apiKey": "tvly-你的_API_密钥_在此"
      }
    }
  }
}

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

选项 2：环境变量

export TAVILY_API_KEY="tvly-你的_API_密钥_在此"

添加到 ~/.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 限制在你实际会使用的数量
• 除非需要，否则禁用 include_raw_content
• 对重复查询在本地缓存结果

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 Search：
- ✅ AI 答案生成
- ✅ 原始内容提取
- ✅ 更好的域名过滤
- ❌ 比 Brave 慢
- ❌ 消耗信用额度

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

对比 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 "测试" --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