Skip to main content

自带你的 AI 密钥插件

EnterpriseThis plugin is available with an Enterprise plan. 5.59.0This feature requires Strapi version 5.59.0 or later.
Page summary:

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

使用“自带 AI 密钥”插件时，Strapi AI 会将媒体库中的 AI 翻译和 AI 驱动的元数据生成请求发送到你选择的提供商。你可以为每个功能设置 API 密钥并选择模型。内容类型构建器 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 is not included: it is only available with Strapi-managed AI.

IDENTITY CARD
位置
在 /config/plugins 中配置。通过管理面板的 Strapi AI 功能使用。
包名
@strapi-enterprise/plugin-byok
附加资源
安装企业插件
Prerequisites
  • CMS 企业版计划的许可证。
  • Strapi 5.59.0 或更高版本。
  • 一个提供商的 API 密钥，该提供商拥有兼容 OpenAI 的 API。
  • 对于 AI 翻译，国际化 功能。

安装​

🌐 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

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

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

terminal
yarn strapi enterprise install plugin-byok

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

🌐 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 for details.

手动​

🌐 Manually

  1. 按照手动设置访问中的说明，设置对注册表的访问。
  2. 在你的 Strapi 应用的根文件夹中，安装这个包，并保存确切版本：
terminal
yarn add --exact @strapi-enterprise/plugin-byok
Caution

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

🌐 Once installed, the plugin is enabled, and Strapi does not start until the plugin is configured. See Configuration.

配置​

🌐 Configuration

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

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

  1. 把插件加到插件配置文件里：
/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'),
      },
    },
  },
});
  1. 在 .env 文件中设置环境变量。有关每个变量的预期值，请参见 配置选项:
terminal
/.env
STRAPI_BYOK_ENABLED=true
STRAPI_BYOK_PROVIDER_BASE_URL=
STRAPI_BYOK_PROVIDER_API_KEY=
STRAPI_BYOK_TRANSLATIONS_MODEL=
STRAPI_BYOK_MEDIA_METADATA_MODEL=
  1. 重启 Strapi。

配置选项​

🌐 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

该插件适用于提供兼容 OpenAI API 的供应商。Strapi 测试了以下模型。关于 connection.baseURL 的值，请参阅你供应商的文档：Anthropic、OpenAI、Google Gemini、OpenRouter 或 LiteLLM。

🌐 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, OpenAI, Google Gemini, OpenRouter, or LiteLLM.

提供商和模型系列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

插件配置好后，每个 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:

要关闭所有 Strapi AI 功能，包括插件提供的那些功能，请将 ai.enabled 设置为 false。

🌐 To turn off all Strapi AI features, including the ones the plugin powers, set ai.enabled to false.

检查插件是否激活​

🌐 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

症状应该做什么
Strapi 没有启动，并记录了一个选项 is required设置该选项。参见 配置选项。
警告显示你的 Strapi 许可不包含此功能请检查你的许可。在你的许可包含此功能之前，Strapi AI 功能将保持关闭。
警告：未安装 i18n 插件在启用 国际化 功能之前，AI 翻译保持关闭状态。媒体库功能仍然使用你的提供商。
启动时日志中没有 BYOK is ready 行检查 STRAPI_BYOK_ENABLED 是否为 true，以及 ai.enabled 是否不是 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重试。如果错误经常发生，尝试使用 已测试的提供商和模型 中更新的模型。对于在自己基础设施上运行模型的服务器，例如 Ollama，可以尝试更大的模型。

卸载​

🌐 Uninstallation

  1. 停止 Strapi。
  2. 从插件配置文件中移除 byok 条目。
  3. 删除这个包:
terminal
yarn remove @strapi-enterprise/plugin-byok
  1. 从 .env 文件中删除 STRAPI_BYOK_ENABLED、STRAPI_BYOK_PROVIDER_BASE_URL、STRAPI_BYOK_PROVIDER_API_KEY、STRAPI_BYOK_TRANSLATIONS_MODEL 和 STRAPI_BYOK_MEDIA_METADATA_MODEL 变量。
  2. 再次启动 Strapi。
On this page