# @genkit-ai/vercel-ai 中文文档

规范地址：https://npmcn.com/package/%40genkit-ai/vercel-ai/

版本：0\.7\.0
npm 元数据更新时间：2026-11-03T20:54:49.773Z
中文译文更新时间：2026-11-16T03:56:08.811Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40genkit-ai/vercel-ai
原文对照：https://npmcn.com/package/%40genkit-ai/vercel-ai/?lang=original
项目主页：https://github.com/genkit-ai/genkit/tree/main/js/plugins/vercel-ai#readme
源码仓库：https://github.com/genkit-ai/genkit

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：198 kB，21 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：0 个
- peer 依赖：ai ^6\.0\.0，genkit ^1\.44\.0，@ai-sdk/react ^3\.0\.0
- 首次发布：2026-06-24T20:02:23.561Z
- 最新版本发布：2026-11-03T20:54:49.602Z
- 近 30 天下载量：2401（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：15（近 12 个月 15 个）

## 中文简介

一个提供 Vercel AI SDK Chat Transport 的 Genkit 插件,用于连接使用 Chat 到 Genkit Agents .

## 安装

```sh
npm install @genkit-ai/vercel-ai
```

也可以使用：`pnpm add @genkit-ai/vercel-ai`、`yarn add @genkit-ai/vercel-ai`、`bun add @genkit-ai/vercel-ai`

## README

# @genkit-ai/vercel-ai (英语)

A 类 [精灵](https://github.com/genkit-ai/genkit) 提供插件 [维塞尔 AI SDK](https://sdk.vercel.ai/) `ChatTransport` 用于连接 `useChat` 给源基特特工.

> **用编码代理? 先安装基因组JS技能.**
> 
> ```bash
> npx skills add genkit-ai/skills --skill developing-genkit-js
> ```
> 
> 它教你的代理人 现任Genkit JS APIs 和普通的gitchas. 其他语言的来源、人工安装和技能: [技能/技能](https://github.com/genkit-ai/skills)。 。 。 .

使用此插件在 React (Next.js, Vite等) 中构建丰富的聊天 UI 源基特代理商的流回,包括多回合对话, 工具调用,以及基于中断的 " 人行 " 流动——零 定制管道.

## 安装

```bash
npm install @genkit-ai/vercel-ai
```

### 同伴依赖关系

| 软件包 | 需求 | 页:1 |
| --- | --- | --- |
| `genkit` | ✅ | `>=1.0.0` - 运输所使用的API剂生活在 `genkit/beta` 子路径. |
| `ai` | ✅ | `^6.0.0` - 提供 `ChatTransport`, (中文(简体) ), `UIMessage`等 (中文(简体) ). |
| `@ai-sdk/react` | 仅限客户 | `^3.0.0` - 只需要你打电话给我 `useChat` 钩 (眉生. |

> **说明:** `@ai-sdk/react` 此软件包不是宣布的对等依赖 因为服务器边入口并不需要它。 安装它 在任何项目中使用 `useChat`。 。 。 .

## 快开始

### 1\. 界定基因组代理人(服务器)

```ts
// app/api/chat/weather/route.ts  (Next.js App Router example)
import { appRoute } from '@genkit-ai/next';
import { genkit } from 'genkit/beta';
import { googleAI } from '@genkit-ai/google-genai';

const ai = genkit({ plugins: [googleAI()] });

const weatherAgent = ai.defineAgent({
  name: 'weatherAgent',
  model: 'googleai/gemini-flash-latest',
  tools: [/* your tools here */],
});

export const POST = appRoute(weatherAgent);
```

或有快报:

```ts
import { expressHandler } from '@genkit-ai/express';
import express from 'express';

const app = express();
app.post('/api/chat/weather', expressHandler(weatherAgent));
app.listen(3000);
```

### 2\. 从客户端连接

```tsx
'use client';
import { useChat } from '@ai-sdk/react';
import { GenkitChatTransport } from '@genkit-ai/vercel-ai/client';
import { useMemo } from 'react';

export default function Chat() {
  const transport = useMemo(
    () => new GenkitChatTransport({ url: '/api/chat/weather' }),
    []
  );
  // The `useChat` `id` is sent to the agent as its `sessionId`; it must be a UUID.
  const chatId = useMemo(() => crypto.randomUUID(), []);

  const { messages, input, handleInputChange, handleSubmit, status } =
    useChat({ id: chatId, transport });


  return (
    <div>
      {messages.map((m) => (
        <div key={m.id}>
          <strong>{m.role}:</strong>{' '}
          {m.parts
            .filter((p) => p.type === 'text')
            .map((p) => p.text)
            .join('')}
        </div>
      ))}
      <form onSubmit={handleSubmit}>
        <input value={input} onChange={handleInputChange} />
        <button type="submit" disabled={status !== 'ready'}>
          Send
        </button>
      </form>
    </div>
  );
}
```

就是这样,文本流,多回转的历史,工具呼叫,和中断 都从盒子里出来.

## 与AI元素有关的工作

这种运输完全兼容 [AI 要素](https://elements.ai-sdk.dev/) - 组成部分图书馆和 自定义 [阴影/ ui](https://ui.shadcn.com/) 建筑物登记簿 应用。 自兹 `GenkitChatTransport` 执行标准 `ChatTransport` 界面,所有 AI 元素组件 (`Conversation`, (中文(简体) ), `Message`, (中文(简体) ), `Tool`, (中文(简体) ), `PromptInput`) 和源基特一起在盒子里工作 探员.

```tsx
'use client';
import { useChat } from '@ai-sdk/react';
import { GenkitChatTransport } from '@genkit-ai/vercel-ai/client';
import { useMemo } from 'react';

import {
  Conversation, ConversationContent, ConversationScrollButton,
} from '@/components/ai-elements/conversation';
import { Message, MessageContent, MessageResponse } from '@/components/ai-elements/message';
import {
  PromptInput, PromptInputTextarea, PromptInputFooter, PromptInputSubmit,
} from '@/components/ai-elements/prompt-input';
import { Tool, ToolHeader, ToolContent, ToolInput, ToolOutput } from '@/components/ai-elements/tool';

export default function Chat() {
  const transport = useMemo(
    () => new GenkitChatTransport({ url: '/api/chat/weather' }),
    []
  );
  // The `useChat` `id` is sent to the agent as its `sessionId`; it must be a UUID.
  const chatId = useMemo(() => crypto.randomUUID(), []);
  const { messages, status, sendMessage } = useChat({ id: chatId, transport });


  return (
    <Conversation>
      <ConversationContent>
        {messages.map((message) => (
          <Message key={message.id} from={message.role}>
            <MessageContent>
              {message.parts.map((part, i) => {
                if (part.type === 'text' && part.text) {
                  return <MessageResponse key={i}>{part.text}</MessageResponse>;
                }
                if (part.type.startsWith('tool-')) {
                  const toolPart = part as any;
                  return (
                    <Tool key={i}>
                      <ToolHeader type={toolPart.type} state={toolPart.state} />
                      <ToolContent>
                        <ToolInput input={toolPart.input} />
                        <ToolOutput output={toolPart.output} />
                      </ToolContent>
                    </Tool>
                  );
                }
                return null;
              })}
            </MessageContent>
          </Message>
        ))}
      </ConversationContent>
      <ConversationScrollButton />
      <PromptInput onSubmit={(msg) => sendMessage({ text: msg.text })}>
        <PromptInputTextarea placeholder="Message..." />
        <PromptInputFooter>
          <div />
          <PromptInputSubmit status={status} />
        </PromptInputFooter>
      </PromptInput>
    </Conversation>
  );
}
```

参看以下文件的完整实例: [`js/testapps/vercel-ai-elements`](https://npmcn.com/package/testapps/vercel-ai-elements) 哪个 演示多代理选择、工具调用渲染和中断 人-入-入-入-入-入-入-入-出-出-出-出-出-出-出-出-出-出-出-出-出-出-出-出-出-出-出-出-出-出-出-出-出-出-出-出-出-出-出-出-出-出-出-出-出-出:出-出-出-出-出-出-出-出-出:出:出:出:出-出:出:出:出:出:出:出:出-出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出.

## 入境点

| 导入路径 | 环境 | 目录 |
| --- | --- | --- |
| `@genkit-ai/vercel-ai` | 服务器/ 共享 | 测绘公用事业(`mapUIMessageToGenkit`, (中文(简体) ), `mapUIPartToGenkit`)和再出口 `UIMessage` 类型 |
| `@genkit-ai/vercel-ai/client` | 浏览器/ 客户端 | `GenkitChatTransport` 类 |

这个 `/client` 入站点为浏览器安全并具有Node.js的依赖性.

## API 密码

### `GenkitChatTransport`

```ts
import { GenkitChatTransport } from '@genkit-ai/vercel-ai/client';

const transport = new GenkitChatTransport({
  url: '/api/chat/weather',
  headers: { Authorization: 'Bearer token' },         // static headers
  // headers: () => ({ Authorization: `Bearer ${getToken()}` }),  // or dynamic
});
```

#### 配置

| 选项 | 类型 | 说明 |
| --- | --- | --- |
| `url` | `string` | **要求.** 源基特代理端点的 URL. |
| `headers` | `Record<string, string> | () => Record<string, string>` | 在每个请求中包含可选的 HTTP 信头 。 接受一个静态对象或动态值的函数(如认证符). |

> **这个 `useChat` `id` 必须是裸体UUID.** 传送器发送聊天 `id` 以特务身份 `sessionId`,并且代理服务器需要 会话 ID 要裸露 UUID 。 生成一个 `crypto.randomUUID()` 财务报告和审定财务报表 传过来 `useChat({ id })`。如果省略 `id`,AI SDK生成一个 非UUID ID, 传输会返回一个错误.

```tsx
import { useMemo } from 'react';

const chatId = useMemo(() => crypto.randomUUID(), []);
const { messages, sendMessage } = useChat({ id: chatId, transport });
```

#### 服务器管理的会话状态

对话状态是 **完全服务器管理**。传输发送聊天 `id` 作为代理人 `sessionId`,并且该代理人在 它的配置 `SessionStore`自动恢复会话 最近的情况——有 **没有客户端快照簿记** 管理或 持续,在页面重新装入(服务器持有状态)时不会丢失任何内容 .

要继续现有的对话,只需重新使用同样的UUID `id`。 。 。 .

#### 重新装入后恢复对话

因为状态是服务器管理的,恢复 _下一个_ 转身不需要更多了 而不是重用同一个UUID `id`客户端必须重建的唯一东西就是 _已执行_ 信件列表( e)`useChat` 拥有这些,他们不是坚持的 运输.

使用 `messagesFromSnapshot` 以重建来自 Genkit 的可见信件 `SessionSnapshot` (通过一个 `/state` 由相同键入的流 `sessionId`:

```tsx
import { useChat } from '@ai-sdk/react';
import { GenkitChatTransport } from '@genkit-ai/vercel-ai/client';
import { messagesFromSnapshot } from '@genkit-ai/vercel-ai';
import { runFlow } from 'genkit/beta/client';
import { useEffect, useMemo, useState } from 'react';

export default function RestoredChat({ sessionId }: { sessionId: string }) {
  const transport = useMemo(() => new GenkitChatTransport({ url: '/api/chat/weather' }), []);
  const [initialMessages, setInitialMessages] = useState([]);

  useEffect(() => {
    (async () => {
      // Load the latest snapshot for this session (returns a SessionSnapshot).
      const snapshot = await runFlow({ url: '/api/chat/weather/state', input: sessionId });
      // Rebuild the visible message list from the snapshot.
      setInitialMessages(messagesFromSnapshot(snapshot.state.messages));
    })();
  }, [sessionId]);

  // Reuse the same UUID `id` so the next turn resumes the server-side session.
  const { messages, sendMessage } = useChat({ id: sessionId, transport, messages: initialMessages });
  // ...render messages, send new turns — continuity is preserved.
}
```

`messagesFromSnapshot` 合并 Genkit 的单独工具请求/ 工具响应 消息输入单个的 AI SDK 工具部件( 所以每个工具调用都变成一个) 元素),地图 `reasoning` 财务报告和审定财务报表 `media` 部分,保留部分 `metadata`,以及 发出任何未解决的工具请求(例如待决中断) `input-available` 说好UI还能解决.

> **提示 :** 页:1 `sessionId` 装入快照时必须是相同的UUID 通过为 `useChat` `id`,所以已发送的消息和服务器侧 会话保持同步 .

#### 重新生成响应

当UI触发再生时(AI SDK发送) `trigger: 'regenerate-message'`),运输重运行最后一个用户消息 作为 **新转弯** 相对于当前服务器侧会话状态。 这个 生成对同一提示的新答案。 因为状态是由服务器管理的 `sessionId`,没有客户端快照指针可以倒转到 与任何其他回合一样,重新生成的回合附在届会后.

#### 如何运作

1.  **发送信件** 通过源基特 `streamFlow` 客户端 — 一个浏览器安全 HTTP pOST 到代理端点并读取 NDJSON 流线的客户端 反应.
2.  **变换** 元吉的书 `AgentStreamChunk` 事件进入 Vercel AI SDK `UIMessageChunk` 活动(`text-delta`, (中文(简体) ), `tool-input-available`, (中文(简体) ), `tool-output-available`(见a/c.5/49/70,附件).
3.  **发送会话 ID** - 运输通行证 `init: { sessionId: chatId }` 并恢复 每个回合的会话最新快照。 没有客户端快照跟踪 需要帮助.
4.  **处理中断** ——当代理人暂停人输入时(通过 `defineInterrupt`),运输会浮出等待的工具呼叫UI. 接下来 `sendMessages` 调用已解析的工具结果 直接从消息历史中发送,传输自动发送 `resume` 有效载荷而非新消息 .

### 间断( 人- 在- 在- 在- 有)

精灵特工可以 **暂停** 中途通过 `defineInterrupt` (或呼叫的工具) `interrupt()`) (中文(简体) ). 当这种情况发生时, 显示已暂停的工具调用 `useChat` 作为工具在 页:1 `input-available` 状态。 解决这个问题有两种方法:

1.  **响应** ——直接提供工具的输出(人类的决定) _实值_ (结果)。 这才是 `defineInterrupt` 工具预期.
2.  **重新开始** - 要求经纪人 **重新运行** 工具服务器侧,可选 附加元数据。 用于工具 `interrupt()` 直到确认和 然后在恢复时计算一个实际结果 `resumed` 参数已设置).

两者都由AI SDK的原生HITL原始人所驱动—— `addToolResult` 加号 `sendAutomaticallyWhen` - 所以没有手动 `setMessages`编号 :`flushSync` 需要:

```tsx
import { useChat } from '@ai-sdk/react';
import {
  GenkitChatTransport,
  restartInterrupt,
} from '@genkit-ai/vercel-ai/client';
import { lastAssistantMessageIsCompleteWithToolCalls } from 'ai';

const { messages, addToolResult } = useChat({
  transport: new GenkitChatTransport({ url: '/api/chat/banking' }),
  // Auto-resume once every paused tool call has a result.
  sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithToolCalls,
});

// 1. Respond: provide the tool output (resume.respond).
addToolResult({
  tool: 'userApproval',
  toolCallId,
  output: { approved: true, feedback: 'Looks good' },
});

// 2. Restart: re-run the tool (resume.restart). The metadata becomes the
//    tool's `resumed` argument server-side.
addToolResult({
  tool: 'getExchangeRate',
  toolCallId,
  output: restartInterrupt({ confirmedAt: Date.now() }),
});
```

> **说明:** Genkit打断了 AI SDK的地图 `addToolResult` 流动, **没有** 那个工具.._核准_ 流动(`needsApproval` 编号 : `addToolApprovalResponse`A级 Genkit 中断从不执行服务器侧面 —— 您通过的价值 改为 `addToolResult` _实值_ 决议 使用 `restartInterrupt()` 当你 想要代理重新运行工具, 而不是接受所提供的输出 .

参看以下文件的完整实例: [`js/testapps/vercel-ai-elements`](https://npmcn.com/package/testapps/vercel-ai-elements),哪个 证明两项批准(`userApproval`)并重新启动(`getExchangeRate`(中文(简体) ) 流动.

### 测绘公用事业

根入点( E)`@genkit-ai/vercel-ai`) 出口绘图功能 在 Vercel AI SDK 之间 `UIMessage` 类型和基因组 `MessageData`附加时 运输所使用的辅助函数 :

| 函数 | 方向 | 说明 |
| --- | --- | --- |
| `mapUIMessageToGenkit(msg)` | UI – 源基特语Name | 转换 Vercel `UIMessage` 给基因组 `MessageData` |
| `mapUIPartToGenkit(part)` | UI – 源基特语Name | 转换单个 `UIMessagePart` 给源基特 `Part[]` |
| `messagesFromSnapshot(msgs)` | Genkit – UI (英语) | 转换 a `SessionSnapshot`是因为 `state.messages` 输入 `UIMessage[]` 用于再水 `useChat` (传真工具请求/答复,保存元数据) |
| `mapGenkitMessageToUI(msg)` | Genkit – UI (英语) | 转换单个源基特 `MessageData` 改为 a `UIMessage` |
| `extractResolvedToolResults(msgs)` | —— 说 | 从信件数组提取已解析的工具引用结果 |
| `findLastUserMessage(msgs)` | —— 说 | 在 a 中查找最后一个用户消息 `UIMessage[]` |

工具/部分元数据双向保存: `mapUIPartToGenkit` 带UI部分 `metadata` 进入基因组部分,以及 `messagesFromSnapshot` 带了玄基的 `metadata` 回到UI部分.

这个 `UIMessage` 类型也从 `ai` 为方便而包装.

## 特征

-   **文本流** – 串流符号逐个输入的文本三角洲到 UI
    
-   **多回合对话** 自动服务器管理的会话连续性按键 `useChat` `id` (单位:千美元)`sessionId`(中文(简体) )
    
-   **工具调用** ——当工具投入和产出出现时表面
    
-   **间断( 人- 在- 在- 在- 有)** ——头等舱支援 `defineInterrupt` 工具; 通过用户输入暂停并恢复流量
    
-   **自定义信头** ——用于认证的静态或动态信头
    
-   **浏览器安全** - 那个 `/client` 切入点没有节点.js依赖性
    
-   **零配置** 没有 `ChatSessionStore` 客户端需要
    

## 所需资源

-   精灵 `>=1.0.0` - 代理人API(`defineAgent`, (中文(简体) ), `streamFlow`用于此 运输通过 `genkit/beta` 主子路径 `1.x` 软件包.
-   维塞尔 AI SDK `>=6.0.0` (计: `useChat` 与 `ChatTransport`(中文(简体) )
-   `@ai-sdk/react` `>=3.0.0` (客户方,用于 `useChat` 钩子)
-   节点.js `>=20` (服务器侧)

## 许可证

阿帕奇-2.0 — 见 [自由主义](https://npmcn.com/package/%40genkit-ai/vercel-ai/LICENSE)。 。 。 .

## 常见问题

### @genkit-ai/vercel-ai 是什么？

一个提供 Vercel AI SDK Chat Transport 的 Genkit 插件,用于连接使用 Chat 到 Genkit Agents \.

### 如何安装 @genkit-ai/vercel-ai？

在项目目录运行 npm install @genkit-ai/vercel-ai，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：ai（^6\.0\.0）、genkit（^1\.44\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @genkit-ai/vercel-ai 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @genkit-ai/vercel-ai 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @genkit-ai/vercel-ai 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @genkit-ai/vercel-ai 可以商用吗？

@genkit-ai/vercel-ai 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @genkit-ai/vercel-ai 的下载量有多少？

根据 npm 官方下载统计，@genkit-ai/vercel-ai 在 2026/10/16 – 2026/11/14 这 30 天内被下载 2,401 次，日均约 80 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @genkit-ai/vercel-ai 还在维护吗？

最新版本 0\.7\.0 发布于 2026/11/04（12 天前）；至今共发布 15 个版本，其中过去 12 个月发布了 15 个；首次发布于 2026/06/25。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

