# @cloudflare/ai-utils 中文文档

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

版本：1\.0\.1
npm 元数据更新时间：2026-09-03T14:17:44.200Z
中文译文更新时间：2026-11-10T03:22:56.504Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：1.1 MB，19 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：2 个
- 首次发布：2024-06-27T15:41:27.617Z
- 最新版本发布：2024-06-27T16:47:25.240Z
- 近 30 天下载量：7611（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：2（近 12 个月 0 个）

## 中文简介

使用人工智能工具的公用事业

## 安装

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

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

## README

## 方便工人AI平台工作的公用事业.

### 安装

```bash
npm install @cloudflare/ai-utils --save
```

### 这是什么?

这一一揽子计划包含一套公用事业,以方便与工发组织合作 [Cloudflare工人AI平台](https://developers.cloudflare.com/workers-ai/)。 。 。 .

要了解更多关于函数调用及其在Cloudflare上的用法,请参见这里的文件: [Cloudflare 函数调用文档](https://developers.cloudflare.com/workers-ai/function-calling/)。 。 。 .

这一一揽子计划包括下列公用事业:

### `runWithTools`

`runWithTools` 是帮助您用更简单的语法调用函数的辅助函数 `AI.run()`。您可以提供与您想要使用的工具相关的函数,该工具会随着引用AI调用所在的同一工人中传递到函数的参数自动运行.

**使用工具运行的特性**数字 :

-   多工具调用功能
-   \* 递归工具呼叫
-   QQ 处理函数有错误运行
-   流出最后反应
-   回放类型与AI.run相同
-   程序修饰工具,或使用 `autoTrimTools` 自动完成.

它还支持下列配置选项:

-   `strictValidation` - 如果设置为 `true`,如果 LLM 工具的参数无效,则函数会出错。 默认为 `false`。 。 。 .
-   `maxRecursiveToolRuns` - 工具可循环运行的最大次数。 默认为 `1`。 。 。 .
-   `streamFinalResponse` - 如果设置为 `true`,函数将返回 a `ReadableStream` 而不是一个字符串。 默认为 `false`。 。 。 .
-   `verbose` - 如果设置为 `true`,该函数将打印更多关于工具执行的信息。 默认为 `false`。 。 。 .
-   `trimFunction` 这个功能可以用来修剪工具. 它取出所有参数(工具,AI,模型,消息),并可以还原被修剪的工具阵列. 您可以在发送函数调用查询( 通常使用多个符号 ) 之前用它来决定使用哪个工具

我们也提供一种功能 `autoTrimTools`,它需要一个工具阵列,并根据每个工具的名称和描述对其进行修饰.

用法 :

```ts
const r = await runWithTools(
  env.AI,
  "@hf/nousresearch/hermes-2-pro-mistral-7b",
  {
    messages: [{ role: "user", content: "What's the weather in Mumbai, India?" }],
    tools: [
      {
        name: "get-weather",
        description: "Gets weather information of a particular city",
        parameters: {
          type: "object",
          properties: {
            city: {
              type: "string",
              description: "The city name"
            }
          },
          required: ["city"]
        },
        function: async ({ city }) => {
          // fetch weather data from an API
          console.log("value from llm", city)

          return city
        }
      }
    ]
  },
  {
    strictValidation: true,
    maxRecursiveToolRuns: 1,
    streamFinalResponse: true,
    // If there's too many tools, you can enable this
    trimFunction: autoTrimTools
  }
)
```

您也可以使用 `tool()` 函数,它是一个为函数参数和工具提供类型补全的帮助工具,因此可以从外部创建工具 `runWithTools` 函数并仍然享受类型安全.

```ts
import { tool } from "@cloudflare/ai-utils"

const ourTool = tool({
    name: "ourTool"
    ...
    function: async (args) => {...}
})
```

### OpenAPI 到工具转换器

函数 `createToolsFromOpenAPISpec`

这个项目提供了一个功能 `createToolsFromOpenAPISpec` 将 OpenAPI 规格转换成 JSONSchema 格式的一套工具,每个工具都有相关的函数来进行 API 调用。 这可用于基于 OpenAPI 光谱动态生成 API 客户端. 使用此功能,用户可以简单地制作诸如:

-   谷歌日历代理
-   Github 仓库管理器/ 发行跟踪器
-   电子邮件 - > 气表数据库插入器

只要API提供OpenAPI spec,就可以用它来制作代理. 当与 runWithTools 配对时,这提供了惊人的开发者经验,其中智能工作量可以仅用几行代码来完成.

**使用量**

此函数需要一个 OpenAPI spec和一个配置对象并返回一系列工具.

参数;

-   `spec`: OpenAPI 规格. 这可以是JSON或YAML形式. 您也可以提供远程规格, 并且会获取并解析 .
-   `config`数字 :
    -   `matchPatterns`: 一组可匹配的regex图案,如果您不想要整个API,但需要一小部分,则会有帮助.
    -   `overrides` \[:
        -   `matcher`: 匹配器函数,该函数取用 URL 和方法并返回布尔 .
        -   `values`:如果匹配者是真实的,这些值在实际获取请求时会被添加为覆盖值. 这有助于添加用户代理,认证符等. 你可以提供 `headers`, (中文(简体) ), `pathData`, (中文(简体) ), `query`, (中文(简体) ), `formData`, (中文(简体) ), `body` 财务报告和审定财务报表 `cookies` 作为价值.

```typescript
const githubUserTool = await createToolsFromOpenAPISpec(GITHUB_SPEC, {
  matchPatterns: [
    // api.github.com/users/{username} and api.github.com/users/{username}/repos
    /^https:\/\/api\.github\.com\/users\/([^\/]+)\/repos$/,
    /^https:\/\/api\.github\.com\/users\/([^\/]+)$/,
    // Also, for api.github.com/repos/{owner}/{repo}/ queries
    /^https:\/\/api\.github\.com\/repos\/([^\/]+)\/([^\/]+)\/?$/
  ],
  overrides: [
    {
      // for all requests on *.github.com, we'll need to add a User-Agent and Authorization.
      matcher: ({ url, method }) => {
        return url.hostname === "api.github.com"
      },
      values: {
        headers: {
          "User-Agent":
            "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/112.0.0.0 Safari/537.36",
          Authorization: "Bearer GITHUB_TOKEN"
        }
      }
    }
  ]
})
```

### 在工人平台上嵌入函数

当使用时 [云花岗工人](https://workers.cloudflare.com/) 平台,您也可以使用 [约束](https://developers.cloudflare.com/workers/runtime-apis/bindings/) 进行数据库查询和查询,存储和获取图像,旋转浏览器实例,甚至运行AI模型,作为工具的功能.

因为我们使用绑定,大多数计算和外观都发生在同一个执行环境中,这有助于降低延迟,并获得10%-20%的更快的响应时间.

以下是一个代理商的例子,该代理商通过对话自动制作数据库条目,以获得用户的"记忆":

```ts
const r = await runWithTools(env.AI, "@hf/nousresearch/hermes-2-pro-mistral-7b", {
  messages: [
    {
      role: "system",
      content: "Save important information about the user to the KV databse."
    },
    {
      role: "user",
      content: "Hi! I'm dhravya. An engineering intern at Cloudflare."
    }
  ],
  tools: [
    tool({
      name: "Save information",
      description: "Info save about the user",
      parameters: {
        type: "object",
        properties: {
          key: {
            type: "string",
            description: "Name of the user"
          },
          value: {
            type: "string",
            description: "Information of the user"
          }
        },
        required: ["key", "value"]
      },
      function: async ({ key, value }) => {
        await env.KV.put(key, value)
        return `Saved ${key} to the KV database.`
      }
    })
  ]
})
```

### 捐款

该项目是开放的,欢迎捐款。 请将寄存器叉出并提交拉力请求.

### 许可证

该项目根据Apache 2.0许可证颁发许可——见 [自由主义](https://npmcn.com/package/%40cloudflare/ai-utils/LICENSE) 详细文件.

## 常见问题

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

使用人工智能工具的公用事业

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

在项目目录运行 npm install @cloudflare/ai-utils，或使用 pnpm add / yarn add / bun add。

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

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

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

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

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

@cloudflare/ai-utils 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

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

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

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

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