Tavily

Tavily 是一款专为大语言模型（LLM）设计的搜索 API，可让 AI 应用程序实时访问网络数据。

前提条件

需要 Tavily API 密钥 —— 请前往 https://app.tavily.com 获取您的密钥（每月提供 1,000 次免费 API 调用额度，无需绑定信用卡）

将以下配置添加到 ~/.claude/settings.json 文件中：

{
  "env": {
    "TAVILY_API_KEY": "tvly-YOUR_API_KEY"
  }
}

添加 API 密钥后，请重启 Claude Code。

安装

Python：

pip install tavily-python

JavaScript：

npm install @tavily/core

完整 SDK 参考文档请参阅 references/sdk.md。

客户端初始化

from tavily import TavilyClient

# 方式 1：使用环境变量 TAVILY_API_KEY（推荐）
client = TavilyClient()

# 方式 2：显式传入 API 密钥
client = TavilyClient(api_key="tvly-YOUR_API_KEY")

# 方式 3：启用项目跟踪（便于用量管理）
client = TavilyClient(api_key="tvly-YOUR_API_KEY", project_id="your-project-id")

# 异步客户端，支持并行查询
from tavily import AsyncTavilyClient
async_client = AsyncTavilyClient()

选择合适的方法

适用于自定义智能体 / 工作流：

适用于开箱即用的研究任务：

快速参考

search() —— 网页搜索

response = client.search(
    query="quantum computing breakthroughs",  # 建议控制在 400 字符以内
    max_results=10,
    search_depth="advanced",  # 消耗 2 个积分，返回最相关结果
    topic="general"  # 或 "news"、"finance"
)

for result in response["results"]:
    print(f"{result['title']}: {result['score']}")

关键参数：query、max_results、search_depth（可选值：ultra-fast / fast / basic / advanced）、topic、include_domains、exclude_domains、time_range

extract() —— URL 内容提取

# 推荐的两步模式（便于精细控制）
search_results = client.search(query="Python async best practices")
urls = [r["url"] for r in search_results["results"] if r["score"] > 0.5]
extracted = client.extract(
    urls=urls[:20],
    query="async patterns",  # 根据相关性对文本块重新排序
    chunks_per_source=3  # 防止上下文爆炸
)

关键参数：urls（最多 20 个）、extract_depth、query、chunks_per_source（取值范围：1–5）

crawl() —— 全站内容提取

response = client.crawl(
    url="https://docs.example.com",
    max_depth=2,
    instructions="Find API documentation pages",  # 语义聚焦指令
    chunks_per_source=3,  # Token 使用优化
    select_paths=["/docs/.*", "/api/.*"]
)

关键参数：url、max_depth、max_breadth、limit、instructions、chunks_per_source、select_paths、exclude_paths

map() —— URL 发现

response = client.map(
    url="https://docs.example.com",
    max_depth=2,
    instructions="Find all API and guide pages"
)
api_docs = [url for url in response["results"] if "/api/" in url]

research() —— AI 驱动的研究

import time

# 用于多主题综合研究
result = client.research(
    input="Analyze competitive landscape for X in SMB market",
    model="pro"  # 或 "mini"（适合聚焦型查询），或 "auto"（不确定时使用）
)
request_id = result["request_id"]

# 轮询直至完成
response = client.get_research(request_id)
while response["status"] not in ["completed", "failed"]:
    time.sleep(10)
    response = client.get_research(request_id)

print(response["content"])  # 研究报告正文

关键参数：input、model（可选值："mini"/"pro"/"auto"）、stream、output_schema、citation_format

详细指南

如需查阅完整的参数说明、响应字段定义、最佳实践模式与示例代码：

• references/sdk.md —— Python 与 JavaScript SDK 参考、异步调用模式、混合 RAG 实现
• references/search.md —— 查询优化技巧、搜索深度选择策略、域名过滤、异步模式、后置过滤
• references/extract.md —— 单步 vs 两步提取、基于 query/chunks 的精准定位、高级模式
• references/crawl.md —— crawl 与 map 的区别、语义聚焦指令编写、典型用例、“先 map 后 extract” 模式
• references/research.md —— 提示词工程最佳实践、模型选型建议、流式响应、结构化输出 Schema
• references/integrations.md —— LangChain、LlamaIndex、CrewAI、Vercel AI SDK 及其他主流框架集成方案