Non-realtime WebSockets API（非实时 WebSockets API）

Non-realtime WebSockets API 允许你建立持久连接以发送 AI 请求，无需重复握手。这种方法适用于不需要实时交互但仍受益于降低延迟和持续通信的应用。

设置 WebSockets API

生成具有适当 AI Gateway Run 权限的 AI Gateway 令牌，并选择使用已认证的 gateway。

使用 wss:// 协议发起 WebSocket 连接：

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

打开使用具有 AI Gateway Run 权限的 Cloudflare 令牌进行身份验证的 WebSocket 连接。

示例请求

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.on("open", () => {
	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", (message) => {
	console.log(message.toString());
});

示例响应

{
	"type": "universal.created",
	"metadata": {
		"cacheStatus": "MISS",
		"eventId": "my-request",
		"logId": "01JC3R94FRD97JBCBX3S0ZAXKW",
		"step": "0",
		"contentType": "application/json"
	},
	"response": {
		"result": {
			"response": "Why was the math book sad? Because it had too many problems. Would you like to hear another one?"
		},
		"success": true,
		"errors": [],
		"messages": []
	}
}

示例流式请求

对于流式请求，AI Gateway 发送一条带有请求元数据的初始消息，指示流正在开始：

{
	"type": "universal.created",
	"metadata": {
		"cacheStatus": "MISS",
		"eventId": "my-request",
		"logId": "01JC40RB3NGBE5XFRZGBN07572",
		"step": "0",
		"contentType": "text/event-stream"
	}
}

在此初始消息之后，所有流式块在从推理提供商到达时实时中继到 WebSocket 连接。这些流式块的元数据中仅包含 eventId 字段。eventId 允许 AI Gateway 在流式 WebSocket 环境中为每条消息包含客户端定义的 ID。

{
	"type": "universal.stream",
	"metadata": {
		"eventId": "my-request"
	},
	"response": {
		"response": "would"
	}
}

当请求的所有块都已流式传输完成后，AI Gateway 发送最终消息以表示请求完成。为了灵活性，此消息再次包含所有元数据，尽管这些元数据最初在流式传输过程开始时已提供。

{
	"type": "universal.done",
	"metadata": {
		"cacheStatus": "MISS",
		"eventId": "my-request",
		"logId": "01JC40RB3NGBE5XFRZGBN07572",
		"step": "0",
		"contentType": "text/event-stream"
	}
}