@convex-dev/ai-sdk-provider
使用 Convex AI 网关与 AI SDK 从 Convex 动作.
"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 } 来使用带有零数据保留的推断端点
政策:
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终点. 见 路线要求和保留限额。 。 。 .
选择模式界面
对于文本生成, 首先 convexGateway(model)。它可以跨模式工作
提供者和推荐的默认值。 只使用特定端点的模型
当您需要 Anthropic 信件或 OpenAI 响应独有的特性时:
convexGateway.messages("anthropic/claude-sonnet-4.5");
convexGateway.responses("openai/gpt-5");
结构化决定
使用提供者版本0.2.1 或以后用于正确验证 Jev 四舍五入 分数和概率.
杰维 评价 choice, (中文(简体) ), score,以及
boolean 关于贵国提供的背景 state给AI SDK打电话
实验 evaluate 从动作中跳出 :
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 或以后.
生成图像
图像生成在α. 请求和答复格式可能改变.
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以美元计。 每次通话都会产生
多个图像;成本是呼叫,而不是每个图像.
转写和生成语音
语音对正文和文本对正文为α.
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 操作处理以检查状态并获取结果 .
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 模型。 。 。 .
同步视频
用AI SDK 7.0.105或以后,使用 experimental_startVideo 提交工作
不等待视频。 见
同步可用性要求
在使用这些路线之前.
先创建应用程序任务 。 使用它的ID作为 requestId 在召回 URL 中
这样,接收器就可以找到工作 和它保存的秘密.
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 来源
以实例代替.
接收回调
在更新应用程序前装入保存的工作并验证原始请求正文 状态 :
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 响应
保存至今.
获取视频
在以后的动作中,使用所保存的操作检查状态并下载:
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 仅使用状态检查。 如果一个完成回调是
丢失, 请使用保存的操作检查任务并获取结果 .
需要自动回收的应用程序可以定期检查未完成
任务.