# Vercel AI SDK

> 借助官方 Search1API 工具包，为 AI SDK 智能体提供网页搜索、新闻、网页读取和智能搜索能力。

Canonical URL: https://s1.dev/zh/docs/integrations/vercel-ai-sdk

关于两种 Vercel 集成方式（包括 Vercel Connect），请参阅 [Vercel 指南](https://s1.dev/zh/docs/integrations/vercel)。

`@search1api/ai-sdk` 将 Search1API 作为普通的 AI SDK 工具提供。你可以将它与 `generateText`、`streamText` 或智能体一起使用，并搭配你偏好的模型提供商。一个包即可覆盖 Google、Reddit、GitHub 和 YouTube 等引擎的搜索，外加用于读取搜索结果对应完整页面的 `crawl`，因此智能体无需单独的抓取服务就能完成搜索、阅读和引用。该包通过官方 [TypeScript SDK](https://s1.dev/zh/docs/integrations/sdks) 发起 API 调用。

## 安装与配置

```bash
npm install @search1api/ai-sdk ai zod
```

在[仪表盘](https://app.s1.dev)创建密钥，然后在服务器环境中设置：

```bash
export SEARCH1API_API_KEY="your-api-key"
```

同时也接受兼容别名 `SEARCH1API_KEY`。显式传入的 `apiKey` 优先级更高。请将密钥保存在服务端代码中。

支持 AI SDK 5、6 和 7，需搭配 Zod 3.25.76+ 或 4.1.8+。请使用你的 AI SDK 版本所支持的 Node.js 版本；AI SDK 7 需要 Node.js 22+。

## 搜索、阅读并回答

此示例使用 Vercel AI Gateway，它需要单独的 `AI_GATEWAY_API_KEY`。你可以将模型替换为任何兼容的 AI SDK 提供商。

```ts
import { gateway, generateText, stepCountIs } from 'ai';
import { search1apiTools } from '@search1api/ai-sdk';

const result = await generateText({
  model: gateway('openai/gpt-5-mini'),
  tools: search1apiTools({ only: ['search', 'crawl'] }),
  stopWhen: stepCountIs(5),
  prompt: 'Find the official AI SDK tool calling docs, read them, and explain how tools work. Cite the URLs you used.',
});

console.log(result.text);
```

`stopWhen` 让模型可以在同一次调用中使用搜索结果、读取页面，然后给出回答。完整工具集包含：

| 工具 | 模型输入 | 结果 |
| --- | --- | --- |
| `search` | `query`，可选 `search_service`、`page`、`max_results`、`include_sites`、`exclude_sites`、`time_range` | 标题、链接、摘要以及其他搜索响应字段 |
| `news` | 与 `search` 相同（不含 `page`），使用新闻引擎 | 新闻文章和来源链接 |
| `crawl` | `{ url: string }` | 网页的标题、来源 URL 和可读内容 |
| `ask` | `{ query: string }` | 最多 10 条按相关性排序的结果，以及所用的引擎和时间范围 |

面向模型的参数与 [MCP 服务器](https://s1.dev/zh/docs/integrations/mcp)一致。模型可以选择引擎（`google`、`bing`、`bingcn`、`duckduckgo`、`yahoo`、`yandex`、`x`、`reddit`、`github`、`youtube`、`arxiv`、`wechat`、`bilibili`、`imdb`、`wikipedia`、`grokipedia`；新闻支持 `google`、`bing`、`duckduckgo`、`yahoo` 和 `hackernews`），返回 1–50 条结果，请求后续结果页（仅 `bing`、`bingcn`、`baidu` 和 `grokipedia` 支持分页），限定或排除域名，以及将结果限制在过去一天、一周、一个月或一年内。结果页抓取不向模型开放。未知参数会被忽略，而不会导致调用失败。

每个工具都返回 SDK 的类型化响应。来源 URL 和可选元数据会被保留。空结果保持为空。请让模型引用返回的链接；这些工具不会自动发出 AI SDK 的 source 事件。当回答使用了 `grokipedia` 的结果时，请注明 "Powered by xAI"；详见[提升搜索结果质量](https://s1.dev/zh/docs/guides/improving-search-results)。

## 使用 ask 进行智能搜索

`ask` 将自然语言请求发送到 [`POST /ask`](https://s1.dev/zh/docs/basic/ask)。Search1API 会选择最多五个引擎和一个时间范围，剔除不相关的结果，并返回最多 10 条按相关性排序的结果。与 MCP 服务器的 `ask` 工具一样，它默认包含在 `search1apiTools()` 中。每次调用消耗 5 积分（`search` 为 1 积分），超时时间为 45 秒。

```ts
import { search1apiAsk, search1apiTools } from '@search1api/ai-sdk';

// 之前的三工具集合，不含 ask
const withoutAsk = search1apiTools({ only: ['search', 'news', 'crawl'] });

// 单独使用 ask
const askOnly = { ask: search1apiAsk() };
```

`ask` 不支持按次付费（pay-per-request）支付方式。

## 配置单个工具

```ts
import { search1apiSearch, search1apiNews, search1apiCrawl } from '@search1api/ai-sdk';

const tools = {
  webSearch: search1apiSearch({
    search: { maxResults: 5, includeSites: ['ai-sdk.dev'], timeRange: 'month' },
  }),
  recentNews: search1apiNews({ news: { maxResults: 3, timeRange: 'day' } }),
  readPage: search1apiCrawl({ crawl: { enableFallback: true } }),
};
```

在代码中传入的设置是默认值。当模型提供了相同的参数时，该次调用使用模型的值；模型未提供的参数则回退到你的设置。工具集在 `search`、`news` 和 `crawl` 下接受相同的设置。

search 和 news 默认返回十条结果，且 `crawlResults: 0`。如需在搜索响应中包含页面内容，请显式设置 `search.crawlResults` 或 `news.crawlResults`。每个成功获取的页面单独计费；详见[积分与限制](https://s1.dev/zh/docs/essentials/credits-and-limits)。

## 客户端设置与取消

工厂函数和工具集接受 SDK 的 `apiKey`、`baseUrl`、`fetch`、`headers`、`timeoutMs`、`maxRetries` 和 `retryDelayMs` 设置。你也可以注入一个已有的客户端：

```ts
import { Search1API } from '@search1api/client';

const client = new Search1API({ apiKey: 'your-api-key', timeoutMs: 15_000 });
const tools = search1apiTools({ client });
```

提供了 `client` 时，其他客户端设置会被忽略。否则，工具会在首次执行时创建客户端，因此在 Next.js 构建期间，模块级的工具定义不需要凭证。

向 `generateText` 或 `streamText` 传入 `abortSignal` 即可取消工具请求。SDK 的错误类型、状态码、解析后的错误响应体和请求 ID 都会被保留。重试和超时遵循官方 SDK 的配置。

## Next.js 路由处理器

在服务端使用这些工具，并将 UI 消息流式传输给 `useChat`：

```ts
import { search1apiTools } from '@search1api/ai-sdk';
import { convertToModelMessages, gateway, stepCountIs, streamText } from 'ai';
import type { UIMessage } from 'ai';

const tools = search1apiTools({ only: ['search', 'crawl'] });

export async function POST(request: Request) {
  const { messages }: { messages: UIMessage[] } = await request.json();
  const result = streamText({
    model: gateway('openai/gpt-5-mini'),
    system: 'Search and read relevant pages before answering. Cite the URLs you used.',
    messages: await convertToModelMessages(messages),
    tools,
    stopWhen: stepCountIs(5),
    abortSignal: request.signal,
  });
  return result.toUIMessageStreamResponse();
}
```

[完整的 Next.js 示例](https://github.com/superagents-lab/search1api-ai-sdk/tree/main/examples/nextjs)包含客户端聊天界面，并会渲染工具输出中的链接。

## 源码

[GitHub](https://github.com/superagents-lab/search1api-ai-sdk) ·
[npm](https://www.npmjs.com/package/@search1api/ai-sdk) ·
[AI SDK 工具调用](https://ai-sdk.dev/docs/ai-sdk-core/tools-and-tool-calling)