Ai 模块

Ai 是一个独立的 ZTBCMS 模块，用于调用 OpenAI Chat Completions 兼容接口。模块支持供应商分组、随机选择模型、指定供应商模型、请求日志、调用统计和日志清理。

安装

php think module:install ai
cp app/ai/config/ai_provider.php config/ai_provider.php

模块安装不会自动复制配置文件，请手动复制后再填写供应商配置。

环境变量示例

[AI]
VOLCENGINE_BASE_URL=https://ark.cn-beijing.volces.com/api/v3
VOLCENGINE_KEY=ark-xxx

QINIU_BASE_URL=https://api.qnaigc.com/v1
QINIU_KEY=sk-xxx

base_url 配置到 API 根路径即可，模块会自动请求 {base_url}/chat/completions。 火山方舟的 API Key 通常是 ark- 开头。 火山方舟的 model 需要填写方舟控制台可调用的模型 ID，例如 doubao-seed-2-0-lite-260215。

配置说明

配置文件位于：

config/ai_provider.php

主要配置：

• timeout：请求超时时间，默认 30 秒。
• logging.record_success：是否保存成功请求的摘要详情，默认关闭。
• logging.record_failure：是否保存失败请求的摘要详情，默认开启。
• logging.retention_days：日志保留天数，默认 30 天。
• providers：供应商配置。
• groups：模型分组配置。

为了保证调用统计准确，模块会为成功请求写入轻量日志记录；record_success=false 时不会保存请求和响应摘要。

group() 和 provider() 是互斥的选择方式，链式调用时以后设置的方式为准。调用 group() 会清空已设置的供应商和模型；调用 provider() 会清空已设置的分组。

默认分组调用

use app\ai\libs\Agent;

$response = Agent::prompt('你好，请简单介绍你自己');
$content = $response->content();

指定分组随机调用

use app\ai\libs\Agent;

$response = Agent::group('fast')->prompt('请总结这段公告正文');
$content = $response->content();

指定供应商和模型

use app\ai\libs\Agent;

$response = Agent::provider('aliyun')
    ->model('deepseek-v4-flash')
    ->prompt('请提取公告标题中的地区');

带上下文和场景

use app\ai\libs\Agent;
use app\ai\libs\Message;

$response = Agent::group('fast')
    ->scene('notice_recognition')
    ->context([
        Message::system('你是公告信息识别助手'),
        Message::user('标题：2026年广州市事业单位公开招聘公告'),
    ])
    ->prompt('请识别分类、地域、开始时间和结束时间');

$content = $response->content();

scene 只用于日志和统计，不会发送给模型。

JSON 返回

use app\ai\libs\Agent;

$response = Agent::group('fast')->prompt('请用 JSON 返回结果', [
    'temperature' => 0.2,
    'response_format' => ['type' => 'json_object'],
]);

$json = $response->content();

查看日志和统计

安装模块后，后台会新增：

• AI 管理 / 请求日志
• AI 管理 / 调用统计

请求日志用于排查单次调用，默认只查询当日数据。调用统计读取每日统计表，不直接扫描请求日志明细表，统计数据最多延迟 30 分钟。

计划任务

模块安装时会写入两个计划任务：

• AI 请求统计汇总：建议每 30 分钟执行一次。
• AI 请求日志清理：建议每天凌晨 3 点执行一次。

可手动执行：

php think cron:exec --class "app\\ai\\cronscript\\AggregateAiRequestStatScript"
php think cron:exec --class "app\\ai\\cronscript\\CleanAiRequestLogScript"

注意事项

• 本模块只支持 OpenAI Chat Completions 兼容接口。
• 本模块不支持流式输出、工具调用、文件、多模态、自动重试和权重分配。
• 供应商分组使用简单随机选择。
• 不要把 key 写入代码，建议统一放到 .env。