AI 网关 SDK

一个轻量级TypeScript SDK到Cloudflare的AI Gateway,用于统一访问多个AI供应商(OpenAI,Google AI Studio等).
支持文本生成(带有可选流),结构化输出通过Zod,以及自定义工具集成.

目录

• 特征
• 安装
• 开始
• API 参考

特征

• 多重提供者 支持:OpenAI,谷歌AI Studio等.
• 流线 低纬度消费的答复.
• 结构化产出 使用 佐德语Name。 。 。 .
• 自定义工具 对外部数据/行动的整合(功能调用).

安装

npm install @cloudflare/ai-gateway
# or
yarn add @cloudflare/ai-gateway

开始

以您的账户细节和 API 密钥证明 AIGateway :

import { AIGateway } from "@cloudflare/ai-gateway";

const gateway = new AIGateway({
  gatewayName: "<YOUR_GATEWAY_NAME>",
  accountId: "<YOUR_ACCOUNT_ID>",
  apiKey: "<YOUR_AIG_CF_TOKEN>"
});

基本用途

生成一次性文本补全 :

const { output } = await gateway.generateText({
  modelName: "openai/gpt-4.1",
  userPrompt: "Hello, how are you?",
  metadata: {
    eu: true,
  },
});
console.log("Output:", output);

简化答复

获得部分结果时:

const { output } = await gateway.generateText({
  modelName: "google-ai-studio/gemini-2.5-flash-preview-04-17",
  userPrompt:
    "Write a 500 word essay on the importance of AI in modern society.",
  stream: true,
});

for await (const chunk of output) {
  console.log("Chunk:", chunk);
}

结构化输出( Zod)

执行JSON计划

import z from "zod";

const { output } = await gateway.generateText({
  modelName: "openai/gpt-4.1",
  schema: z.object({
    answer: z.string(),
  }),
  userPrompt: "Hello, how are you?",
});

// `output.answer` is guaranteed to be a string by Zod
console.log("Answer:", output.answer);

结构化输出

将流与计划验证相结合:

const { output } = await gateway.generateText({
  modelName: "openai/gpt-4.1",
  schema: z.object({
    answer: z.string(),
    details: z.object({
      length: z.number(),
      language: z.string(),
    }),
  }),
  stream: true,
  userPrompt:
    "Hello, how are you? What is the length of your response and what language is it in?",
});

output.details.length.then((length) => {
  console.log("Length:", length);
});
output.details.language.then((language) => {
  console.log("Language:", language);
});
output.answer.then((answer) => {
  console.log("Answer:", answer);
});

自定义工具

定义和登记模型可称为的外部“工具”(功能):

import { createTool } from "@cloudflare/ai-gateway";
import z from "zod"; //v3

const weatherTool = createTool({
  name: "getWeather",
  description: "Get the current weather for a given city",
  parameters: z.object({
    city: z.string().describe("The city to fetch weather for"),
  }),
  function: async ({ city }) => {
    // Your implementation here (API call, database lookup, etc.)
    return { city, temperature: 22, condition: "Sunny" };
  },
});

const { output } = await gateway.generateText({
  modelName: "google-ai-studio/gemini-2.5-flash-preview-04-17",
  tools: [weatherTool],
  userPrompt: "Hello, what is the weather in Bangalore?",
});

console.log("Weather:", output);

限制

流线

• SDK 运行的假设是,内容总是在工具块或工具块之前流出,如果其中任何一个块交织在一起,那么前一流块就会被丢出

API 参考

new AIGateway(config: GatewayConfig)

创建新的 AI 网关客户端 .

new AIGateway({
  gatewayName: string,
  accountId: string,
  apiKey: string,
});

gateway.generateText(options: GenerateTextOptions)

生成文本( 可选流出或系统验证) .

gateway.generateText({
  modelName: string,
  userPrompt: string,
  schema?: ZodSchema<T>,
  stream?: boolean,
  tools?: ReturnType<typeof createTool>[],
  metadata?: Record<string, any>,
}): Promise<GenerateTextResult<T>>

回返情况:

• 文本数字 :

  { output: string | AsyncIterable<string> }
  

• 结构化输出数字 :

  { output: T | { [K in keyof T]: Promise<T[K]> } }
  

createTool(config: ToolConfig)

定义自定义函数调用工具 .

createTool({
  name: string,
  description: string,
  parameters: ZodSchema<object>,
  function: (args: any) => Promise<any>,
});