Workers 绑定

AI 绑定（env.AI）允许你直接从 Worker 调用 AI 模型并访问 AI Gateway 功能。

有关分步设置指南，请参阅使用 AI Gateway 设置 Workers AI。

配置

{
	"ai": {
		"binding": "AI",
	},
}

[ai]
binding = "AI"

绑定在 Worker 代码中可通过 env.AI 访问。

如果你使用 TypeScript，每当你修改 Wrangler 配置文件时，请运行 wrangler types。这将根据你的绑定生成 env 对象的类型，以及运行时类型。

`env.AI.run()`

通过 AI Gateway 运行推理请求。接受 Workers AI 模型（@cf/ 前缀）和第三方模型（{author}/{model} 格式）。

Workers AI 模型：

const resp = await env.AI.run(
	"@cf/moonshotai/kimi-k2.5",
	{
		prompt: "tell me a joke",
	},
	{
		gateway: {
			id: "default", // or use a specific gateway name
		},
	},
);

const resp = await env.AI.run(
	"@cf/moonshotai/kimi-k2.5",
	{
		prompt: "tell me a joke",
	},
	{
		gateway: {
			id: "default", // or use a specific gateway name
		},
	},
);

第三方模型：

const resp = await env.AI.run(
	"openai/gpt-4.1-mini",
	{
		messages: [{ role: "user", content: "tell me a joke" }],
	},
	{
		gateway: {
			id: "default", // or use a specific gateway name
		},
	},
);

const resp = await env.AI.run(
	"openai/gpt-4.1-mini",
	{
		messages: [{ role: "user", content: "tell me a joke" }],
	},
	{
		gateway: {
			id: "default", // or use a specific gateway name
		},
	},
);

第三方模型需要 AI Gateway，并使用 Unified Billing。Cloudflare 管理提供商凭据并从你的账户扣除积分。你无需提供自己的 API 密钥。

在模型目录中浏览可用模型。

Gateway 选项

env.AI.run() 的第三个参数接受具有以下参数的 gateway 对象：

参数	类型	默认值	说明
`id`	`string`	required	AI Gateway的名称。必须与 Worker 在同一账户中。使用 `"default"` 在首次经过身份验证的请求时自动创建 gateway。有关详情，请参阅默认 gateway。
`skipCache`	`boolean`	`false`	对此请求跳过缓存。
`cacheTtl`	`number`	—	缓存 TTL（秒）。
`cacheKey`	`string`	—	此请求的自定义缓存键。
`collectLog`	`boolean`	—	是否为此请求收集日志。
`metadata`	`object`	—	附加到日志条目的自定义元数据。

`env.AI.aiGatewayLogId`

返回最近一次 env.AI.run() 请求的 log ID。

const myLogId = env.AI.aiGatewayLogId;

`env.AI.gateway()`

返回 gateway 实例，用于直接访问 AI Gateway 方法。

const gateway = env.AI.gateway("my-gateway");

gateway 实例公开以下方法。

`patchLog()`

为特定日志条目发送反馈、分数和元数据。第二个参数中的所有属性都是可选的。

await gateway.patchLog("my-log-id", {
	feedback: 1,
	score: 100,
	metadata: {
		user: "123",
	},
});

Returns: Promise<void>

`getLog()`

检索特定日志条目的详情。如果缺少 AiGatewayLog 类型，请运行 wrangler types。

const log = await gateway.getLog("my-log-id");

Returns: Promise<AiGatewayLog>

`getUrl()`

返回 AI Gateway 的基础 URL。传递可选的提供商名称以获取提供商专用端点。

const baseUrl = await gateway.getUrl();
// https://gateway.ai.cloudflare.com/v1/my-account-id/my-gateway/

const openaiUrl = await gateway.getUrl("openai");
// https://gateway.ai.cloudflare.com/v1/my-account-id/my-gateway/openai

Parameters: 可选 provider（string 或 AIGatewayProviders 枚举）

Returns: Promise<string>

SDK 集成示例

OpenAI SDK：

import OpenAI from "openai";

const openai = new OpenAI({
	apiKey: "my api key", // defaults to process.env["OPENAI_API_KEY"]
	baseURL: await env.AI.gateway("my-gateway").getUrl("openai"),
});

Vercel AI SDK with OpenAI：

import { createOpenAI } from "@ai-sdk/openai";

const openai = createOpenAI({
	baseURL: await env.AI.gateway("my-gateway").getUrl("openai"),
});

Vercel AI SDK with Anthropic：

import { createAnthropic } from "@ai-sdk/anthropic";

const anthropic = createAnthropic({
	baseURL: await env.AI.gateway("my-gateway").getUrl("anthropic"),
});