简介

本文件面向DouPHP的AI智能功能开发者，系统性说明后台AI应用管理、提示词组装、内容生成（文本/翻译/批量）、图像生成（含参考图与横幅Banner）、异步任务提交与轮询、用量记录与审计等能力。文档覆盖聊天对话管理、知识库构建、模型调用、响应处理、任务调度、并发控制、结果缓存、错误重试等关键机制，并提供可操作的集成与扩展建议。

项目结构

AI相关代码主要分布在以下位置：

• 配置：AI提示词、图片尺寸策略、Banner素材限制等集中配置
• 控制器：后台AI应用列表、新增/编辑、删除、批量操作等入口
• 服务层：应用策略、提示词组装、生成执行、任务提交、用量记录、批量幂等保护
• 模型：AI应用数据表映射与查询构造器
• 核心网关：AiGateway统一封装不同AI供应商驱动（在core/service/ai中）

graph TB
A["后台控制器<br/>AiController"] --> B["应用服务<br/>ApplicationService"]
B --> C["策略与校验<br/>ApplicationPolicy"]
B --> D["Schema构建<br/>SchemaBuilder(外部)"]
A --> E["任务服务<br/>TaskService"]
E --> F["异步任务仓库<br/>AsyncTaskRepository(外部)"]
A --> G["生成服务<br/>GenerateService"]
G --> H["提示词组装<br/>PromptComposer"]
G --> I["AI网关<br/>AiGateway(外部)"]
G --> J["用量记录<br/>UsageRecorder(外部)"]
G --> K["批量幂等保护<br/>BatchRequestGuard"]
G --> L["批量导入<br/>BatchImportManager(外部)"]

核心组件

• 应用管理：提供AI应用的增删改查、按形态/任务类型筛选、模块字段动态加载、批量操作
• 提示词引擎：按placement/task_type组合system/user消息，注入站点知识、表单快照、用户指令与应用默认要求
• 生成执行：支持assist（单字段）、translate（翻译）、fill（结构化表单）、batch（批量入库）；图像应用走文生图链路
• 任务调度：对长耗时或异步驱动的任务进行提交与状态返回，前端轮询展示
• 并发与幂等：批量生成使用短时文件锁防止重复提交
• 用量与审计：记录每次调用的成功/失败、模型、管理员、IP、元数据与消息摘要

架构总览

整体采用“控制器-服务-网关”分层：

• 控制器负责路由与视图渲染
• 服务层编排业务逻辑（策略、提示词、生成、任务、用量）
• 通过AiGateway统一对接底层驱动（文本/图像/视频），屏蔽供应商差异
• 配置集中管理提示词模板、图片尺寸策略、Banner限制等

sequenceDiagram
participant U as "管理员"
participant C as "AiController"
participant S as "GenerateService"
participant P as "PromptComposer"
participant G as "AiGateway"
participant R as "UsageRecorder"
U->>C : 提交生成请求
C->>S : 调用generateField/generateForm/generateBatch
S->>P : 组装messages/imagePrompt
P-->>S : 返回消息或提示词
S->>G : chat/chatJson/generateImage/submitAsyncTask
G-->>S : 返回{success, data/error}
S->>R : 记录用量与审计
S-->>C : 返回结果或任务信息
C-->>U : 渲染结果或轮询任务

详细组件分析

应用管理与策略

• 列表与分页：支持按placement、task_type、status筛选，并一次查询关联模型名称减少N+1
• 新增/编辑：通过策略校验placement与task_type匹配性、模型是否支持该任务、必填字段约束
• 删除与批量：二次确认、审计日志记录
• 模块字段：按模块名动态返回字段定义，供前端渲染Schema

flowchart TD
Start(["进入应用管理"]) --> List["列表筛选与分页"]
List --> Create{"新增/编辑?"}
Create --> |是| Policy["策略校验<br/>placement-taskType匹配<br/>模型支持任务<br/>必填字段检查"]
Policy --> Save["写入数据库并审计"]
Create --> |否| Delete{"删除/批量?"}
Delete --> Confirm["二次确认"]
Confirm --> Remove["删除并审计"]
Remove --> End(["完成"])
Save --> End

提示词组装与知识库

• 两维选择：按task_type取system提示词，按placement取instruction
• 上下文注入：站点基础信息、表单快照、当前字段值、用户当次要求、应用默认要求
• 图像提示词：banner风格、标题/副标题排版、画布尺寸与裁切区、参考图用法指令

classDiagram
class PromptComposer {
+compose(app, options) array
+instruction(placement, vars) string
+imagePrompt(app, options) string
-formatFormSnapshot(snapshot) string
-bannerTextInstruction(options) string
-bannerLayout(app, options) string
}
class SiteKnowledgeBuilder {
+build() string
}
class PromptCatalog {
+system(task_type) string
+label(key) string
+instruction(placement, vars) string
+bannerStyle(style) string
+bannerMaterial(mode) string
}
PromptComposer --> PromptCatalog : "读取模板与标签"
PromptComposer --> SiteKnowledgeBuilder : "获取站点知识"

生成执行（文本/翻译/批量/图像）

• assist：单字段正文生成，支持图像应用时走文生图链路
• translate：纯文本翻译，保留HTML结构与占位
• fill：按JSON Schema生成结构化字段，返回给前端回填
• batch：生成items数组后批量导入到对应模块，支持异步驱动自动转任务
• 图像应用：尺寸归一化、极端比例裁剪、参考图解析（data URI或附件号转base64）

sequenceDiagram
participant C as "控制器"
participant G as "GenerateService"
participant P as "PromptComposer"
participant GW as "AiGateway"
participant UR as "UsageRecorder"
C->>G : generateField/generateForm/generateBatch
alt 文本路径
G->>P : compose()
P-->>G : messages
G->>GW : chat/chatJson(modelId, messages/schema)
GW-->>G : {success,data/error}
else 图像路径
G->>P : imagePrompt()
P-->>G : prompt
G->>GW : generateImage(modelId, params)
GW-->>G : {success,result}
end
G->>UR : record(result, app_id, admin_id, ip, metadata, messages/prompt)
G-->>C : 返回正文/字段/导入结果/任务信息

异步任务与轮询

• 提交：当目标驱动为异步时，GenerateService/TaskService会提交任务并落账，返回task_id与status
• 轮询：由TaskController直接调用AiGateway::pollAsyncTask（本服务不参与轮询逻辑）
• 列表：支持按status、task_type筛选，聚合模型/供应商/管理员名称

sequenceDiagram
participant UI as "后台界面"
participant TS as "TaskService"
participant GW as "AiGateway"
UI->>TS : submit(appId, prompt, post)
TS->>GW : submitAsyncTask(modelId, {prompt}, meta)
GW-->>TS : {success, task_id, status}
TS-->>UI : 返回任务ID与状态
UI->>GW : pollAsyncTask(task_id)
GW-->>UI : 返回任务结果或进度

并发控制与幂等

• 批量生成指纹：基于管理员、应用、提示词、数量、上下文的哈希作为指纹
• 短时文件锁：防止同一指纹在短时间内重复提交，过期自动释放
• 失败清理：生成失败时主动释放锁，避免死锁

flowchart TD
A["开始批量生成"] --> B["计算指纹"]
B --> C{"获取锁成功?"}
C --> |否| E["拒绝重复提交"]
C --> |是| D["执行生成流程"]
D --> F{"成功?"}
F --> |是| G["释放锁"]
F --> |否| H["释放锁并报错"]
G --> I["结束"]
H --> I
E --> I

图像生成与尺寸归一化

• 尺寸策略：按模型族/供应商预设范围或固定集合归一化，极端比例自动换基础尺寸并记录裁切区
• 参考图：仅当上游支持图生图时解析，支持data URI与附件号转base64，最多4张且单张有限制
• Banner：支持风格、主副标题排版、画布尺寸与裁切区指令

flowchart TD
S["输入size/contentAlign/banner"] --> V["校验size格式与contentAlign"]
V --> R{"极端比例?"}
R --> |是| N["映射到合法gen_size"]
R --> |否| P["保持原尺寸"]
N --> T["计算band_ratio"]
P --> T
T --> M["解析参考图(若支持)"]
M --> Q["组装imagePrompt"]
Q --> O["调用generateImage"]

依赖关系分析

• 控制器依赖服务层，服务层依赖策略、提示词、网关、仓库、记录器等
• 模型提供数据访问与查询构造器
• 配置集中管理提示词与图片策略

graph LR
AC["AiController"] --> AS["ApplicationService"]
AC --> GS["GenerateService"]
AC --> TS["TaskService"]
AS --> AP["ApplicationPolicy"]
GS --> PC["PromptComposer"]
GS --> AG["AiGateway"]
GS --> BRG["BatchRequestGuard"]
TS --> AR["AsyncTaskRepository"]
AS --> AM["AiApplication"]

性能与成本优化

• 批量上限与策略：通过策略限制批量条数，避免单次过大请求导致超时或高成本
• 尺寸归一化：将非标准尺寸映射到模型支持范围，减少失败重试与无效调用
• 异步任务：长耗时任务自动转异步，提升用户体验并降低同步阻塞
• 用量记录：每次调用记录成功/失败、模型、管理员、IP、元数据与消息摘要，便于成本核算与质量监控
• 并发保护：短时文件锁防止重复提交，降低重复成本与资源浪费

故障排查指南

• 应用未找到或状态异常：检查应用是否存在、状态是否为启用、placement是否与请求匹配
• 模型与任务不匹配：检查task_type与model_code/provider_code是否满足媒体/文本任务约定
• 提示词为空：图像应用需确保最终提示词非空，否则抛出错误
• 批量重复提交：检查短时锁是否被占用，必要时清理缓存目录中的锁文件
• 参考图解析失败：确认上游支持图生图、文件存在且大小不超过限制、路径正确

结论

DouPHP的AI智能功能以清晰的分层与策略化设计，实现了文本生成、翻译、批量入库与图像生成的完整闭环。通过提示词引擎、尺寸归一化、异步任务、用量记录与并发保护，兼顾了易用性、稳定性与成本控制。开发者可在此基础上扩展新的AI工作流、接入更多供应商、定制提示词与策略，以满足多样化业务需求。

附录：集成与扩展指南

• 集成不同AI供应商

  • 通过AiGateway统一接口调用chat/chatJson/generateImage/submitAsyncTask，无需修改上层服务
  • 在配置中声明模型代码、供应商代码与图片尺寸策略，确保策略与驱动一致
  • 参考路径：admin/service/ai/GenerateService.php:102-786、config/ai.php:100-166

• 自定义AI工作流

  • 在GenerateService中新增方法，复用PromptComposer与AiGateway，结合策略与用量记录
  • 如需异步，遵循submitAsyncIfNeeded模式，返回任务信息供前端轮询
  • 参考路径：admin/service/ai/GenerateService.php:758-786

• 扩展AI功能模块

  • 新增模块字段：通过SchemaBuilder与模块字段接口动态返回字段定义
  • 新增批量导入：实现BatchImportManager的supports/import接口
  • 参考路径：admin/service/ai/ApplicationService.php:340-347

• 提示词与知识库

  • 在config/ai.php中维护system/instruction/labels/banner_styles等模板
  • 通过SiteKnowledgeBuilder注入站点基础信息，增强生成相关性
  • 参考路径：config/ai.php:31-98、admin/service/ai/Prompt/PromptComposer.php:51-288

• 性能与成本监控

  • 利用用量记录与审计日志分析调用量、成功率、失败原因
  • 调整批量上限、尺寸策略与异步阈值，平衡体验与成本
  • 参考路径：admin/service/ai/GenerateService.php:131-156、config/ai.php:100-166