为什么需要在 WordPress 中接入 OpenAI API？

WordPress 是服务端渲染的 PHP 系统，适合在服务端调用外部 API。接入 OpenAI 后，你可以为站内增加 AI 聊天、内容摘要、标题建议、标签生成、文章嵌入向量等功能。与直接在前端脚本调用相比，在 WordPress 中集成可以更安全地保管密钥，并在服务器端统一处理错误和缓存。

教程前提

• 一个可访问后台的 WordPress 站点，运行 PHP 7.4 或更高版本。
• 拥有一个 OpenAI 账号，并在 platform.openai.com 中创建 API Key。这个 API Key 是用来调用付费的 gpt、embedding 等模型接口的凭证。
• 了解基本的 PHP、WordPress 主题或插件开发，会知道如何向 functions.php 或插件文件添加代码。

提醒：OpenAI API 按 token 用量计费，调用价格、模型列表和速率限制会调整。所有费用信息和最新接口文档请以 OpenAI 官网为准。不要把真实的 API Key 发布到公开仓库或前端页面中。

第一步：把密钥放在安全位置

我不建议把 API Key 直接写在前端 JavaScript 或者主题后台选项里。你可以在服务器端的 wp-config.php 中定义常量，使用方法如下：

define( ‘MY_SITE_OPENAI_API_KEY’, ‘sk-这里换成你的密钥’ );

同时可以定义一个默认模型常量，例如：

define( ‘MY_SITE_OPENAI_MODEL’, ‘gpt-3.5-turbo’ );

如果你的代码部署在多个环境，也可以使用系统环境变量代替常量，但核心原则是内容不能出现在公开产物中。

第二步：创建自定义文件还是插件

直接向主题的 functions.php 中添加代码可能最简单，但当你切换主题时，AI 功能就会失效。更稳定的小项目方式是在 wp-content/plugins/ 下新建一个文件夹，例如 my-openai-tools，在里面创建入口文件my-openai-tools.php，并写上插件头声明，然后启用插件。

你最终要封装一个函数，把向 OpenAI 发送对话请求的细节统一起来。下面是用 WordPress 内置函数发起请求的核心结构：

$response = wp_remote_post( ‘https://api.openai.com/v1/chat/completions’, array( ‘headers’ => array( ‘Content-Type’ => ‘application/json’, ‘Authorization’ => ‘Bearer ‘ . $api_key ), ‘body’ => wp_json_encode( array( ‘model’ => $model, ‘messages’ => $messages, ‘temperature’ => 0.7 ) ), ‘timeout’ => 30 ) );

上述代码把请求发送到 Chat Completions 端点，然后用 wp_remote_retrieve_body( $response ) 读取返回结果。这个函数可以继续包含以下判断：

• 如果 $response 是 WP_Error，立即返回该错误对象；
• 如果响应码不是 200，使用 wp_remote_retrieve_response_code() 取得状态码并记录到日志；
• 把响应正文用 json_decode 转换为数组，再将 $body[‘choices’][0][‘message’][‘content’] 返回给调用方。

这样你以后无论做聊天还是摘要，都可以复用这个请求层。

第三步：为前台提供 REST API

如果你打算让网站访客点击按钮后得到一段回答，建议不要在页面加载时直接同步调用 OpenAI。可以先给前端提供一个 REST API 端点，让浏览器通过异步请求调用。

注册端点的函数是 register_rest_route()。比如你想创建一个 mwai/v1/ask 的 POST 端点，可以在插件中使用如下代码：

register_rest_route( ‘mwai/v1’, ‘/ask’, array( ‘methods’ => ‘POST’, ‘permission_callback’ => function( $request ) { return is_user_logged_in(); }, ‘callback’ => ‘mwai_handle_ask’ ) );

上面的 permission_callback 表示只有登录用户能访问。如果你的场景需要公开访问，可以换成其他频率限制方案，一定不要直接用 return true 就结束。

请求参数建议至少包含：

在回调函数 mwai_handle_ask() 中，你从 $request->get_param() 获取参数，再组装 $messages 数组，例如：

$messages = array( array( ‘role’ => ‘system’, ‘content’ => ‘你是一个网站智能助手。’ ), array( ‘role’ => ‘user’, ‘content’ => $message ) );

调用上一步封装好的请求函数后，把文本以 JSON 结构返回。前端就能拿到结果。

第四步：错误状态与超时建议

外部 API 必定会出现异常。Chat Completions 通常通过 HTTP 状态码反馈情况，你可以用 WordPress 的 wp_remote_retrieve_response_code() 判断：

• 200：请求成功；
• 401：API Key 错误；
• 429：速率限制或账户异常；
• 500/503：OpenAI 临时服务问题。

遇到 401、429 等情况时，应优先给终端用户一个可控的提示，不要直接透出内部错误对象。

设置 timeout 参数很重要，推荐设为 20 到 60 秒之间。还要注意你的 Web 服务器和 PHP 的 max_execution_time 限制。对于长时间任务，最好使用 WordPress 的 scheduled event 或后台异步处理，以避免用户等待整个页面。

第五步：扩展现有站内功能

批量生成文章摘要

你可以遍历文章正文并截取前几个段落，交给模型做摘要。要注意控制文本长度，不同模型的最大 token 不同。建议先用 wp_strip_all_tags() 删除 HTML，再使用 mb_substr() 切分文本。

摘要的结果可以存到文章的 meta 字段中，并在模板中调用展示。

给评论或用户查询做内容摘要

与文章摘要类似，把用户输入合并到一个上下文中，然后要求模型只输出精简的结论。可以在系统消息中指定格式，比如“请用一两句话回答”。

加入文本嵌入与相似搜索

Embeddings 模型可以把一段文本生成为一个向量。调用地址是 https://api.openai.com/v1/embeddings。请求参数包括所选 embeddings 模型名称和 input 文本。输入文本通常需要传输为字符串。

得到向量后，你需要把它保存到数据库，例如某个自定义数据表或作为文章 meta。在站内搜索时，再把查询词转成同一模型的向量，计算与文章向量的余弦相似度。向量维度取决于模型，不同模型之间不能混用。

只插入这段说明并不等于完成嵌入功能，但这是你自行开发时需要理解的最小流程：先建立索引，再查询向量，最后按相似度排序。

常见安全与成本问题

• 不要把 API Key 放进主题 JS 文件或任何公开 CSS/JS 资源中。
• 如果有用户提交的 prompt，服务端要加以限制，并允许管理员禁用某些危险指令。虽然你无法完全防止 prompt 注入，但可以限制用户消息的长度和频率。
• 同一请求可能非常消耗 token，请对每个用户设定的次数上限；否则被恶意调用可能造成费用失控。
• 使用 Transients 或对象缓存来保存相同的提问或摘要结果，减少重复调用。

发布前的简单测试流程

1. 先在本地或测试站启用插件，用开发者工具或 curl 测试 REST API。
2. 确认没有在页面源码中出现 sk- 开头的字符串。
3. 制造一次错误响应（例如临时改错 API Key），检查前端提示是否友好。
4. 使用不同长度文本测试摘要或聊天，确认不会超时。
5. 开启 WordPress 日志，观察 429 和 500 的错误频率。

以上流程可以帮你发现接口层、权限层和超时层的问题。

小结

让 WordPress 真正拥有 OpenAI 能力时，你不需要依赖复杂的可视化拖拽工具。只需要在服务端封装一个请求层、注册一个可安全访问的接口，并写清模型与错误处理，就可以接出聊天、摘要或嵌入能力。

本教程只展示了关键路径。由于 OpenAI 的模型和接口时刻变化，建议在编写代码后，以 OpenAI 的官方 API 参考文档为准。