WordPress 7.0内置了AI客户端——一个与提供者无关的PHP API，允许插件向AI模型发送提示，并通过一致的界面接收结果。你的插件描述了它需要什么以及需要什么。WordPress 负责将请求路由到网站所有者配置的供应商的合适型号。
本文解释了API表面，带你了解代码示例，并介绍了插件开发者需要了解的内容。
切入点：wp_ai_client_prompt()
每次互动都从：$builder = wp_ai_client_prompt();
这会返回一个对象，一个流畅的构建器，提供多种自定义提示的方式。你串联配置方法，然后调用生成方法来获得结果：WP_AI_Client_Prompt_Builder
$text = wp_ai_client_prompt( 'Summarize the benefits of caching in WordPress.' )
->using_temperature( 0.7 )
->generate_text();为了方便，你可以直接将提示文本作为参数传递给 ，当然也可以采用增量构建提示的方法。
文本生成
这里有一个基本的文本生成示例：
$text = wp_ai_client_prompt( 'Write a haiku about WordPress.' )
->generate_text();
if ( is_wp_error( $text ) ) {
// Handle error.
return;
}
echo wp_kses_post( $text );你可以传递一个JSON模式，让模型以JSON字符串的形式返回结构化数据：
$schema = array(
'type' => 'array',
'items' => array(
'type' => 'object',
'properties' => array(
'plugin_name' => array( 'type' => 'string' ),
'category' => array( 'type' => 'string' ),
),
'required' => array( 'plugin_name', 'category' ),
),
);
$json = wp_ai_client_prompt( 'List 5 popular WordPress plugins with their primary category.' )
->as_json_response( $schema )
->generate_text();
if ( is_wp_error( $json ) ) {
// Handle error.
return;
}
$data = json_decode( $json, true );你可以为同一提示请求多个回复候选人作为变体：
$texts = wp_ai_client_prompt( 'Write a tagline for a photography blog.' )
->generate_texts( 4 );图像生成
这里有一个基本的图像生成示例：
use WordPress\AiClient\Files\DTO\File;
$image_file = wp_ai_client_prompt( 'A futuristic WordPress logo in neon style' )
->generate_image();
if ( is_wp_error( $image_file ) ) {
// Handle error.
return;
}
echo '<img src="' . esc_url( $image_file->getDataUri() ) . '" alt="">';generate_image()返回一个通过 访问图像数据的 DTO 。FilegetDataUri()
类似于文本生成，你可以请求同一图片的多个变体：
$images = wp_ai_client_prompt( 'Aerial shot of snowy plains, cinematic.' )
->generate_images( 4 );
if ( is_wp_error( $images ) ) {
// Handle error.
return;
}
foreach ( $images as $image_file ) {
echo '<img src="' . esc_url( $image_file->getDataUri() ) . '">';
}获取完整的结果对象
对于更丰富的元数据，例如覆盖提供者和模型信息，请使用。例如，对于图像生成：generate_*_result()
$result = wp_ai_client_prompt( 'A serene mountain landscape.' )
->generate_image_result();该对象返回若干额外信息，包括令牌使用情况以及响应提示的提供者和模型。获取这些额外元数据的最相关方法有：GenerativeAiResult
getTokenUsage()返回代币使用情况，按输入、输出和可选的思考方式进行细分。getProviderMetadata()返回处理请求的提供者的元数据。getModelMetadata()： 返回处理请求的模型元数据（通过提供者）。
该对象可序列化，可以直接传递到 ，这使得通过 REST API 直接暴露 AI 功能变得简单。GenerativeAiResultrest_ensure_response()
可用方法：generate_*_result()
generate_text_result()generate_image_result()convert_text_to_speech_result()generate_speech_result()generate_video_result()
使用适合你所治疗的治疗方式的方法。每个对象返回一个具有丰富元数据的对象GenerativeAiResult。
模型偏好
每个WordPress网站上可用的模型取决于该网站管理员在设置>连接器界面中配置的AI提供商。
由于你的插件无法控制每个网站可用的供应商，可以用来标示哪些型号是理想的。AI客户端将使用列表中第一个可用的模型，如果没有兼容型号，则退回到任何兼容的模型：using_model_preference()
$text_result = wp_ai_client_prompt( 'Summarize the history of the printing press.' )
->using_temperature( 0.1 )
->using_model_preference(
'claude-sonnet-4-6',
'gemini-3.1-pro-preview',
'gpt-5.4'
)
->generate_text_result();这是偏好，不是强制要求。你的插件应该能在没有它的情况下运行。记住，你可以通过查看providerMeta和modelMetadata完整结果对象的和属性来测试或验证使用的模型。
如果不指定模型偏好，则会使用在配置提供者中遇到的第一个合适的模型。具体提供者实现需合理排序提供者模型，例如使较新的模型优先于同一模型家族的旧模型。三个初始官方提供者插件（见下文）以这种方式组织模型，符合推荐。
特征检测
并非每个WordPress网站都配置了AI服务提供者，也不是每个服务商都支持所有功能和所有选项。在展示AI驱动的UI之前，请检查该功能是否可正常工作：
$builder = wp_ai_client_prompt( 'test' )
->using_temperature( 0.7 );
if ( $builder->is_supported_for_text_generation() ) {
// Safe to show text generation UI.
}这些检查不调用 API。它们使用确定性逻辑将构建者的配置与可用模型的能力进行匹配。因此，它们运行快速，调用它们无需成本。
可用的支持检查方法：
is_supported_for_text_generation()is_supported_for_image_generation()is_supported_for_text_to_speech_conversion()is_supported_for_speech_generation()is_supported_for_video_generation()
用这些工具来有条件地加载你的UI，在功能不可用时显示有用的通知，或者干脆跳过注册UI。千万不要因为安装了WordPress 7.0就假设AI功能一定会用。
高级配置
系统指令
$text = wp_ai_client_prompt( 'Explain caching.' )
->using_system_instruction( 'You are a WordPress developer writing documentation.' )
->generate_text();最大词元
$text = wp_ai_client_prompt( 'Explain quantum computing in complicated terms.' )
->using_max_tokens( 8000 )
->generate_text();图像的输出文件类型和方向
use WordPress\AiClient\Files\Enums\FileTypeEnum;
use WordPress\AiClient\Files\Enums\MediaOrientationEnum;
$result = wp_ai_client_prompt()
->with_text( 'A vibrant sunset over the ocean.' )
->as_output_file_type( FileTypeEnum::inline() )
->as_output_media_orientation( MediaOrientationEnum::from( 'landscape' ) )
->generate_image_result();多模态输出
use WordPress\AiClient\Messages\Enums\ModalityEnum;
$result = wp_ai_client_prompt( 'Create a recipe for a chocolate cake and include photos for the steps.' )
->as_output_modalities( ModalityEnum::text(), ModalityEnum::image() )
->generate_result();
if ( is_wp_error( $result ) ) {
// Handle error.
return;
}
foreach ( $result->toMessage()->getParts() as $part ) {
if ( $part->isText() ) {
echo wp_kses_post( $part->getText() );
} elseif ( $part->isFile() && $part->getFile()->isImage() ) {
echo '<img src="' . esc_url( $part->getFile()->getDataUri() ) . '">';
}
}其他建造方法
完整的配置方法列表可通过WP_AI_Client_Prompt_Builder该类获得。主要方法包括：
| 配置 | 方法 |
|---|---|
| 提示文本 | with_text() |
| 文件输入 | with_file() |
| 对话历史（适用于多回合/聊天） | with_history() |
| 系统指令 | using_system_instruction() |
| 温度 | using_temperature() |
| 最大代币 | using_max_tokens() |
| Top-p / Top-k | using_top_p(), using_top_k() |
| 停止序列 | using_stop_sequences() |
| 模型偏好 | using_model_preference() |
| 输出模态 | as_output_modalities() |
| 输出文件类型 | as_output_file_type() |
| JSON 响应 | as_json_response() |
错误处理
wp_ai_client_prompt()生成器方法在失败时返回，遵循WordPress的惯例：WP_Error
$text = wp_ai_client_prompt( 'Hello' )
->generate_text();
if ( is_wp_error( $text ) ) {
// Handle the error.
}当用于REST API回调时，和都可以直接传递给：GenerativeAiResultWP_Errorrest_ensure_response()
function my_rest_callback( WP_REST_Request $request ) {
$result = wp_ai_client_prompt( $request->get_param( 'prompt' ) )
->generate_text_result();
return rest_ensure_response( $result );
}如果发生错误，它会自动附加一个语义意义的 HTTP 响应代码。
控制AI可用性
对于细致控制，wp_ai_client_prevent_prompt过滤器允许阻止特定提示执行：
add_filter(
'wp_ai_client_prevent_prompt',
function ( bool $prevent, WP_AI_Client_Prompt_Builder $builder ): bool {
// Example: Block all prompts for non-admin users.
if ( ! current_user_can( 'manage_options' ) ) {
return true;
}
return $prevent;
},
10,
2
);当提示被阻止时：
- 没有尝试AI呼叫。
is_supported_*()方法返回false，使插件能够优雅地隐藏其界面。generate_*()方法返回WP_Error。
架构
WordPress 7.0 中的 AI 客户端由两层组成：
- PHP AI 客户端（wordpress/php-ai-client）——一个与提供者无关的 PHP SDK，作为外部库捆绑在 Core 中。这是负责提供者沟通、模型选择和响应规范化的引擎。由于它技术上是一个与WordPress无关的PHP SDK，其他PHP项目也能使用，因此它使用camelCase方法命名并利用异常。
- WordPress 包装器——Core 类用 WordPress 的惯例包裹 PHP AI 客户端：snake_case方法、返回，以及与 WordPress HTTP 传输、Abilities API、连接器/设置基础设施和 WordPress 钩子系统的集成。
WP_AI_Client_Prompt_BuilderWP_Error
函数是推荐的入门点。它返回一个实例，捕获底层SDK的异常并将其转换为对象。wp_ai_client_prompt()WP_AI_Client_Prompt_BuilderWP_Error
证书管理
API 密钥通过连接器 API 进行管理。注册到 PHP AI 客户端提供者注册表的 AI 提供者插件会获得自动连接器集成——包括 API 密钥管理 UI > Connectors 设置。使用 AI 客户端构建功能的插件开发者根本不需要处理凭证。
官方提供者插件
WordPress Core 不直接捆绑任何 AI 服务提供者。相反，它们以插件的形式开发和维护，从而根据AI的发展速度，实现更灵活和快速的迭代速度。WordPress Core 中的 AI 客户端提供了稳定的基础，作为抽象层，它足够脱离可能一夜之间变化的提供者特定需求。
虽然任何人都可以实现新的提供者插件，但WordPress项目本身开发了三个最初的旗舰实现，以与最受欢迎的AI提供商集成。这些插件包括：
- 人类学人工智能提供商
- 谷歌的人工智能提供商
- OpenAI 的人工智能提供商
单独提供：客户端JavaScript API
通过 wp-ai-client 包，提供了带有类似流利提示构建器的 JavaScript API。它在底层使用REST端点连接服务器端基础设施。该 API 不属于 Core 版本，目前仍在评估该方法是否适合通用使用。由于 API 允许客户端任意执行提示符，因此需要高权限能力检查，默认情况下仅授予管理员权限。这一限制是为了防止不受信任的用户向任何配置好的AI提供商发送任何提示。因此，不建议在分布式插件中使用这种方法。
目前推荐的做法是为插件提供的每个特定 AI 功能实现独立的 REST API 端点，然后让 JavaScript 功能调用这些端点。这允许你执行细致的权限检查，并限制客户端可执行的范围。它还保持了AI提示处理和配置的完全范围，仅限于服务器端。
从 php-ai-client 和 wp-ai-client 迁移
如果你之前在插件中使用过这些软件包，以下是你需要知道的事项。
推荐：要求使用 WordPress 7.0
最简单的方法是将插件的“至少需要”头部“更新到7.0，并移除Composer对及其传递依赖的依赖。wordpress/php-ai-client
将所有调用替换为 。AI_Client::prompt()wp_ai_client_prompt()
对于包，如果你没有使用包的REST API端点或JavaScript API，你可以直接将其作为依赖移除，因为它的其他功能现在都集成在WordPress Core中。wordpress/wp-ai-client
如果你非得支持 WordPress < 7.0
PHP AI 客户端（wordpress/php-ai-client)
如果你的插件还需要在 WordPress 7.0 之前的版本上运行，同时还要捆绑 wordpress/php-ai-client，那你就需要一个条件自动加载器的变通办法。PHP AI 客户端及其依赖现在由 Core 在 7.0+ 版本中加载，因此通过 Composer 再次加载会导致冲突（类定义重复）。
解决方案是：在运行 WordPress 7.0 之前的版本时，只注册 Composer 自动加载器来管理这些依赖：
if ( ! function_exists( 'wp_get_wp_version' ) || version_compare( wp_get_wp_version(), '7.0', '<' ) ) {
require_once __DIR__ . '/vendor/autoload.php';
}由于Composer的自动加载器的工作方式——一次性加载所有依赖，而非选择性加载——更细致的方法不可行。这意味着条件检查需要包裹整个自动装填器。或者，把PHP依赖拆开，分别用两个不同的Composer设置，一个可以自动加载，另一个只针对包及其依赖，条件自动加载。wordpress/php-ai-client
WP AI 客户端 （wordpress/wp-ai-client)
该软件包会自动处理 WordPress 7.0 的过渡。在7.0+版本中，它禁用了自己的PHP SDK基础设施（因为Core原生处理），但保留了REST API端点和JavaScript API的激活功能，因为这些还不在Core中。wordpress/wp-ai-client
你可以无条件继续加载这个包裹。它检测WordPress版本，只激活Core未提供的部分。不需要条件加载。不过，务必保持对此包的更新，因为它很可能很快会被终止，取而代之的是将REST API端点和JavaScript API迁移到Gutenberg。
