> ## Documentation Index
> Fetch the complete documentation index at: https://docs.olostep.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Olostep + Vercel AI SDK 集成

> 使用现成的 Olostep 工具为 AI SDK 代理提供实时网页搜索、抓取、爬取和引用答案

Olostep AI SDK 集成为使用 [Vercel AI SDK](https://ai-sdk.dev) 构建的代理提供了现成的实时网页数据工具。Olostep 是一个网页搜索、抓取和爬取 API：一个用于搜索、提取和结构化网页数据的 API。将工具传递给 `generateText` 或 `streamText`，模型会决定何时进行搜索、抓取或爬取。

[从 npm 安装 →](https://www.npmjs.com/package/@olostep/ai-sdk)

## 功能

该包提供了 6 种工具：

> **抓取**
>
> 抓取任何 URL 并返回干净的 markdown，支持 JavaScript 渲染

> **搜索**
>
> 搜索实时网页并返回标题、URL 和描述

> **回答**
>
> 从实时网页回答问题，并提供来源 URL

> **映射**
>
> 列出网站上的 URL，可选择按查询进行排名

> **爬取**
>
> 从起始 URL 爬取网站并返回每个页面的 markdown

> **批处理**
>
> 批量抓取 URL 列表并返回每个页面的 markdown

## 安装

```bash npm theme={null}
npm install @olostep/ai-sdk ai zod
```

```bash yarn theme={null}
yarn add @olostep/ai-sdk ai zod
```

```bash pnpm theme={null}
pnpm add @olostep/ai-sdk ai zod
```

适用于 AI SDK 5、6 和 7，Zod 3.25+ 或 4，以及 Node.js 18+。

## 设置

将你的 Olostep API 密钥设置为环境变量：

```bash theme={null}
export OLOSTEP_API_KEY=your-api-key-here
```

或在你的 `.env` 文件中：

```
OLOSTEP_API_KEY=your-api-key-here
```

从 [Olostep Dashboard](https://www.olostep.com/dashboard) 获取你的 API 密钥。

## 快速开始

使用 `olostepTools()` 将所有 Olostep 工具传递给模型：

```typescript theme={null}
import { generateText, stepCountIs } from 'ai';
import { olostepTools } from '@olostep/ai-sdk';

const { text } = await generateText({
  model: 'openai/gpt-5-mini',
  tools: olostepTools(),
  stopWhen: stepCountIs(5),
  prompt: '阅读 Next.js 15 版本说明并列出重大变化，附来源。',
});

console.log(text);
```

`stopWhen` 允许模型在多个步骤中调用工具，例如先搜索然后抓取最佳结果。模型字符串使用 [Vercel AI Gateway](https://vercel.com/docs/ai-gateway)。你也可以传递任何 AI SDK 提供者模型，例如来自 `@ai-sdk/openai` 的 `openai('gpt-5-mini')`。

### 选择单个工具

只给模型所需的工具：

```typescript theme={null}
import { olostepScrape, olostepSearch } from '@olostep/ai-sdk';

const tools = {
  scrape: olostepScrape(),
  search: olostepSearch(),
};
```

## 可用工具

以下工具名称是 `olostepTools()` 使用的键。

### scrape

`olostepScrape()`。抓取单个 URL 并以 markdown 格式返回其内容。

**输入：**

**url** `string` *required*

要抓取的页面 URL

**waitBeforeScraping** `number`

等待 JavaScript 密集型页面渲染的毫秒数（0 到 10000）

**返回：** `{ url, markdown }`

### search

`olostepSearch()`。搜索实时网页。

**输入：**

**query** `string` *required*

搜索查询

**limit** `number` (default: 10)

最大结果数（1 到 20）

**返回：** `{ query, results: [{ title, url, description }] }`

### answer

`olostepAnswer()`。搜索并阅读实时网页以回答问题，并提供来源。

**输入：**

**task** `string` *required*

问题或研究任务

**返回：** `{ answer, sources }`

### map

`olostepMap()`。发现网站上的 URL。

**输入：**

**url** `string` *required*

要映射的网站

**searchQuery** `string`

按与此查询的相关性对 URL 进行排名

**topN** `number`

要返回的最大 URL 数（1 到 500）

**返回：** `{ url, urls }`

### crawl

`olostepCrawl()`。从起始 URL 爬取网站并返回每个页面的 markdown。工具在返回之前等待爬取完成。

**输入：**

**url** `string` *required*

开始爬取的 URL

**maxPages** `number` (default: 5)

最大爬取页面数（1 到 25）

**includeUrls** `array`

仅爬取匹配这些 glob 模式的 URL，例如 `["/docs/**"]`

**返回：** `{ url, pages: [{ url, markdown }] }`

### batch

`olostepBatch()`。批量抓取 URL 列表并返回每个页面的 markdown。工具在返回之前等待批处理完成。

**输入：**

**urls** `array` *required*

要抓取的 URL（1 到 20）

**返回：** `{ pages: [{ url, markdown }] }`

> [!NOTE]
>
> 爬取和批处理工具每次调用限制为 25 页和 20 个 URL，以保持工具结果足够小以适应模型。对于更大的任务，请直接使用 [Node.js SDK](https://docs.olostep.com/sdks/node-js.md) 调用 [Crawls](https://docs.olostep.com/features/crawls.md) 和 [Batches](https://docs.olostep.com/features/batches.md) API。

## 选项

每个工具和 `olostepTools()` 接受相同的选项：

```typescript theme={null}
olostepTools({
  apiKey: 'olostep_...',   // 默认为 process.env.OLOSTEP_API_KEY
  maxCharacters: 20_000,   // 每页返回给模型的最大页面内容
  timeoutSeconds: 300,     // 爬取和批处理工具等待任务完成的时间
});
```

**apiKey** `string`

Olostep API 密钥。默认为 `OLOSTEP_API_KEY` 环境变量。

**maxCharacters** `number` (default: 20000)

每页返回给模型的最大字符数。较长的页面会被截断。

**timeoutSeconds** `number` (default: 300)

爬取和批处理工具等待任务完成的时间，以秒为单位。

## 流式示例

在 Next.js 路由处理器中使用相同的工具与 `streamText`：

```typescript app/api/chat/route.ts theme={null}
import { convertToModelMessages, streamText, stepCountIs, type UIMessage } from 'ai';
import { olostepTools } from '@olostep/ai-sdk';

export async function POST(req: Request) {
  const { messages }: { messages: UIMessage[] } = await req.json();

  const result = streamText({
    model: 'openai/gpt-5-mini',
    system: '你是一个研究助手。使用网络工具并引用你的来源。',
    messages: await convertToModelMessages(messages),
    tools: olostepTools(),
    stopWhen: stepCountIs(5),
  });

  return result.toUIMessageStreamResponse();
}
```

## 常见用例

> **研究助手**
>
> 1. 模型使用 `search` 或 `answer` 找到来源
> 2. 使用 `scrape` 阅读最相关的页面
> 3. 返回带有来源 URL 的摘要

> **文档感知编码代理**
>
> 1. 模型使用 `map` 和 `searchQuery` 找到正确的文档页面
> 2. 使用 `batch` 或 `crawl` 阅读它们
> 3. 根据当前 API 编写代码而不是猜测

> **竞争对手和价格监控**
>
> 1. 定时任务调用 `generateText` 与 `scrape` 和 `batch`
> 2. 模型从每个页面提取价格或变化
> 3. 你的代码将它们与上次运行进行比较并发送警报

## 最佳实践

> **只传递你需要的工具**
>
> 每个工具的描述都会发送给模型。工具越少，token 越少，错误工具选择也越少。对于只读取页面的聊天，`scrape` 和 `search` 通常就足够了。

> **设置步骤限制**
>
> 始终设置 `stopWhen`（例如 `stepCountIs(5)`），以便模型可以链式调用工具，但不能无限循环。

> **为长页面降低 maxCharacters**
>
> 页面内容是 token 账单的最大部分。如果你爬取或批处理许多页面，请降低 `maxCharacters` 以便所有结果都能适应模型的上下文窗口。

> **为大型爬取提高 timeoutSeconds**
>
> 爬取和批处理工具等待任务完成。如果遇到超时，请提高 `timeoutSeconds`，或降低 `maxPages`。

## 故障排除

> **认证失败**
>
> **错误**："无效的 API 密钥"
>
> **解决方案**：
>
> * 在 [dashboard](https://www.olostep.com/dashboard) 中检查你的 API 密钥
> * 确保 `OLOSTEP_API_KEY` 在你的代码运行位置设置（例如在你的 Vercel 项目的环境变量中）
> * 或直接通过 `olostepTools({ apiKey })` 传递密钥

> **模型未调用工具**
>
> **解决方案**：
>
> * 设置 `stopWhen`，否则生成将在第一步后停止
> * 使用支持工具调用的模型
> * 在提示或系统消息中提到网络，例如 "使用网络工具并引用你的来源"

> **爬取或批处理超时**
>
> **解决方案**：
>
> * 提高 `timeoutSeconds`
> * 降低 `maxPages` 或传递更少的 URL
> * 在无服务器函数上，确保函数自身的时间限制长于 `timeoutSeconds`

> **上下文长度超出**
>
> **解决方案**：
>
> * 降低 `maxCharacters`
> * 使用 `map` 和 `searchQuery` 在阅读之前选择更少、更相关的页面

## 价格

Olostep 根据 API 使用情况收费，与 AI SDK 无关：

* **抓取**：按抓取收费
* **搜索和回答**：按请求收费
* **批处理**：按批处理中的 URL 收费
* **爬取**：按爬取的页面收费
* **映射**：按映射操作收费

查看当前价格在 [olostep.com/pricing](https://www.olostep.com/pricing)。

## 支持

> **[GitHub](https://github.com/olostep-api/olostep-ai-sdk)**
>
> 源代码和问题

> **[支持邮箱](mailto:info@olostep.com)**
>
> 邮箱：[info@olostep.com](mailto:info@olostep.com)

> **[AI SDK 文档](https://ai-sdk.dev/docs)**
>
> 了解 Vercel AI SDK

> **[文档](https://docs.olostep.com)**
>
> 浏览完整的 API 文档

## 相关资源

> **[抓取 API](https://docs.olostep.com/features/scrapes.md)**
>
> 了解抓取端点

> **[爬取 API](https://docs.olostep.com/features/crawls.md)**
>
> 了解爬取端点

> **[Mastra 集成](https://docs.olostep.com/integrations/mastra.md)**
>
> 使用 Mastra 构建代理

> **[LangChain 集成](https://docs.olostep.com/integrations/langchain.md)**
>
> 使用 LangChain 构建 AI 代理


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.