Search 还是 Extract：两个端点怎么选

WebSearch V1 只提供两个写端点：/api/search 和 /api/extract。边界划得很清楚——Search 负责发现，Extract 负责深读。但什么时候用哪个、参数怎么给，值得展开讲。

决策路径

有明确 URL 吗？
├─ 有 → 直接 Extract，跳过 Search
└─ 没有 → 先 Search
         ├─ 摘要够用 → 到此为止
         └─ 需要全文 → 对 top 结果再 Extract

最常见的浪费是：Search 返回的摘要已经够回答问题，却又对每个 URL 做了一遍 Extract。先看 content 字段够不够用，再决定要不要深挖。

Search：控制成本的两个旋钮

search_depth 是最大的成本开关：

• basic（1 积分）— 只要标题、URL、摘要。大多数问答场景够了。
• advanced（2 积分）— 额外抓取每条结果的正文。适合需要直接引用原文的场景。

max_results 默认 5，上限 20。结果越多，advanced 模式下抓正文越慢。经验值：先 5 条，不够再加。

域名过滤用 include_domains / exclude_domains，provider 支持的话会直接下发，比事后自己过滤省一轮调用：

{
  "query": "retrieval augmented generation",
  "search_depth": "basic",
  "max_results": 5,
  "include_domains": ["arxiv.org"]
}

Extract：按成功计费，失败免费

Extract 一次最多 20 个 URL，每 5 个成功 URL 计 1 积分（advanced 计 2）。抓不动的页面进 failed_results，不收费——所以放心批量给。

{
  "urls": ["https://example.com/a", "https://example.com/b"],
  "extract_depth": "basic",
  "format": "markdown"
}

• format: "markdown"（默认）保留标题和列表结构，适合进模型上下文；"text" 是纯文本，适合做 embedding。
• advanced 会保留表格、延长超时，对付重 JS 的页面。先用 basic，失败率高了再升级。

一个完整的 Agent 循环

# 1. 发现
curl -X POST $BASE/api/search \
  -H "Authorization: Bearer $KEY" \
  -d '{"query": "人工智能最新进展", "max_results": 3}'

# 2. 深读 top 结果
curl -X POST $BASE/api/extract \
  -H "Authorization: Bearer $KEY" \
  -d '{"urls": ["https://tags.news.sina.com.cn/人工智能"]}'

# 3. 查账
curl $BASE/api/usage -H "Authorization: Bearer $KEY"

三步下来，本次任务花了 2 积分：1 次 basic search + 1 次单 URL extract。在 Usage 页面能看到逐端点的汇总。