# @cloudflare/ai-gateway 中文文档

规范地址：https://npmcn.com/package/%40cloudflare/ai-gateway/

版本：0\.0\.6
npm 元数据更新时间：2026-09-03T14:17:49.305Z
中文译文更新时间：2026-11-10T03:46:40.558Z
软件包许可：未声明

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40cloudflare/ai-gateway
原文对照：https://npmcn.com/package/%40cloudflare/ai-gateway/?lang=original
项目主页：https://cloudflare.com/

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：134 kB，33 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：3 个
- peer 依赖：@cloudflare/workers-types \*
- 首次发布：2025-07-03T16:33:34.571Z
- 最新版本发布：2025-12-10T08:37:36.950Z
- 近 30 天下载量：3704（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：10（近 12 个月 8 个）

## 中文简介

Cloudflare AI 网关的 SDK

## 安装

```sh
npm install @cloudflare/ai-gateway
```

也可以使用：`pnpm add @cloudflare/ai-gateway`、`yarn add @cloudflare/ai-gateway`、`bun add @cloudflare/ai-gateway`

## README

# AI 网关 SDK

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

* * *

## 目录

-   [特征](https://npmcn.com/package/%40cloudflare/ai-gateway/#readme-features)
-   [安装](https://npmcn.com/package/%40cloudflare/ai-gateway/#readme-installation)
-   [开始](https://npmcn.com/package/%40cloudflare/ai-gateway/#readme-getting-started)
-   [API 参考](https://npmcn.com/package/%40cloudflare/ai-gateway/#readme-api-reference)

* * *

## 特征

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

* * *

## 安装

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

## 开始

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

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

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

### 基本用途

生成一次性文本补全 :

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

### 简化答复

获得部分结果时:

```ts
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计划

```ts
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);
```

### 结构化输出

将流与计划验证相结合:

```ts
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);
});
```

### 自定义工具

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

```ts
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 网关客户端 .

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

| 财产 | 类型 | 说明 |
| --- | --- | --- |
| `gatewayName` | `string` | 您唯一的网关标识符 . |
| `accountId` | `string` | 你的账号. |
| `apiKey` | `string` | 一个带有AI Gateway的CF符号运行范围. |

* * *

### `gateway.generateText(options: GenerateTextOptions)`

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

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

| 选项 | 类型 | 说明 |
| --- | --- | --- |
| `modelName` | `string` | 供应商/型号的标识符(例如:. `"openai/gpt-4.1"`, (中文(简体) ), `"google-ai-studio/gemini-…"`(中文(简体) ) |
| `userPrompt` | `string` | 文本提示或用户查询 . |
| `schema?` | `ZodSchema<T>` | 可选的Zod schema来验证和打入JSON响应. |
| `stream?` | `boolean` | 若为 `true`,返回文本块或字段承诺的可同步. |
| `tools?` | `ReturnType<typeof createTool>[]` | 用于模型引用的函数调用工具矩阵 . |
| `metadata?` | `Record<string, any>` | 提供方特有的元数据(如区域旗帜). |

**回返情况:**

-   **文本**数字 :
    
    ```ts
    { output: string | AsyncIterable<string> }
    ```
    
-   **结构化输出**数字 :
    
    ```ts
    { output: T | { [K in keyof T]: Promise<T[K]> } }
    ```
    

* * *

### `createTool(config: ToolConfig)`

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

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

| 财产 | 类型 | 说明 |
| --- | --- | --- |
| `name` | `string` | 独特的工具标识符 . |
| `description` | `string` | 人可读取的模型描述. |
| `parameters` | `ZodSchema<object>` | Zod schema 定义工具的输入参数 . |
| `function` | `(args) => Promise<any>` | 接收经验证的投入并返回结果的执行. |

## 常见问题

### @cloudflare/ai-gateway 是什么？

Cloudflare AI 网关的 SDK

### 如何安装 @cloudflare/ai-gateway？

在项目目录运行 npm install @cloudflare/ai-gateway，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@cloudflare/workers-types（\*）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @cloudflare/ai-gateway 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @cloudflare/ai-gateway 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @cloudflare/ai-gateway 可以商用吗？

@cloudflare/ai-gateway 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @cloudflare/ai-gateway 的下载量有多少？

根据 npm 官方下载统计，@cloudflare/ai-gateway 在 2026/10/10 – 2026/11/08 这 30 天内被下载 3,704 次，日均约 123 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @cloudflare/ai-gateway 还在维护吗？

最新版本 0\.0\.6 发布于 2025/12/10（10 个月前）；至今共发布 10 个版本，其中过去 12 个月发布了 8 个；首次发布于 2025/07/04。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。