AI 网关绑定方法

本指南概述了如何使用最新的 Cloudflare Workers AI 网关绑定方法。您将学习如何设置 AI 网关绑定、访问新方法以及将它们集成到您的 Worker 中。

1. 将 AI 绑定添加到您的 Worker

要将您的 Worker 连接到 Workers AI，请将以下内容添加到您的 Wrangler 配置文件中：

wrangler.jsonc

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

wrangler.toml

[ai]
binding = "AI"

此配置设置了可在您的 Worker 代码中作为 env.AI 访问的 AI 绑定。

If you're using TypeScript, run wrangler types whenever you modify your Wrangler configuration file. This generates types for the env object based on your bindings, as well as runtime types.

2. Workers AI + 网关的基本用法

要使用 Workers AI 和 AI 网关执行推理任务，您可以使用以下代码：

src/index.ts

const resp = await env.AI.run(
  "@cf/meta/llama-3.1-8b-instruct",
  {
    prompt: "tell me a joke",
  },
  {
    gateway: {
      id: "my-gateway",
    },
  },
);

此外，您可以使用以下代码访问最新的请求日志 ID：

const myLogId = env.AI.aiGatewayLogId;

3. 访问网关绑定

您可以使用以下代码访问您的 AI 网关绑定：

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

一旦您有了网关实例，您就可以使用以下方法：

3.1. patchLog：发送反馈

patchLog 方法允许您为特定的日志 ID 发送反馈、评分和元数据。所有对象属性都是可选的，因此您可以包含任何参数组合：

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

• 返回：Promise<void>（确保 await 请求。）
• 用例示例：使用用户反馈或附加元数据更新日志条目。

3.2. getLog：读取日志详情

getLog 方法检索特定日志 ID 的详细信息。它返回一个 Promise<AiGatewayLog> 类型的对象。如果此类型缺失，请确保您已运行 wrangler types。

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

• 返回：Promise<AiGatewayLog>
• 用例示例：检索日志信息以进行调试或分析。

3.3. getUrl：获取网关 URL

getUrl 方法允许您检索 AI 网关的基本 URL，可选择指定一个提供商以获取特定于提供商的端点。

// 获取基本网关 URL
const baseUrl = await gateway.getUrl();
// 输出: https://gateway.ai.cloudflare.com/v1/my-account-id/my-gateway/

// 获取特定于提供商的 URL
const openaiUrl = await gateway.getUrl("openai");
// 输出: https://gateway.ai.cloudflare.com/v1/my-account-id/my-gateway/openai

• 参数：可选的 provider（字符串或 AIGatewayProviders 枚举）
• 返回：Promise<string>
• 用例示例：动态构建用于直接 API 调用或调试配置的 URL。

SDK 集成示例

getUrl 方法对于与流行的 AI SDK 集成特别有用：

OpenAI SDK：

import OpenAI from "openai";

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

Vercel AI SDK 与 OpenAI：

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

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

Vercel AI SDK 与 Anthropic：

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

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

3.4. run：通用请求

run 方法允许您执行通用请求。用户可以传递单个通用请求对象或其数组。此方法支持所有 AI 网关提供商。

有关可用输入的详细信息，请参阅通用端点文档。

const resp = await gateway.run({
  provider: "workers-ai",
  endpoint: "@cf/meta/llama-3.1-8b-instruct",
  headers: {
    authorization: "Bearer my-api-token",
  },
  query: {
    prompt: "tell me a joke",
  },
});

• 返回：Promise<Response>
• 用例示例：向任何支持的提供商执行通用请求。

结论

通过这些 AI 网关绑定方法，您现在可以：

• 使用 patchLog 发送反馈和更新元数据。
• 使用 getLog 检索详细的日志信息。
• 使用 getUrl 获取用于直接 API 访问的网关 URL，从而轻松与流行的 AI SDK 集成。
• 使用 run 执行到任何 AI 网关提供商的通用请求。

这些方法为您的 AI 集成提供了更大的灵活性和控制力，使您能够在 Cloudflare Workers 平台上构建更复杂的应用程序。