# @convex-dev/ai-sdk-provider 中文文档

规范地址：https://npmcn.com/package/%40convex-dev/ai-sdk-provider/

版本：0\.3\.0
npm 元数据更新时间：2026-10-09T17:01:14.325Z
中文译文更新时间：2026-11-10T17:48:34.417Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40convex-dev/ai-sdk-provider
原文对照：https://npmcn.com/package/%40convex-dev/ai-sdk-provider/?lang=original
源码仓库：https://github.com/get-convex/convex-backend

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

- 包体积（解压后）：164 kB，50 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：4 个
- peer 依赖：ai ^7\.0\.105，convex ^1\.45\.0
- 首次发布：2026-08-19T23:38:41.143Z
- 最新版本发布：2026-10-09T17:01:14.080Z
- 近 30 天下载量：177731（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：7（近 12 个月 7 个）

## 中文简介

Convex AI网关的 AI SDK 提供者

## 安装

```sh
npm install @convex-dev/ai-sdk-provider
```

也可以使用：`pnpm add @convex-dev/ai-sdk-provider`、`yarn add @convex-dev/ai-sdk-provider`、`bun add @convex-dev/ai-sdk-provider`

## README

# `@convex-dev/ai-sdk-provider`

使用 Convex AI 网关与 AI SDK 从 Convex 动作.

```ts
"use node";

import { convexGateway } from "@convex-dev/ai-sdk-provider";
import { embedMany, generateText } from "ai";
import { action } from "./_generated/server";
import { v } from "convex/values";

export const chat = action({
  args: { prompt: v.string() },
  handler: async (_ctx, { prompt }) => {
    const { text } = await generateText({
      model: convexGateway("anthropic/claude-sonnet-4.5"),
      prompt,
    });
    return text;
  },
});

export const embed = action({
  args: { values: v.array(v.string()) },
  handler: async (_ctx, { values }) => {
    const { embeddings } = await embedMany({
      model: convexGateway.embeddingModel("openai/text-embedding-3-small"),
      values,
    });
    return embeddings;
  },
});
```

嵌入的批量大于网关的512输入限制被拆分成 aI SDK多次请求.

## 可选 ZDR 路由

过 `{ zdr: true }` 来使用带有零数据保留的推断端点 政策:

```ts
const { text } = await generateText({
  model: convexGateway("openai/gpt-4o-mini", { zdr: true }),
  prompt: "Summarize this document",
});
```

也得到下列各方的支持: `messages`, (中文(简体) ), `responses`, (中文(简体) ), `embeddingModel`,以及 `evaluationModel`。设置适用于模型实例并覆盖 `provider.zdr` 从其他 SDK 选项。 允许它使用默认政策; `false` 无法禁用更严格的网关政策.

并不是每个模型都有ZDR终点. 见 [路线要求和保留限额](https://docs.convex.dev/ai-gateway/api#provider-preferences)。 。 。 .

## 选择模式界面

对于文本生成, 首先 `convexGateway(model)`。它可以跨模式工作 提供者和推荐的默认值。 只使用特定端点的模型 当您需要 Anthropic 信件或 OpenAI 响应独有的特性时:

```ts
convexGateway.messages("anthropic/claude-sonnet-4.5");
convexGateway.responses("openai/gpt-5");
```

## 结构化决定

使用提供者版本0.2.1 或以后用于正确验证 Jev 四舍五入 分数和概率.

[杰维](https://docs.typesafe.ai/introduction) 评价 `choice`, (中文(简体) ), `score`,以及 `boolean` 关于贵国提供的背景 `state`给AI SDK打电话 实验 `evaluate` 从动作中跳出 :

```ts
import { experimental_evaluate as evaluate } from "ai";
import { convexGateway } from "@convex-dev/ai-sdk-provider";

const decision = await evaluate({
  model: convexGateway.evaluationModel("typesafe/jev-1.13"),
  state: { ticket: "Customer cannot sign in" },
  questions: {
    priority: {
      type: "choice",
      instructions: "Choose the response priority",
      criteria: {
        urgent: "Respond now",
        normal: "Respond today",
      },
    },
    needsReview: {
      type: "boolean",
      instructions: "Does a human need to review this?",
    },
  },
});

console.log(decision.answers.priority.choice);
console.log(decision.answers.needsReview.probability);
```

这需要AI SDK 7.0.105 或以后. 评价接口 `/alpha/decisions` 终点是实验性的。 认证处理 自动。 过 `abortSignal` 改为 `evaluate` 取消请求。 美元费用 可在 `decision.providerMetadata?.convexGateway?.cost`原样 网关响应,包括供应商特有的领域,例如 `confidence`,为 备查 `decision.response.body`。 。 。 .

`getServiceToken("ai-gateway")` 提供短寿命部署JWT. 这个 动作运行时间缓存并按需要刷新证书,所以 `convexGateway` 每一个要求都要求它.

要求Convex 1.45或更晚和AI SDK 7.0.105或更晚. 供应商在 默认运行时间和 Node.js 动作中,需要 Node.js 22 或以后.

## 生成图像

图像生成在α. 请求和答复格式可能改变.

```ts
import { generateImage } from "ai";
import { convexGateway } from "@convex-dev/ai-sdk-provider";

const { images } = await generateImage({
  model: convexGateway.imageModel("openai/gpt-image-1"),
  prompt: "A mountain lake at sunrise",
});
```

图像请求费用可在 `result.calls`时 `providerMetadata?.convexGateway?.cost`以美元计。 每次通话都会产生 多个图像;成本是呼叫,而不是每个图像.

## 转写和生成语音

语音对正文和文本对正文为α.

```ts
import {
  experimental_generateSpeech as generateSpeech,
  experimental_transcribe as transcribe,
} from "ai";
import { convexGateway } from "@convex-dev/ai-sdk-provider";

const { text, providerMetadata } = await transcribe({
  model: convexGateway.transcriptionModel("openai/whisper-large-v3-turbo"),
  audio: recordingBytes,
});
const cost = providerMetadata.convexGateway?.cost;

const { audio } = await generateSpeech({
  model: convexGateway.speechModel("hexgrad/kokoro-82m"),
  text: "Your order has shipped.",
  voice: "af_heart",
});
```

演讲结果没有 `cost` 内 `providerMetadata`,因为成本是已知的 只有在音频发送之后。 Convex仍然为演讲开具账单. 指控出现 convex的用法页面.

## 生成视频

视频生成在α. API可能会改变, 完成回调最好 努力起来。 保存 Async 操作处理以检查状态并获取结果 .

```ts
import { experimental_generateVideo as generateVideo } from "ai";
import { convexGateway } from "@convex-dev/ai-sdk-provider";

const { video, providerMetadata } = await generateVideo({
  model: convexGateway.videoModel("google/veo-3.1"),
  prompt: "A camera pan across a mountain lake",
  duration: 8,
  aspectRatio: "16:9",
  resolution: "1280x720",
});

const bytes = video.uint8Array;
const cost = providerMetadata?.convexGateway?.cost;
```

呼叫等待生成和下载,每段视频有64个米B限制. 这个 如果生成时间超过5分钟,则失败; 使用同步视频用于 更长时间的工作。 在 Convex 文件存储中存储返回的字节 。 AI SDK 拆分 `n > 1` 以单独请求方式进行。 取消请求不会取消 上游工作,还可以收费.

提示中的图像成为了第一个框架. 使用 `frameImages` 明确 帧, `inputReferences` 图像/音频/视频参考,以及 `generateAudio` 用于音频. `fps` 返回不支持的选项警告.

`providerOptions.convexGateway` 接受 `resolution` (例如: `720p`, (中文(简体) ), `generate_audio`, (中文(简体) ), `frame_images`,以及 `input_references`. 标准SDK选项 优先发言。 支持的值取决于 [OpenRouter 模型](https://openrouter.ai/docs/guides/overview/multimodal/video-generation)。 。 。 .

## 同步视频

用AI SDK 7.0.105或以后,使用 `experimental_startVideo` 提交工作 不等待视频。 见 [同步可用性要求](https://docs.convex.dev/ai-gateway/images-and-videos#async-videos) 在使用这些路线之前.

先创建应用程序任务 。 使用它的ID作为 `requestId` 在召回 URL 中 这样,接收器就可以找到工作 和它保存的秘密.

```ts
import { experimental_startVideo as startVideo } from "ai";
import { convexGateway } from "@convex-dev/ai-sdk-provider";

async function startJob(requestId: string) {
  const modelId = "google/veo-3.1";
  const started = await startVideo({
    model: convexGateway.videoModel(modelId),
    prompt: "A camera pan across a mountain lake",
    duration: 8,
    webhookUrl: `${process.env.CONVEX_SITE_URL}/video-complete?requestId=${requestId}`,
    maxRetries: 0,
  });

  return {
    modelId,
    operation: started.operation,
    inferenceId: started.providerMetadata?.convexGateway?.inferenceId,
    webhookSecret: started.providerMetadata?.convexGateway?.webhookSecret,
  };
}
```

在动作返回前将返回的工作保存在私有应用程序存储中 . 自动提交重试被禁用, 因为丢失的响应仍然意味着 接受有偿工作。 回调 URL 必须使用部署的 HTTPS `<deployment>.convex.site` 源; 拒绝重定向。 若为 `CONVEX_SITE_URL` 使用自定义域, 使用部署默认值 `convex.site` 来源 以实例代替.

### 接收回调

在更新应用程序前装入保存的工作并验证原始请求正文 状态 :

```ts
import { verifyVideoWebhook } from "@convex-dev/ai-sdk-provider";

const event = await verifyVideoWebhook({
  body: await request.text(),
  signature: request.headers.get("x-convex-video-signature"),
  secret: savedJob.webhookSecret,
});

if (event.id !== savedJob.inferenceId) {
  return new Response("Wrong job", { status: 400 });
}
```

重复 `(event.id, event.status)` 在同一变异中保存 活动。 对于 `completed`,安排下载视频的动作。 记录 `failed`, (中文(简体) ), `cancelled`,或 `expired` 作为终端故障。 204号之后返回 保存事件; 如果任务没有保密, 返回非-2xx 响应 保存至今.

### 获取视频

在以后的动作中,使用所保存的操作检查状态并下载:

```ts
const model = convexGateway.videoModel(savedJob.modelId);
const status = await model.getStatus({ operation: savedJob.operation });

if (status.status === "completed") {
  const result = await model.download({ operation: savedJob.operation });
  const video = result.videos[0];
  const cost = result.providerMetadata?.convexGateway?.cost;
}
```

`getStatus` 返回时 `pending`, (中文(简体) ), `completed`,或 `error`当状态是 `error`,则 `error` 字段包含错误消息。 存储已下载 视频在应用程序存储中,因为每个 `download` 打电话再拿一次. 业务在7天后到期;上游视频保存时间可能更短.

奥米 `webhookUrl` 仅使用状态检查。 如果一个完成回调是 丢失, 请使用保存的操作检查任务并获取结果 . 需要自动回收的应用程序可以定期检查未完成 任务.

## 常见问题

### @convex-dev/ai-sdk-provider 是什么？

Convex AI网关的 AI SDK 提供者

### 如何安装 @convex-dev/ai-sdk-provider？

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

### @convex-dev/ai-sdk-provider 支持 TypeScript 吗？

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

### @convex-dev/ai-sdk-provider 支持 ESM 还是 CommonJS？

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

### @convex-dev/ai-sdk-provider 需要什么版本的 Node\.js？

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

### @convex-dev/ai-sdk-provider 可以商用吗？

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

### @convex-dev/ai-sdk-provider 的下载量有多少？

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

### @convex-dev/ai-sdk-provider 还在维护吗？

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