Tavily AI Search

# Tavily AI Search

## 概述

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

**核心功能：** - 基于搜索结果生成的 AI 摘要答案 - 针对 LLM 处理优化的干净、结构化结果 - 快速（`basic`）和全面（`advanced`）搜索模式 - 域名过滤（包含/排除特定来源） - 针对时事新闻的搜索 - 包含相关视觉内容的图片搜索 - 用于深度分析的原始内容提取

## 架构

```mermaid 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 ```

## 快速开始

### 基础搜索

```bash # 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 ```

### 高级搜索

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

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

### 域名过滤

```bash # 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 ```

### 包含图片

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

## 搜索模式

### 基础 vs 高级

| 模式 | 速度 | 覆盖面 | 适用场景 | |------|-------|----------|----------| | **basic** | 1-2秒 | 良好 | 快速事实、简单查询 | | **advanced** | 5-10秒 | 优秀 | 研究、复杂主题、综合分析 |

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

### 通用 vs 新闻

| 主题 | 时间范围 | 来源 | 适用场景 | |-------|------------|---------|----------| | **general** | 所有时间 | 广泛的网络 | 常青内容、教程、文档 | | **news** | 过去 7 天 | 新闻网站 | 当前事件、近期进展、突发新闻 |

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

## API 密钥设置

### 选项 1：Clawdbot 配置（推荐）

添加到你的 Clawdbot 配置中：

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

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

### 选项 2：环境变量

```bash export TAVILY_API_KEY="tvly-YOUR_API_KEY_HERE" ```

添加到 `~/.clawdbot/.env` 或你的 Shell 配置文件中。

### 获取 API 密钥

1. 访问 https://tavily.com 2. 注册账户 3. 进入你的仪表盘 4. 生成 API 密钥（以 `tvly-` 开头） 5. 注意你计划的速率限制和配额分配

## 常见用例

### 1. 研究与事实核查

```bash # 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. 当前事件

```bash # 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. 特定域名研究

```bash # 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. 视觉研究

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

### 5. 内容提取

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

## 响应处理

### AI 答案

AI 生成的答案提供了从搜索结果综合得出的简洁摘要：

```python { "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. 优雅地处理错误

该脚本提供有用的错误消息：

```bash # 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 ```

## 集成模式

### 编程式使用

```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 输出

```bash scripts/tavily_search.py "Python tutorials" --json > results.json ```

### 与其他工具链式调用

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

## 与其他搜索 API 的比较

**vs Brave Search：** - ✅ AI 答案生成 - ✅ 原始内容提取 - ✅ 更好的域名过滤 - ❌ 比 Brave 慢 - ❌ 消耗配额

**vs Perplexity：** - ✅ 对来源有更多控制 - ✅ 可用原始内容 - ✅ 专用新闻模式 - ≈ 答案质量相似 - ≈ 速度相似

**vs Google Custom Search：** - ✅ LLM 优化的结果 - ✅ 答案生成 - ✅ 更简单的 API - ❌ 索引较小 - ≈ 成本结构相似

## 故障排除

### 脚本无法运行

```bash # Make executable chmod +x scripts/tavily_search.py

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

# Install dependencies pip install tavily-python ```

### API 密钥问题

```bash # 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](references/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