通用端点

您可以使用通用端点与每个提供商进行交互。

https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}

AI 网关为您创建的每个网关提供多个端点 - 每个提供商一个端点，以及一个通用端点。通用端点需要对您的架构进行一些调整，但支持其他功能。这些功能包括，例如，如果请求首次失败时重试请求，或配置回退模型/提供商。

您可以使用通用端点与每个提供商进行交互。载荷期望一个消息数组，每个消息都是具有以下参数的对象：

• provider：您想要将此消息定向到的提供商名称。可以是 OpenAI、workers-ai 或我们支持的任何提供商。
• endpoint：您尝试访问的提供商 API 的路径名。例如，在 OpenAI 上可以是 chat/completions，对于 Workers AI 可能是 @cf/meta/llama-3.1-8b-instruct。在每个提供商的特定部分中查看更多信息。
• authorization：联系此提供商时应使用的授权 HTTP 标头内容。这通常以 'Token' 或 'Bearer' 开头。
• query：提供商在其官方 API 中期望的载荷。

cURL 示例

Request

curl https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id} \
  --header 'Content-Type: application/json' \
  --data '[
  {
    "provider": "workers-ai",
    "endpoint": "@cf/meta/llama-3.1-8b-instruct",
    "headers": {
      "Authorization": "Bearer {cloudflare_token}",
      "Content-Type": "application/json"
    },
    "query": {
      "messages": [
        {
          "role": "system",
          "content": "You are a friendly assistant"
        },
        {
          "role": "user",
          "content": "What is Cloudflare?"
        }
      ]
    }
  },
  {
    "provider": "openai",
    "endpoint": "chat/completions",
    "headers": {
      "Authorization": "Bearer {open_ai_token}",
      "Content-Type": "application/json"
    },
    "query": {
      "model": "gpt-4o-mini",
      "stream": true,
      "messages": [
        {
          "role": "user",
          "content": "What is Cloudflare?"
        }
      ]
    }
  }
]'

上述请求将发送到 Workers AI 推理 API，如果失败，它将继续发送到 OpenAI。您可以通过在数组中添加另一个 JSON 来添加任意数量的回退。

WebSockets API beta

通用端点还可以通过 WebSockets API 访问，该 API 提供单一持久连接，实现持续通信。此 API 支持连接到 AI 网关的所有 AI 提供商，包括那些本身不支持 WebSockets 的提供商。

WebSockets 示例

import WebSocket from "ws";
const ws = new WebSocket(
  "wss://gateway.ai.cloudflare.com/v1/my-account-id/my-gateway/",
  {
    headers: {
      "cf-aig-authorization": "Bearer AI_GATEWAY_TOKEN",
    },
  },
);

ws.send(
  JSON.stringify({
    type: "universal.create",
    request: {
      eventId: "my-request",
      provider: "workers-ai",
      endpoint: "@cf/meta/llama-3.1-8b-instruct",
      headers: {
        Authorization: "Bearer WORKERS_AI_TOKEN",
        "Content-Type": "application/json",
      },
      query: {
        prompt: "tell me a joke",
      },
    },
  }),
);

ws.on("message", function incoming(message) {
  console.log(message.toString());
});

Workers 绑定示例

wrangler.jsonc

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

wrangler.toml

[ai]
binding = "AI"

src/index.ts

type Env = {
  AI: Ai;
};

export default {
  async fetch(request: Request, env: Env) {
    return env.AI.gateway("my-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",
      },
    });
  },
};

标头配置层次结构

通用端点允许您设置回退模型或提供商，并为每个提供商或请求自定义标头。您可以在三个级别配置标头：

1. 提供商级别：特定于特定提供商的标头。
2. 请求级别：包含在各个请求中的标头。
3. 网关设置：在网关仪表板中配置的默认标头。

由于相同的设置可以在多个位置配置，AI 网关应用层次结构来确定哪个配置优先：

• 提供商级别标头覆盖所有其他配置。
• 请求级别标头在未设置提供商级别标头时使用。
• 网关级别设置仅在提供商或请求级别未配置标头时使用。

此层次结构确保一致的行为，优先考虑最具体的配置。使用提供商级别和请求级别标头进行精细控制，使用网关设置作为通用默认值。

层次结构示例

此示例演示了在不同级别设置的标头如何影响缓存行为：

• 请求级别标头：cf-aig-cache-ttl 设置为 3600 秒，默认情况下将此缓存持续时间应用于请求。
• 提供商级别标头：对于回退提供商（OpenAI），cf-aig-cache-ttl 明确设置为 0 秒，覆盖请求级别标头，并在使用 OpenAI 作为提供商时禁用响应缓存。

这显示了提供商级别标头如何优先于请求级别标头，允许对缓存行为进行精细控制。

curl https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id} \
  --header 'Content-Type: application/json' \
  --header 'cf-aig-cache-ttl: 3600' \
  --data '[
    {
      "provider": "workers-ai",
      "endpoint": "@cf/meta/llama-3.1-8b-instruct",
      "headers": {
        "Authorization": "Bearer {cloudflare_token}",
        "Content-Type": "application/json"
      },
      "query": {
        "messages": [
          {
            "role": "system",
            "content": "You are a friendly assistant"
          },
          {
            "role": "user",
            "content": "What is Cloudflare?"
          }
        ]
      }
    },
    {
      "provider": "openai",
      "endpoint": "chat/completions",
      "headers": {
        "Authorization": "Bearer {open_ai_token}",
        "Content-Type": "application/json",
        "cf-aig-cache-ttl": "0"
      },
      "query": {
        "model": "gpt-4o-mini",
        "stream": true,
        "messages": [
          {
            "role": "user",
            "content": "What is Cloudflare?"
          }
        ]
      }
    }
  ]'