# 自带 AI 密钥插件

> Source: https://strapi.nodejs.cn/cms/plugins/byok

自带AI密钥（BYOK）插件让你可以使用自己的AI提供商为Strapi AI提供支持，用于AI翻译和AI驱动的元数据生成。

使用“自带 AI 密钥”插件时，Strapi AI 会将媒体库中的 AI 翻译和 AI 驱动的元数据生成请求发送到你选择的提供商。你可以为每个功能设置 API 密钥并选择模型。[内容类型构建器 AI 助手](/cms/features/content-type-builder#strapi-ai) 不包含在内：它只在 Strapi 托管的 AI 中可用。

🌐 With the Bring your own AI key plugin, Strapi AI sends the requests of AI Translations and AI-powered metadata generation in the Media Library to the provider of your choice. You set the API key and pick the model for each feature. The [Content-Type Builder AI assistant](/cms/features/content-type-builder#strapi-ai) is not included: it is only available with Strapi-managed AI.

**位置**

在 `/config/plugins` 中配置。通过管理面板的 Strapi AI 功能使用。

**包名**

`@strapi-enterprise/plugin-byok`

**附加资源**

[安装企业插件](/cms/plugins/installing-enterprise-plugins)

:::prerequisites

- CMS 企业版计划的许可证。
- Strapi 5.59.0 或更高版本。
- 一个提供商的 API 密钥，该提供商拥有兼容 OpenAI 的 API。
- 对于 AI 翻译，[国际化](/cms/features/internationalization) 功能。

:::

## 安装 {#installation}

🌐 Installation

这个插件可以从 Strapi 软件包注册表安装。`strapi enterprise install` 命令会帮你完成设置，或者你也可以手动操作。

🌐 The plugin installs from the Strapi package registry. The `strapi enterprise install` command does the setup for you, or you can do it manually.

### 用命令 {#with-the-command}

🌐 With the command

在你的 Strapi 应用的根文件夹中，运行：

🌐 From the root folder of your Strapi application, run:

```bash
yarn strapi enterprise install plugin-byok
```
```bash
npm run strapi enterprise install plugin-byok
```
```bash
pnpm strapi enterprise install plugin-byok
```

该命令会找到你的许可证，设置对注册表的访问，并安装支持你应用对应的 Strapi 版本的版本。详情请参阅 [安装企业插件](/cms/plugins/installing-enterprise-plugins)。

🌐 The command finds your license, sets up access to the registry, and installs a version that supports the Strapi version of your application. See [Installing Enterprise plugins](/cms/plugins/installing-enterprise-plugins) for details.

### 手动 {#manually}

🌐 Manually

1. 按照[手动设置访问](/cms/plugins/installing-enterprise-plugins#setting-up-access-manually)中的说明，设置对注册表的访问。
2. 在你的 Strapi 应用的根文件夹中，安装这个包，并保存确切版本：

  ```bash
  yarn add --exact @strapi-enterprise/plugin-byok
  ```
  ```bash
  npm install --save-exact @strapi-enterprise/plugin-byok
  ```
  ```bash
  pnpm add --save-exact @strapi-enterprise/plugin-byok
  ```

:::caution

插件安装后会被启用，在插件配置完成之前，Strapi 不会启动。详情请见 [配置](#configuration)。

🌐 Once installed, the plugin is enabled, and Strapi does not start until the plugin is configured. See [Configuration](#configuration).

:::

## 配置 {#configuration}

🌐 Configuration

这个插件是在插件配置文件中配置的，提供者连接和模型用环境变量设置。

🌐 The plugin is configured in the plugins configuration file, with environment variables for the provider connection and the models.

1. 把插件加到插件配置文件里：

  ```js title="/config/plugins.js"
  module.exports = ({ env }) => ({
    // …
    byok: {
      enabled: env.bool('STRAPI_BYOK_ENABLED', false),
      config: {
        connection: {
          baseURL: env('STRAPI_BYOK_PROVIDER_BASE_URL'),
          apiKey: env('STRAPI_BYOK_PROVIDER_API_KEY'),
        },
        models: {
          translations: env('STRAPI_BYOK_TRANSLATIONS_MODEL'),
          mediaMetadata: env('STRAPI_BYOK_MEDIA_METADATA_MODEL'),
        },
      },
    },
  });
  ```
  ```ts title="/config/plugins.ts"
  export default ({ env }) => ({
    // …
    byok: {
      enabled: env.bool('STRAPI_BYOK_ENABLED', false),
      config: {
        connection: {
          baseURL: env('STRAPI_BYOK_PROVIDER_BASE_URL'),
          apiKey: env('STRAPI_BYOK_PROVIDER_API_KEY'),
        },
        models: {
          translations: env('STRAPI_BYOK_TRANSLATIONS_MODEL'),
          mediaMetadata: env('STRAPI_BYOK_MEDIA_METADATA_MODEL'),
        },
      },
    },
  });
  ```

2. 在 `.env` 文件中设置环境变量。有关每个变量的预期值，请参见 [配置选项](#configuration-options):

  ```bash title="/.env"
  STRAPI_BYOK_ENABLED=true
  STRAPI_BYOK_PROVIDER_BASE_URL=
  STRAPI_BYOK_PROVIDER_API_KEY=
  STRAPI_BYOK_TRANSLATIONS_MODEL=
  STRAPI_BYOK_MEDIA_METADATA_MODEL=
  ```

3. 重启 Strapi。

### 配置选项 {#configuration-options}

🌐 Configuration options

如果在插件启用时缺少必需的选项，Strapi 就不会启动，并且会记录第一个缺失的选项。

🌐 If a required option is missing while the plugin is enabled, Strapi does not start and logs the first missing option.

| 选项 | 类型 | 必填 | 描述 |
|---|---|---|---|
| `enabled` | 布尔 | 否 | 在不卸载插件的情况下打开或关闭插件。根据上面的配置，除非 `STRAPI_BYOK_ENABLED` 为 `true`，否则插件保持关闭状态。 |
| `connection.baseURL` | 字符串 | 是 | 提供商 OpenAI 兼容 API 的根 URL，包含版本前缀。例如，OpenAI 使用 `https://api.openai.com/v1`，Anthropic 使用 `https://api.anthropic.com/v1`。 |
| `connection.apiKey` | 字符串 | 是 | 你的提供商的 API 密钥，只能保存在服务器环境中。 |
| `models.translations` | 字符串 | 是 | 用于 AI 翻译的模型，例如 OpenAI 的 `gpt-4o` 或 Anthropic 的 `claude-haiku-4-5`。 |
| `models.mediaMetadata` | 字符串 | 是 | 用于在媒体库生成替代文本和标题的模型。该模型必须支持图片输入，例如 OpenAI 的 `gpt-4o` 或 Anthropic 的 `claude-sonnet-5-5`。 |

:::tip

在没有 API 密钥的环境中（例如测试环境），使用 `STRAPI_BYOK_ENABLED` 来保持插件关闭。

🌐 Use `STRAPI_BYOK_ENABLED` to keep the plugin off in an environment without an API key, such as a staging environment.

:::

### 已测试的供应商和模型 {#tested-providers-and-models}

🌐 Tested providers and models

该插件适用于提供兼容 OpenAI API 的供应商。Strapi 测试了以下模型。关于 `connection.baseURL` 的值，请参阅你供应商的文档：[Anthropic](https://platform.claude.com/docs/en/cli-sdks-libraries/libraries/openai-sdk)、[OpenAI](https://developers.openai.com/api/reference/overview)、[Google Gemini](https://ai.google.dev/gemini-api/docs/openai)、[OpenRouter](https://openrouter.ai/docs/quickstart) 或 [LiteLLM](https://docs.litellm.ai/docs/proxy/user_keys)。

🌐 The plugin works with providers that offer an OpenAI-compatible API. Strapi tested the following models. For the `connection.baseURL` value, see the documentation of your provider: [Anthropic](https://platform.claude.com/docs/en/cli-sdks-libraries/libraries/openai-sdk), [OpenAI](https://developers.openai.com/api/reference/overview), [Google Gemini](https://ai.google.dev/gemini-api/docs/openai), [OpenRouter](https://openrouter.ai/docs/quickstart), or [LiteLLM](https://docs.litellm.ai/docs/proxy/user_keys).

| 提供商和模型系列 | AI翻译 (`models.translations`) | AI驱动的元数据生成 (`models.mediaMetadata`) |
|---|---|---|
| Anthropic Claude Haiku | `>=claude-haiku-4-5` | `>=claude-haiku-4-5` |
| Anthropic Claude Sonnet | `>=claude-sonnet-4-5` | `>=claude-sonnet-4-5` |
| Anthropic Claude Opus | `>=claude-opus-4-5` | `>=claude-opus-4-8` |
| Anthropic Claude Fable | `>=claude-fable-5` | `>=claude-fable-5` |
| OpenAI GPT | `>=gpt-4` | `>=gpt-4o` |
| OpenAI GPT mini | `>=gpt-5.4-mini` | `>=gpt-4o-mini` |
| OpenAI o系列 | `>=o3` | `>=o3` |
| Google Gemini | `>=gemini-3` | `>=gemini-3` |
| OpenRouter | 与上面相同，但使用OpenRouter ID（例如 `anthropic/claude-haiku-4.5`） | 与上面相同，但使用OpenRouter ID |
| LiteLLM | 与上面相同，但使用你的LiteLLM模型名称 | 与上面相同，但使用你的LiteLLM模型名称 |

:::note

Strapi 只测试了上面这些模型，但理论上任何其他兼容 OpenAI 的 API 都应该可以用。对于 AI 驱动的元数据生成，确保你使用的是可以接受图片输入的模型。

🌐 Strapi only tested the models above, but in theory any other OpenAI-compatible API should work. For AI-powered metadata generation, ensure that you use a model that accepts image input.

人工智能模型对相同的请求并不总是给出相同的回复，所以即使是经过测试的模型有时也会出错。如果发生这种情况，可以再试一次。

🌐 AI models don't always reply the same way to the same request, so even a tested model can fail now and then. If that happens, retry the request.

:::

## 使用 {#usage}

🌐 Usage

插件配置好后，每个 AI 功能都会按照各自的文档说明运行，包括如何开启它。它的请求会发送到你的提供商：

🌐 Once the plugin is configured, each AI feature works as described in its own documentation, including how to turn it on. Its requests go to your provider:

- [AI 翻译](/cms/features/internationalization#enabling-ai-powered-internationalization)（AI 驱动的国际化）
- [AI驱动的元数据生成](/cms/features/media-library#ai-powered-metadata-generation)，包括[批量生成元数据](/cms/features/media-library#bulk-metadata)

要关闭所有 Strapi AI 功能，包括插件提供的那些功能，请将 [`ai.enabled`](/cms/configurations/admin-panel#strapi-ai) 设置为 `false`。

🌐 To turn off all Strapi AI features, including the ones the plugin powers, set [`ai.enabled`](/cms/configurations/admin-panel#strapi-ai) to `false`.

### 检查插件是否激活 {#checking-that-the-plugin-is-active}

🌐 Checking that the plugin is active

当 Strapi 启动时，服务器日志会列出使用你提供者的功能，例如：

🌐 When Strapi starts, the server logs list the features that use your provider, for instance:

```
BYOK is ready for AI Translation, AI Media Library. Requests go to your configured provider.
```

## 故障排除 {#troubleshooting}

🌐 Troubleshooting

| 症状 | 应该做什么 |
|---|---|
| Strapi 没有启动，并记录了一个选项 `is required` | 设置该选项。参见 [配置选项](#configuration-options)。 |
| 警告显示你的 Strapi 许可不包含此功能 | 请检查你的许可。在你的许可包含此功能之前，Strapi AI 功能将保持关闭。 |
| 警告：未安装 i18n 插件 | 在启用 [国际化](/cms/features/internationalization) 功能之前，AI 翻译保持关闭状态。媒体库功能仍然使用你的提供商。 |
| 启动时日志中没有 `BYOK is ready` 行 | 检查 `STRAPI_BYOK_ENABLED` 是否为 `true`，以及 [`ai.enabled`](/cms/configurations/admin-panel#strapi-ai) 是否不是 `false`。 |
| `The AI provider rejected the request (HTTP 401)` 或 `(HTTP 403)` | 检查 `connection.apiKey`。 |
| `The AI provider rejected the request (HTTP 404)` | 检查 `connection.baseURL` 是否包含 API 版本路径，例如 `/v1`，并确认你的提供商仍然提供你设置的模型。有些提供商在你的账户无法使用该模型时也会返回 404 错误。 |
| `The AI provider did not return valid JSON` | 重试。如果错误经常发生，尝试使用 [已测试的提供商和模型](#tested-providers-and-models) 中更新的模型。对于在自己基础设施上运行模型的服务器，例如 Ollama，可以尝试更大的模型。 |

## 卸载 {#uninstallation}

🌐 Uninstallation

1. 停止 Strapi。
2. 从插件配置文件中移除 `byok` 条目。
3. 删除这个包:

  ```bash
  yarn remove @strapi-enterprise/plugin-byok
  ```
  ```bash
  npm uninstall @strapi-enterprise/plugin-byok
  ```
  ```bash
  pnpm remove @strapi-enterprise/plugin-byok
  ```

4. 从 `.env` 文件中删除 `STRAPI_BYOK_ENABLED`、`STRAPI_BYOK_PROVIDER_BASE_URL`、`STRAPI_BYOK_PROVIDER_API_KEY`、`STRAPI_BYOK_TRANSLATIONS_MODEL` 和 `STRAPI_BYOK_MEDIA_METADATA_MODEL` 变量。
5. 再次启动 Strapi。