# @convex-dev/action-cache 中文文档

规范地址：https://npmcn.com/package/%40convex-dev/action-cache/

版本：0\.3\.1
npm 元数据更新时间：2026-10-07T00:51:34.995Z
中文译文更新时间：2026-11-10T17:46:14.980Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40convex-dev/action-cache
原文对照：https://npmcn.com/package/%40convex-dev/action-cache/?lang=original
项目主页：https://github.com/get-convex/action-cache#readme
源码仓库：https://github.com/get-convex/action-cache

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

- 包体积（解压后）：105 kB，56 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：convex ^1\.24\.8
- 首次发布：2024-10-17T04:48:49.642Z
- 最新版本发布：2026-07-07T04:41:53.661Z
- 近 30 天下载量：428270（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：22（近 12 个月 2 个）

## 中文简介

用于计算昂贵的缓存值的 Convex 组件.

## 安装

```sh
npm install @convex-dev/action-cache
```

也可以使用：`pnpm add @convex-dev/action-cache`、`yarn add @convex-dev/action-cache`、`bun add @convex-dev/action-cache`

## README

# Convex 动作缓存组件

[![npm version](https://badge.fury.io/js/@convex-dev%2Faction-cache.svg)](https://badge.fury.io/js/@convex-dev%2Faction-cache)

有时你的应用需要从第三方API那里获取信息,即 缓慢或花钱。 夹克可以帮助! 这是一个可缓存的 Convex 组件 并设置了可选的 TTL。 过期的条目为 一天一次通过工作清理干净 缓存键是 `ActionCache`名称 (默认为函数名称)和生成 缓存值 .

```ts
import { action } from "./_generated/server";
import { components } from "./_generated/api";
import { ActionCache } from "@convex-dev/action-cache";

const cache = new ActionCache(components.actionCache, {
  action: internal.example.myExpensiveAction,
});

export const myFunction = action({
  // NOTE: If we're returning the result, we need explicitly type the return value.
  // Refer to https://docs.convex.dev/functions/actions#dealing-with-circular-type-inference for more info.
  handler: async (ctx, args): Promise<{ text: string }> => {
    // Call it with the parameters to `myExpensiveAction`
    const result = await cache.fetch(ctx, { foo: "bar" });

    // Do something with the result or just return it
    return result;
  },
});

export const myExpensiveAction = internalAction({
  args: { foo: v.string() },
  handler: async (ctx, args): Promise<{ text: string }> {
    const data = await generateLLMResponse(ctx, args);
    return data;
  }
})
```

要取消缓存, 您可以设置一个明确和( 或) 清除缓存的新名称 以名称表示值.

## 预先要求: Convex

你需要一个现有的 Convex 项目来使用组件。 Convex 是一个主机 后端平台,包括数据库、无服务器功能和多一个吨 可以学习 [这里](https://docs.convex.dev/get-started)。 。 。 .

运行 `npm create convex` 或遵循其中任何一条 [快速启动](https://docs.convex.dev/home) 来设置一个.

## 安装

安装组件包 :

```bash
npm install @convex-dev/action-cache
```

创建一个 `convex.config.ts` 应用程序中的文件 `convex/` 文件夹并安装 通过调用 `use`数字 :

```ts
// convex/convex.config.ts
import { defineApp } from "convex/server";
import cache from "@convex-dev/action-cache/convex.config.js";

const app = defineApp();
app.use(cache);

export default app;
```

最后,创建一个新的 `ActionCache` 带有可选名称,并在 您的 Convex 工程,并将其指向已安装的组件.

-   这个 `name` 字段可用于识别函数或版本 用于创建缓存中的值并可用于分组 要删除的条目.
-   这个 `ttl` (Time-to-Live)字段决定缓存条目的长度 有效,以毫秒计.
    -   若无 `ttl` 中提供了缓存项.
    -   如果一个 `ttl` 中提供了已过期的缓存项 找了个工作.

```ts
import { ActionCache } from "@convex-dev/action-cache";
import { components } from "./_generated/api";

const cache = new ActionCache(components.actionCache, {
  action: internal.example.myExpensiveAction,
  name: "myExpensiveActionV1",
  ttl: 1000 * 60 * 60 * 24 * 7, // 7 days
});
```

## 示例

如果你正在制造一个应用软件 [向量搜索](https://docs.convex.dev/search/vector-search)计算 嵌入往往很贵——就我们而言,我们使用的是OpenAI的API 给每一次搜索增加耐用性 并花钱使用。 我们可以减少数量 API呼叫通过缓冲结果!

从定义开始 [凸起动作](https://docs.convex.dev/functions/actions) 它要求API创建嵌入. 随便换换你最喜欢的 嵌入 API. 您可能需要调整图中的矢量维度 `example/schema.ts` 相应.

设置您的 API 密钥 [环境变量](https://docs.convex.dev/production/environment-variables)

```bash
npx convex env set OPENAI_API_KEY <your-api-key>
```

```ts
export const embed = internalAction({
  args: { text: v.string() },
  handler: async (_ctx, { text }) => {
    const apiKey = process.env.OPENAI_API_KEY;
    if (!apiKey) {
      throw new Error("OPENAI_API_KEY environment variable not set!");
    }
    const req = { input: text, model: "text-embedding-ada-002" };
    const resp = await fetch("https://api.openai.com/v1/embeddings", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Authorization: `Bearer ${apiKey}`,
      },
      body: JSON.stringify(req),
    });
    if (!resp.ok) {
      const msg = await resp.text();
      throw new Error(`OpenAI API error: ${msg}`);
    }
    const json = await resp.json();
    const vector = json["data"][0]["embedding"];
    console.log(`Computed embedding of "${text}": ${vector.length} dimensions`);
    return vector as number[];
  },
});
```

创建嵌入缓存 :

```ts
const embeddingsCache = new ActionCache(components.actionCache, {
  action: internal.example.embed,
  name: "embed-v1",
});
```

运行向量搜索时使用缓存 :

```ts
export const vectorSearch = action({
  args: { query: v.string(), cuisines: v.array(v.string()) },
  handler: async (ctx, args) => {
    const embedding = await embeddingsCache.fetch(ctx, {
      text: args.query,
    });
    const results = await ctx.vectorSearch("foods", "by_embedding", {
      vector: embedding,
      limit: 16,
      filter: (q) =>
        q.or(...args.cuisines.map((cuisine) => q.eq("cuisine", cuisine))),
    });
    const rows: SearchResult[] = await ctx.runQuery(
      internal.example.fetchResults,
      { results },
    );
    return rows;
  },
});
```

### 定义多个缓存

您可以在多个动作中使用相同的组件,或者多个版本的 同样的动作。 您可以指定自定义 `name` 表示哪个缓存的参数 想要使用, 或更改名称以开始新鲜, 如 `embed-v2`。 。 。 .

如果返回值发生变化,必须更改名称,以免得到 意外值 .

### 在缓存到期前更新缓存

当出现缓存误差时,懒散运行动作是方便的. 不过, 这意味着有些请求会很慢,许多竞争请求可能 竞相运行动作并充入缓存.

你可以打个电话避开这个 `fetch` 与 `force` 选项。 这将会迫使 运行和更新缓存的动作,即使有缓存命中。 在那个 同时,其他请求会得到缓存命中.

如果您从 cron 工作调用, 缓存将总是有一个条目( 除非 动作失败).

### 清除值

要清除旧的价值观,你可以:

1.  通过参数删除一个条目.
    
    ```ts
    await embeddingsCache.remove(ctx, { text: "target text" });
    ```
    
2.  删除当前名称的所有条目( 默认为函数名称) 。 这是 如果您更新了执行并想要清除
    
    ```ts
    await embeddingsCache.removeAllForName(ctx);
    ```
    
3.  删除组件中的所有条目,包括所有名称.
    
    ```ts
    await embeddingsCache.removeAll(ctx);
    ```
    

更多实例使用 [实例.ts](https://npmcn.com/package/%40convex-dev/action-cache/example/convex/example.ts)。 。 。 .

## 常见问题

### @convex-dev/action-cache 是什么？

用于计算昂贵的缓存值的 Convex 组件\.

### 如何安装 @convex-dev/action-cache？

在项目目录运行 npm install @convex-dev/action-cache，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：convex（^1\.24\.8）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @convex-dev/action-cache 支持 TypeScript 吗？

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

### @convex-dev/action-cache 支持 ESM 还是 CommonJS？

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

### @convex-dev/action-cache 可以商用吗？

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

### @convex-dev/action-cache 的下载量有多少？

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

### @convex-dev/action-cache 还在维护吗？

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