WoShops AI Connector：一个插件，把十几家大模型接到 WordPress 里 - 吾店云

如果你正为 WordPress 接入大模型而困扰——API Key 散落在各个插件、文档格式不一、流式输出需自行实现 SSE、失败重试缺乏机制，那么这款插件或许能提供一站式解决方案。

WoShops AI Connector（中文名「吾店云 AI Connector」）是由吾店云团队开源的 WordPress 插件，最新版本为 1.1.0。其核心定位是成为 AI 能力的“中央插座”。无论是 DeepSeek、OpenAI、Anthropic Claude、Google Gemini，还是本地运行的 Ollama、Groq，乃至自建的 vLLM / LM Studio，只要遵循 OpenAI 兼容的/chat/completions协议，均可无缝接入。

本文将从开发者和终端站长两个维度，深入解析该插件的技术特性与应用价值。

一、产品定位：AI 能力的连接管理层

WoShops AI Connector 并非传统的“聊天机器人插件”，而是作为底层基础设施存在。它提供配置界面、调用 SDK、REST 接口、PHP 客户端、流式支持及嵌入向量支持，旨在让其他插件或自定义代码能够便捷地调用大模型，而非直接提供前端聊天 UI。

该插件主要服务于两类用户：

1. 站长：希望为站点集成 AI 能力，但避免在每个插件中重复配置 API Key；
2. WordPress 插件开发者：希望在插件中集成 AI 功能，但无需为每家厂商编写单独的适配代码。

二、支持的模型与服务（v1.1.0）

经代码审查，当前版本内置了 13 家厂商的适配支持：

• DeepSeek：V3 / R1 / Chat（OpenAI 兼容）

• OpenAI：GPT-4o、GPT-4o-mini、o1-mini、o3-mini

• Anthropic：Claude Sonnet / Haiku / Opus

• Google：Gemini 2.0 Flash / 2.5 Pro / 2.5 Flash

• Ollama：本地大模型，无需 API Key

• Groq：免费高速推理（Llama / Mixtral / Gemma）

• 通义千问（Qwen）

• 智谱 GLM

• Moonshot（Kimi）

• 豆包（Doubao）

• 百川（Baichuan）

• 零一万物（Yi）

• Custom / OpenAI 兼容：vLLM、LM Studio、Together AI、SiliconFlow 等

核心特性：OpenAI 兼容协议即插即用。 即便使用未列出的国产模型，只要接口规范符合 /chat/completions，即可通过「自定义」通道填入 Base URL 直接使用，无需额外开发。

三、站长视角：零代码配置与管理

1. 安装与激活

• 上传 ai-api-connector 文件夹至 wp-content/plugins/

• 在 WordPress 后台「插件」页面启用

• 进入「设置」→「AI API Connector」进行配置

2. 添加连接（Connection）

UI 采用 WordPress Connectors 卡片式风格，操作直观：

• 选择 Provider（厂商）

• 填写 API Key

• 选择模型或自定义 Base URL

• 一键测试连接（AJAX 异步验证，无需刷新页面）

• 保存配置

3. 全局设置

插件设置页提供以下关键配置：

• 默认连接：当调用方未指定时使用

• Fallback 顺序：主连接故障时自动切换至备用连接

• 请求超时：默认 120 秒，适用于长上下文场景

• 重试次数：默认 2 次

• 启用日志：记录最近 100 次调用详情（含系统/用户提示前 200 字、状态码、响应大小）

4. 安全机制：API Key 存储

• 入库前进行加密处理（base64，若存在 wp_encrypt 则采用更安全方案）

• 后台展示时隐藏完整 Key

• 支持 Multisite 环境下的“网络级默认值 + 子站点覆盖”机制

四、开发者视角：高效集成与调用

4.1 公共 PHP 客户端（推荐）

$client = AI_API_Connector_Client::get_instance();

// 1. 单轮对话
$response = $client->prompt( 'You are helpful.', 'Hello!' );

// 2. 高级选项（温度 / 最大 token / 模型覆盖）
$response = $client->prompt( 'System', 'User', [
    'temperature' => 0.7,
    'max_tokens'  => 4096,
    'connection_id' => 'deepseek-prod',  // 可显式指定连接
] );

// 3. 流式输出（SSE，PHP Generator 实现）
foreach ( $client->prompt_stream( 'System', 'User' ) as $chunk ) {
    echo $chunk;
    flush();
}

// 4. 嵌入向量
$vector = $client->embed( '要嵌入的文本' );

// 5. 测试某个连接是否可用
$result = $client->test_connection( 'connection-id' );

返回值设计遵循 WordPress 规范：成功返回字符串或数组，失败返回 WP_Error，无需引入新的异常处理模型，降低开发门槛。

4.2 REST API（面向前端/第三方系统）

插件自动注册了 5 个端点：

注意：当前版本 REST 端点未包含显式的权限校验回调。若需暴露给前端调用，建议在中间件层增加 nonce + capability 检查，或仅限内部系统使用。这是后续版本优化的重点方向。

4.3 兼容层（老插件兜底方案）

该设计极具人性化。许多旧版 AI 插件硬编码了自身的设置读取逻辑，通过兼容层可实现统一配置：

$info = AI_API_Connector::get_compatibility_layer();
if ( $info ) {
    // 获取当前激活连接的 provider / api_key / base_url / model 供老插件使用
    $provider = $info['provider'];
    $api_key  = $info['api_key'];
    $api_base = $info['api_base'];
    $model    = $info['model'];
}

这意味着可以关闭旧插件独立的 AI 设置，统一在此处配置，实现所有插件共享同一套凭证，有效减少 API Key 的管理混乱。

五、技术架构：通用性的实现原理

该插件采用清晰的策略模式（Strategy Pattern），而非简单的代码复制：

class AI_API_Connector_Provider       ← 抽象基类（接口契约）
    ├── build_chat_request()           ← 构造不同厂商的请求体
    ├── parse_response()               ← 解析不同厂商的响应
    ├── get_auth_header()              ← 处理不同鉴权方式
    ├── get_default_base_url()         ← 设定默认域名
    ├── supports_embedding()           ← 判断是否支持嵌入
    └── ...
        ↓
class Provider_DeepSeek extends ...    ← 13 个具体实现类
class Provider_Anthropic extends ...
class Provider_OpenAI_Compat extends ...  ← 兼容任何 OpenAI 协议方

新增厂商只需编写继承类并补全方法，无需修改核心调度代码，体现了良好的面向对象设计原则。

5.1 自动重试逻辑

prompt() 方法内置指数退避重试机制（固定 1 秒间隔），默认重试 retry_count 次（默认为 2）。网络错误或 5xx 错误会自动重试，4xx 错误（如 401、429）则将上游错误信息透传给调用方。

5.2 流式输出实现

利用 wp_remote_post 的 stream => true 参数，逐行解析 SSE 协议的 data: ... 行。这种实现方式在 WordPress 环境中更为稳定，避免了 PHP-FPM模式下 cURL 回调的兼容性问题。

5.3 Multisite 友好性

ai_api_connector_get_option() 封装函数实现了灵活的配置读取逻辑：

1. 优先读取站点级设置；
2. 若为空，则回退至网络级设置（Multisite 主站统一配置，子站继承）；
3. 子站可单独覆盖，保留个性化配置能力。

这一特性对于运营 SaaS WordPress多站点的用户而言至关重要。

六、快速上手：从零到首次对话

以 DeepSeek 为例，最快 30 秒即可完成接入：

1. 安装并启用插件
2. 进入后台 → Settings → AI API Connector → Add New Connection
3. Provider 选择 DeepSeek
4. 填入从 platform.deepseek.com 获取的 API Key
5. Model 选择 deepseek-chat
6. 点击 Test Connection ，显示 “Connection successful!” 后保存
7. 在任意 PHP 文件中添加以下代码：

add_action( 'wp_ajax_my_chat', function() {
    $client = AI_API_Connector_Client::get_instance();
    $reply  = $client->prompt( '你是一个友好助手', '用一句话介绍你自己' );
    wp_send_json( [ 'reply' => $reply ] );
} );

1. 前端通过 fetch 请求 /wp-admin/admin-ajax.php?action=my_chat 即可获取 AI 回复。

全程无需编写任何厂商特定代码。 若需切换至 Claude，仅需更改 Connection ID，业务代码保持不变。

七、适用人群与场景

八、总结

WoShops AI Connector 并非聊天机器人插件，而是一个专业的 AI 能力连接管理层。

如果您：

• 仅需一个简单的聊天窗口，建议选择其他专用插件；

• 希望为站点或产品接入 AI 能力，并实现 Key、厂商及调用方式的统一管理 ，则该插件是理想选择。

该插件在架构上采用了策略模式 + WordPress 原生习惯 + Multisite 友好的设计，并非简单的代码堆砌。对于致力于在 WordPress 平台上构建严肃 AI 应用的开发者而言，这是一个值得长期依赖的底层基础组件。

当前版本：1.1.0
License：GPL v2 or later
作者：吾店云（woshops.com）