WordPress 7.0 ra mắt kiến trúc AI native hoàn toàn mới, cho phép plugin giao tiếp với OpenAI, Google Gemini, Anthropic qua một PHP API duy nhất. Không cần cài SDK, không cần quản lý API key trong từng plugin, không cần viết cURL request thủ công. Bài viết này mình sẽ hướng dẫn từ A đến Z cách sử dụng wp_ai_client_prompt() để xây dựng plugin AI sẵn sàng production.
Trước đây, khi muốn thêm tính năng AI vào plugin WordPress, mình phải nhúng SDK của từng provider (OpenAI PHP client, Anthropic SDK…), viết riêng logic xác thực, xử lý response khác nhau cho mỗi model. Đổi provider nghĩa là viết lại toàn bộ network layer. Với WordPress 7.0, tất cả chuyện đó kết thúc.
WordPress AI Client Là Gì Va Tai Sao Ban Nen Quan Tam?
AI Client là PHP API native trong WordPress 7.0+, cung cấp hàm wp_ai_client_prompt() giúp plugin giao tiếp với bất kỳ AI provider nào thông qua một interface thống nhất. Bạn viết code một lần, WordPress tự động dịch sang “ngôn ngữ” của từng model.
Đây không phải plugin AI sẵn có hay tính năng chatbot có sẵn. Nó là foundation — lớp hạ tầng cho phép developer xây dựng tính năng AI mà không phụ thuộc vào provider cụ thể. Nếu bạn đang phát triển plugin cho WordPress 7.0+, đây là cách đúng đắn duy nhất để tích hợp AI.
Kien Truc 3 Lop Cua WordPress AI
WordPress AI architecture chia thành ba lớp riêng biệt, mỗi lớp có vai trò rõ ràng. Hiểu ba lớp này là chìa khóa để xây dựng plugin AI đúng cách.
Lop 1: AI Connector
AI Connector là giao diện quản lý trong WordPress admin, nằm tại Settings > Connectors. Tại đây, admin nhập API key cho từng provider (OpenAI, Google Gemini, Anthropic) một lần duy nhất. Tất cả plugin trên site dùng chung bộ credentials này.
Trước WordPress 7.0, mỗi plugin tự lưu API key riêng. Plugin A dùng OpenAI, plugin B dùng Gemini — admin phải cấu hình hai nơi, hai giao diện khác nhau. Nếu gỡ plugin, API key bị mất. Nếu plugin cũ có lỗ hổng bảo mật, key bị lộ. AI Connector giải quyết triệt để vấn đề này.
Lợi ích quan trọng nhất: tách biệt authentication khỏi logic plugin. Đổi API key chỉ cần update một chỗ. Thu hồi quyền truy cập của một provider chỉ cần một click — tất cả plugin ngừng sử dụng provider đó ngay lập tức.
Lop 2: AI Client
AI Client là PHP API mà developer sử dụng trong code plugin. Hàm chính là wp_ai_client_prompt(), trả về đối tượng WP_AI_Client_Prompt_Builder với hơn 50 phương thức chainable (Fluent Interface).
Thay vì viết HTTP request riêng cho từng provider, bạn chỉ cần gọi:
$result = wp_ai_client_prompt( 'Tóm tắt bài viết sau thành 3 câu' )
->with_text( $post_content )
->using_temperature( 0.3 )
->generate_text();WordPress tự động biên dịch lệnh này thành request phù hợp cho provider đang active. Nếu admin dùng OpenAI, nó gửi OpenAI API format. Nếu admin chuyển sang Gemini, cùng đoạn code đó tự động gửi Gemini API format. Zero code change.
Lop 3: AI Provider
AI Provider là công ty cung cấp model: OpenAI (GPT), Google (Gemini), Anthropic (Claude). WordPress 7.0 hỗ trợ sẵn ba provider lớn nhất. Developer cũng có thể đăng ký provider custom thông qua wp_register_ai_provider().
Khi plugin gọi generate_text(), WordPress biên dịch payload, gửi đến endpoint của provider đang active, nhận response và trả về cho plugin. Toàn bộ quá trình truyền dữ liệu, parse response, xử lý error do WordPress Core lo.
Cau Hinh AI Connector Trong WordPress Admin
Trước khi code plugin, cần cấu hình ít nhất một AI provider. Đăng nhập WordPress admin, vào Settings > Connectors. Giao diện hiển thị danh sách các provider được hỗ trợ.
Click vào provider muốn kích hoạt (ví dụ Google Gemini), nhập API key. Key cần có quyền truy cập model bạn định dùng. Với Gemini, mình dùng key miễn phí từ Google AI Studio (aistudio.google.com/apikey), đủ 15 request/phút cho development.
Kích hoạt xong, status chuyển sang “Connected”. Provider này giờ available cho mọi plugin trên site. Không cần cấu hình thêm trong từng plugin nữa.
Nếu muốn dự phòng, kích hoạt hai provider cùng lúc. WordPress sẽ tự chọn provider phù hợp nhất dựa trên model preference trong code plugin — tính năng mình sẽ giải thích ở phần sau.
Build Plugin AI Dau Tien: Text Generator Don Gian
Đến phần thú vị nhất. Mình sẽ hướng dẫn xây dựng một plugin đơn giản: nhận nội dung post, yêu cầu AI tạo meta description tự động. Plugin này dùng hoàn toàn native WordPress API, không cần Composer, không cần npm, không cần SDK bên ngoài.
Buoc 1: Tao Plugin Structure
Tạo folder ai-meta-generator trong wp-content/plugins/, bên trong tạo file ai-meta-generator.php:
<?php
/**
* Plugin Name: AI Meta Generator
* Description: Tu dong tao meta description bang WordPress AI Client
* Version: 1.0.0
* Requires at least: 7.0
*/
if ( ! defined( 'ABSPATH' ) ) {
exit;
}
/**
* Generate meta description cho post bang AI Client.
*
* @param int $post_id ID cua post can tao meta description.
* @return string|WP_Error Meta description hoac error.
*/
function ai_meta_generator_create( $post_id ) {
$post = get_post( $post_id );
if ( ! $post ) {
return new WP_Error( 'invalid_post', 'Post khong ton tai' );
}
// Lay noi dung post, strip HTML tags
$content = wp_strip_all_tags( $post->post_content );
// Gioi han 2000 ky tu de tiet kiem token
$content = mb_substr( $content, 0, 2000 );
$prompt = "Viet meta description SEO cho bai viet sau, "
. "toi da 150 ky tu, chua ten bai viet neu co the.\n\n"
. "Tieu de: " . $post->post_title . "\n"
. "Noi dung: " . $content;
// Goi WordPress AI Client
$result = wp_ai_client_prompt( $prompt )
->using_system_instruction(
'Ban la chuyen gia SEO. Luon viet meta description '
. 'ngan gon, chua tu khoa chinh, duoi 160 ky tu.'
)
->using_temperature( 0.3 )
->using_max_tokens( 100 )
->generate_text();
if ( is_wp_error( $result ) ) {
return $result;
}
return trim( $result );
}Đoạn code trên rất trực quan. Hàm wp_ai_client_prompt() nhận prompt text, rồi chain các phương thức cấu hình. using_system_instruction() set role cho AI, using_temperature() kiểm soát độ sáng tạo (0.3 = khá deterministic), using_max_tokens() giới hạn output. Cuối cùng, generate_text() gửi request và trả về kết quả.
Buoc 2: Them Meta Box De Hien Thi Button
Thêm code sau vào cùng file plugin để tạo button trong post editor:
/**
* Them meta box voi button generate.
*/
function ai_meta_generator_meta_box() {
add_meta_box(
'ai-meta-generator',
'AI Meta Description',
'ai_meta_generator_render_meta_box',
'post',
'side'
);
}
add_action( 'add_meta_boxes', 'ai_meta_generator_meta_box' );
function ai_meta_generator_render_meta_box( $post ) {
wp_nonce_field( 'ai_meta_generate', 'ai_meta_nonce' );
?>
<p>Nhan de AI tu dong viet meta description.</p>
<button type="button" class="button button-primary"
id="ai-meta-generate-btn">
Generate Meta Description
</button>
<textarea id="ai-meta-result"
name="ai_meta_description"
style="width:100%;margin-top:10px;"
rows="3"><?php
echo esc_textarea( get_post_meta( $post->ID, '_meta_description', true ) );
?></textarea>
<script>
jQuery(document).ready(function($) {
$('#ai-meta-generate-btn').on('click', function() {
var btn = $(this);
btn.text('Dang generate...').prop('disabled', true);
$.post(ajaxurl, {
action: 'ai_meta_generate',
post_id: <?php echo $post->ID; ?>,
nonce: $('#ai_meta_nonce').val()
}, function(response) {
btn.text('Generate Meta Description').prop('disabled', false);
if (response.success) {
$('#ai-meta-result').val(response.data);
} else {
alert('Loi: ' + response.data);
}
});
});
});
</script>
<?php
}
/**
* Ajax handler cho generate meta description.
*/
function ai_meta_generator_ajax() {
check_ajax_referer( 'ai_meta_generate', 'nonce' );
if ( ! current_user_can( 'edit_posts' ) ) {
wp_send_json_error( 'Khong co quyen' );
}
$post_id = intval( $_POST['post_id'] );
$result = ai_meta_generator_create( $post_id );
if ( is_wp_error( $result ) ) {
wp_send_json_error( $result->get_error_message() );
}
update_post_meta( $post_id, '_meta_description', $result );
wp_send_json_success( $result );
}
add_action( 'wp_ajax_ai_meta_generate', 'ai_meta_generator_ajax' );Plugin hoàn chỉnh chỉ với hai hàm chính: ai_meta_generator_create() giao tiếp với AI Client, và AJAX handler trả kết quả về editor. Không một dòng nào import thư viện bên ngoài. Toàn bộ AI logic được WordPress Core xử lý.
Cac Method Quan Trong Cua wp_ai_client_prompt()
Fluent Interface của wp_ai_client_prompt() cung cấp hơn 50 phương thức. Dưới đây là những method mình dùng thường xuyên nhất, kèm ví dụ cụ thể.
with_text() – Them Noi Dung Text
$result = wp_ai_client_prompt( 'Phan tich cam xuc doan text sau' )
->with_text( $user_input )
->generate_text();Thêm text vào message hiện tại. Có gọi nhiều lần để concat nhiều đoạn text khác nhau.
with_file() – Dinh Kem File (Multimodal)
// Doc file audio va encode base64
$audio_path = '/path/to/audio.mp3';
$audio_data = base64_encode( file_get_contents( $audio_path ) );
$result = wp_ai_client_prompt( 'Chuyen doi audio nay thanh text' )
->with_file( $audio_data, 'audio/mpeg' )
->using_temperature( 0.1 )
->generate_text();Mở khóa khả năng multimodal. AI Provider nhận file (audio, image, video) cùng text prompt. Ứng dụng: transcript podcast, OCR ảnh, phân tích video.
using_model_preference() – Chi Dinh Model Uu Tien
$result = wp_ai_client_prompt( $prompt )
->using_model_preference(
'gemini-2.5-flash',
'claude-3-5-sonnet',
'gpt-4o'
)
->generate_text();WordPress kiểm tra provider nào đang active, chọn model đầu tiên trong danh sách có sẵn. Nếu không có model nào match, fallback về model mặc định của provider đang active. Đảm bảo plugin luôn hoạt động bất kể admin cấu hình provider nào.
as_json_response() – Output Co Cau Truc JSON
// Dinh nghia schema cho JSON output
$schema = array(
'type' => 'object',
'properties' => array(
'title' => array( 'type' => 'string' ),
'summary' => array( 'type' => 'string' ),
'tags' => array(
'type' => 'array',
'items' => array( 'type' => 'string' )
)
),
'required' => array( 'title', 'summary' )
);
$result = wp_ai_client_prompt( 'Phan tich bai viet va tra ve JSON' )
->with_text( $post_content )
->as_json_response( $schema )
->generate_text();
$data = json_decode( $result, true );
// $data['title'], $data['summary'], $data['tags']Ép model trả về JSON theo schema định nghĩa. Rất hữu ích khi cần import kết quả AI vào database hoặc map vào Gutenberg blocks.
using_system_instruction() – Set Role Cho AI
$result = wp_ai_client_prompt( $prompt )
->using_system_instruction(
'Ban la editor voi 10 nam kinh nghiệm. '
. 'Viet tieng Viet chuan, ngan gon, khong lung tung.'
)
->generate_text();Tách biệt role/persona khỏi data payload. Model hiểu rõ “ai đang trả lời” thay vì bị nhầm lẫn giữa instruction và nội dung cần xử lý.
Kiem Tra Provider Co Ho Tro Khong Truoc Khi Goi
Đây là lỗi phổ biến mình gặp ở client: plugin gọi generate_text() nhưng không có provider nào được cấu hình. Kết quả: WP_Error hiển thị trên frontend, user hoảng hốt.
Luôn kiểm tra trước khi gọi generate:
$builder = wp_ai_client_prompt( $prompt )
->with_file( $file_data, $mime_type );
// Kiem tra provider co ho tro text generation khong
if ( ! $builder->is_supported_for_text_generation() ) {
return new WP_Error(
'no_provider',
'Chua cau hinh AI Provider. '
. 'Vao Settings > Connectors de them API key.'
);
}
$result = $builder->generate_text();Các hàm kiểm tra tương tự: is_supported_for_image_generation(), is_supported_for_text_to_speech_conversion(), is_supported_for_video_generation(). Luôn dùng trước khi gọi generate để tránh error không cần thiết.
Xu Ly Loi Va Error Handling Dung Cach
wp_ai_client_prompt() xử lý error theo cơ chế đặc biệt: nếu bất kỳ method nào trong chain gây exception, builder chuyển sang error state. Các method tiếp theo trở thành no-op (không làm gì). Chỉ khi gọi generate method, WP_Error mới được trả về.
$result = wp_ai_client_prompt( $prompt )
->using_temperature( -5 ) // Gia tri khong hop le
->using_max_tokens( 0 ) // Gia tri khong hop le
->generate_text(); // Luc nay moi tra WP_Error
if ( is_wp_error( $result ) ) {
error_log( 'AI Client Error: ' . $result->get_error_message() );
// Fallback: tra ve gia tri mac dinh thay vi bao loi
return $default_value;
}
// Xu ly result binh thuong
return $result;Nguyên tắc: luôn check is_wp_error() sau generate method. Log error cho developer, trả fallback thân thiện cho user.
Bao Mat Khi Dung WordPress AI Client
Vì API key được quản lý tập trung trong WordPress Core, rủi ro lộ key thấp hơn nhiều so với từng plugin tự lưu. Tuy nhiên, vẫn cần lưu ý:
1. Sanitize input trước khi đưa vào prompt: Không bao giờ truyền raw user input thẳng vào wp_ai_client_prompt(). Luôn sanitize:
// Dung wp_kses_post cho HTML content
$safe_content = wp_kses_post( $_POST['content'] );
// Dung sanitize_text_field cho plain text
$safe_title = sanitize_text_field( $_POST['title'] );
// Strip tat ca HTML tags cho plain text prompt
$safe_text = wp_strip_all_tags( $input );2. Gioi han rate call AI: AI API tính tiền theo token. Không để user spam request:
// Gioi han 5 request/gio cho moi user
$user_id = get_current_user_id();
$transient_key = 'ai_rate_' . $user_id;
$count = get_transient( $transient_key );
if ( false === $count ) {
set_transient( $transient_key, 1, HOUR_IN_SECONDS );
} elseif ( $count >= 5 ) {
return new WP_Error( 'rate_limit', 'Vuot qua gioi han 5 request/gio' );
} else {
set_transient( $transient_key, $count + 1, HOUR_IN_SECONDS );
}3. Khong log prompt content vao file: Prompt có thể chứa thông tin nhạy cảm từ post/page. Không ghi vào debug.log hay error_log.
Toi Uu Cost Khi Goi AI API
Mỗi lần gọi generate_text() là một API call tính tiền. Dưới đây là cách mình tối ưu chi phí cho client:
Cache ket qua: Nếu cùng post, không cần generate lại:
$cache_key = 'ai_meta_' . $post_id . '_' . md5( $post->post_modified );
$cached = get_transient( $cache_key );
if ( false !== $cached ) {
return $cached;
}
$result = wp_ai_client_prompt( $prompt )->generate_text();
if ( ! is_wp_error( $result ) ) {
set_transient( $cache_key, $result, DAY_IN_SECONDS );
}
return $result;Chon model re hon cho task don gian: Model như gemini-2.5-flash rẻ hơn nhiều so với gpt-4o. Dùng using_model_preference() để ưu tiên model rẻ cho task đơn giản:
$result = wp_ai_client_prompt( $prompt )
->using_model_preference(
'gemini-2.5-flash',
'claude-3-5-haiku',
'gpt-4o-mini'
)
->generate_text();Gioi han max_tokens: Meta description chỉ cần 50-100 token. Đừng để AI generate 1000 token thừa:
->using_max_tokens( 100 )Ket Qua Thuc Te: Plugin AI Content Builder
Mình đã build plugin hoàn chỉnh sử dụng kiến trúc này: AI Content Builder. Plugin nhận audio file (podcast, voice note), tự động transcript sang text, rồi convert thành blog post với heading, paragraph, bullet list — tất cả structured trong Gutenberg blocks.
Plugin chỉ có hai file chính: ai-content-builder.php (logic PHP) và editor.js (UI trong Block Editor). Tổng dung lượng dưới 20KB. So với plugin AI cũ mình từng maintain nặng 5MB vì bundle OpenAI SDK + Anthropic SDK + Google SDK, đây là sự khác biệt đêm và ngày.
Quy trình plugin hoạt động:
Bước 1: User upload audio file qua media uploader trong Block Editor sidebar.
Bước 2: Plugin gọi wp_ai_client_prompt() với audio file base64, using_temperature(0.1) để transcript chính xác.
Bước 3: Transcript result được truyền vào prompt thứ hai, yêu cầu AI convert thành JSON có schema (title, sections, paragraphs).
Bước 4: Plugin parse JSON, map từng section sang Gutenberg block (<!-- wp:heading -->, <!-- wp:paragraph -->), chèn vào post editor.
Toàn bộ quá trình mất 15-30 giây cho audio 5 phút. Chi phí API khoảng $0.02-0.05 mỗi lần generate.
WordPress AI Client Vs Cach Cu: Bang So Sanh
Để thấy rõ sự khác biệt, so sánh cách cũ và cách mới khi tích hợp AI vào plugin:
Cách cũ (trước WordPress 7.0):
- Nhúng OpenAI PHP SDK: +2MB code
- Viết cURL request riêng cho từng provider
- Quản lý API key trong plugin option riêng
- Xử lý response format khác nhau cho mỗi provider
- Đổi provider = viết lại toàn bộ network logic
- Update SDK liên tục khi provider thay API
Cách mới (WordPress 7.0 AI Client):
- Zero dependency, dùng native WordPress function
- Một interface cho tất cả provider
- API key quản lý tập trung trong Core
- WordPress Core xử lý format conversion
- Đổi provider = không cần đổi code
- WordPress Core update tự động theo provider
Nếu bạn đang maintain plugin AI cũ, đây là lúc migrate. Lợi ích quá rõ ràng để bỏ qua.
WordPress Abilities API Va AI Client: Khac Biet La Gi?
Nhiều người nhầm lẫn AI Client với WordPress Abilities API trong 7.1. Hai thứ này hoàn toàn khác:
AI Client (WP 7.0): giúp plugin GỬI yêu cầu đến AI provider. Plugin là người chủ động gọi AI.
Abilities API (WP 7.1): giúp AI agent ĐỌC và TƯƠNG TÁC với site WordPress. AI bên ngoài (ChatGPT, Claude) kết nối đến site thông qua MCP protocol.
Hai API bổ sung cho nhau: Abilities API cho phép AI agent đọc data site, AI Client cho phép plugin gửi data đến AI để xử lý. Plugin hoàn chỉnh có thể dùng cả hai.
Ket Luan: Bat Dau Build Plugin AI Ngay Hom Nay
WordPress AI Client là thay đổi game cho developer. Nếu bạn đã từng ngại xây dựng plugin AI vì phức tạp của SDK, authentication, vendor lock-in — thì rào cản đó đã biến mất. WordPress 7.0 lo phần nặng nhất, bạn chỉ cần tập trung vào logic nghiệp vụ.
Nếu chưa có WordPress 7.0, tham khảo hướng dẫn cập nhật 7.0.2 an toàn trước. Sau khi update, vào Settings > Connectors cấu hình provider, rồi bắt đầu code. Toàn bộ setup mất dưới 15 phút.
Nếu bạn đang chạy WordPress trên VPS, đừng quên cấu hình Redis Object Cache và tối ưu WP-Cron trước khi chạy AI task nặng. AI generate có thể tốn 10-30 giây PHP execution time, nên đảm bảo server cấu hình max_execution_time tối thiểu 60 giây.
