---
name: deepseek-search
description: "用 DeepSeek 官方 Search / Fetch API 联网搜索和抓取网页。用户要\"搜一下\"、\"查最新资讯\"、\"联网搜索\"、需要实时网页信息回答问题,或给出 URL 要读取网页正文时使用。Search 按关键词返回结构化结果(支持 site:/lang:/after:/before: 语法),Fetch 把单个网页转成 Markdown。"
---

# DeepSeek Search / Fetch

文档: https://api-docs.deepseek.com/zh-cn/guides/search/

## API Key

从环境变量 `DEEPSEEK_API_KEY` 读取。没有设置时先停下,告诉用户:

1. 到 DeepSeek 开放平台 https://platform.deepseek.com/api_keys 创建 API Key(账户需有余额)
2. 写进 shell 配置,如 `echo 'export DEEPSEEK_API_KEY=sk-xxx' >> ~/.zshrc`,重开终端

## Search:关键词搜索

```bash
curl -s https://api.deepseek.com/v1/tools/search \
  -H "Authorization: Bearer $DEEPSEEK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "DeepSeek V4 发布", "count": 5}' \
| jq -r '.error // (.results[] | "## \(.title)\n\(.url)  \(.date // "")  score=\(.rerank_score)\n\(.summary)\n")'
```

| 字段 | 必填 | 说明 |
|---|---|---|
| query | 是 | 搜索词,1~128 字符,支持下方语法 |
| count | 否 | 返回条数 1~50,默认 10(不影响价格) |
| ori_question | 否 | 用户原始问题,1~128 字符,帮助理解意图 |
| need_content | 否 | 是否返回网页正文 `content`,默认 false;一般 `summary` 就够 |
| localization | 否 | IP 地址,优先返回本地化结果 |

搜索语法(可组合):

- `site:github.com OR site:huggingface.co` 限定站点;`-site:x.com` 排除站点
- `-关键词` / `-"短语"` 排除;`"精确短语"` 精确匹配
- `lang:zh,en` 限定语言;`after:2025-01-01` / `before:2026` 限定发布时间

`results[]` 每项: `title`、`url`、`snippet`(短摘要)、`summary`(长摘要 600~800 字,给模型读)、`content`(正文)、`date`(RFC3339 或 null)、`rerank_score`(0~3,≥1.5 为优质)、`authority`(0~4,≥3 极权威,-1 未知)、`site_name`。

## Fetch:抓取网页为 Markdown

```bash
curl -s https://api.deepseek.com/v1/tools/fetch \
  -H "Authorization: Bearer $DEEPSEEK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/article"}' \
| jq -r '.error // "# \(.title)\n\n\(.content)"'
```

- 只有 `url` 一个字段: HTTP/HTTPS、含 host、≤8192 字符、不能带用户名密码
- 返回 `title` 和 `content`(Markdown);正文很长时先存到文件再按需读,避免撑爆上下文

## 用法建议

- 回答时效性问题:先 Search 看 `summary`,不够再对最相关的 1~3 条 Fetch 全文,回答里附上来源链接
- 不确定时间的问题加 `after:` 限定,避免拿到旧闻

## 错误与计费

- 错误为 OpenAI 兼容格式 `.error.message`:401 key 无效,402 余额不足,403 Fetch 被安全策略拒绝,404 Fetch 取不到可用内容(换别的抓取方式)
- 408 / 429 / 5xx 稍后重试;其它 4xx 改了请求再试
- 账号级 QPS:Search、Fetch 各 5,Fetch 另有目标域名限速
- 按次计费,各 5 元 / 千次成功请求;失败、无结果不计费