简介

本文件面向DouPHP框架的AI智能服务，覆盖智能聊天、图像生成、内容创作辅助等能力。文档从系统架构、组件职责、数据流、提示词管理、任务调度、结果处理、第三方平台集成（API密钥、限流熔断、错误重试）等方面展开，并提供可在业务中直接参考的调用路径与使用建议。

项目结构

AI能力在后台模块中以“应用配置—运行时生成—网关驱动”的分层组织：

• 配置层：集中定义提示词模板、图像尺寸策略、素材限制等。
• 控制与服务层：提供AI应用管理、表单填充、批量生成、字段辅助、翻译、异步任务提交与查询。
• 网关与驱动层：统一解析模型/供应商/密钥，封装对话与图像/视频生成，支持同步与异步两种模式。
• 前端交互：提供密钥重置、任务状态展示等界面逻辑。

graph TB
subgraph "后台管理"
AC["AiController"]
ASvc["ApplicationService"]
GSvc["GenerateService"]
TSvc["TaskService"]
PC["PromptComposer"]
end
subgraph "AI网关与驱动"
GW["AiGateway"]
OF["OpenAiDriver"]
BD["BailianDriver"]
AP["AsyncTaskPoller"]
end
subgraph "外部平台"
OAI["OpenAI/DALL·E/CogView"]
DS["阿里百炼(DashScope)"]
end
AC --> ASvc
AC --> GSvc
AC --> TSvc
GSvc --> PC
GSvc --> GW
TSvc --> GW
GW --> OF
GW --> BD
GW --> AP
OF --> OAI
BD --> DS

核心组件

• 配置中心（config/ai.php）：集中管理提示词体系（system/instruction/labels/banner_styles）、图生图支持的模型通配、图像尺寸归一化策略、横幅素材上限与上传大小限制。
• 应用管理（ApplicationService）：负责AI应用的列表、新增、编辑、删除、批量操作，以及按形态/任务类型校验与字段白名单约束。
• 运行时生成（GenerateService）：实现assist/fill/batch/translate/image/banner等场景；组装提示词、调用网关、记录用量、处理同步/异步结果。
• 异步任务（TaskService）：提交异步任务、分页查询、删除终态任务。
• 提示词编排（PromptComposer）：按placement/task_type拼装system/user消息或单段图像prompt，注入站点知识、表单快照、用户要求等。
• 网关与驱动（AiGateway + Drivers）：解析模型/供应商/密钥，选择驱动，执行对话/图像/视频生成；支持同步直出与异步轮询。

架构总览

AI服务采用“控制器—服务—网关—驱动—外部平台”的分层架构，关键流程如下：

• 文本生成：控制器接收请求 → GenerateService组装提示词 → AiGateway选择驱动 → 调用外部平台 → 返回结果并记录用量。
• 图像生成：GenerateService构建图像prompt与尺寸参数 → AiGateway根据驱动能力走同步或异步路径 → 同步直出或异步轮询获取结果。
• 异步任务：TaskService提交任务 → AsyncTaskPoller维护任务生命周期 → 前端轮询查看状态与结果。

sequenceDiagram
participant U as "管理员/业务端"
participant C as "AiController"
participant S as "GenerateService"
participant P as "PromptComposer"
participant G as "AiGateway"
participant D as "驱动(OpenAI/百炼)"
participant R as "外部平台"
U->>C : 发起生成请求
C->>S : 调用generateField/generateForm/generateBatch
S->>P : 组装messages或image prompt
P-->>S : 返回消息/提示词
S->>G : chat/chatJson/generateImage/submitAsyncTask
G->>D : 选择驱动并发送请求
D->>R : 调用第三方API
R-->>D : 返回结果
D-->>G : 标准化响应
G-->>S : 成功/失败
S-->>C : 业务结果(文本/图片/任务ID)
C-->>U : 渲染页面或返回JSON

详细组件分析

应用管理与策略（ApplicationService）

• 列表与筛选：按placement/task_type/status过滤，聚合模型名称，分页返回。
• 新增/编辑：通过表单校验后写入，应用“形态-任务-模型”一致性策略，确保assist/translate不挂载模块，fill/batch必须指定模块与字段。
• 删除与批量：二次确认与批量删除，审计日志记录。

flowchart TD
Start(["进入应用管理"]) --> List["列表筛选与分页"]
List --> Create["新增/编辑表单"]
Create --> Policy{"形态-任务-模型匹配?"}
Policy --> |否| Err["抛出错误"]
Policy --> |是| Save["保存并记录审计"]
Save --> Delete["删除/批量删除"]
Delete --> End(["完成"])

运行时生成（GenerateService）

• assist：文本字段辅助生成，或图像应用走文生图链路，返回任务结果数组供前端展示。
• fill：按模块Schema生成整表单字段值，供前端回填。
• batch：结构化生成items数组，经导入管理器入库。
• translate：纯文本翻译，返回译文。
• 提示词预览：仅组装不下发模型，便于调试。
• 异步提交：当目标驱动为异步时，立即返回任务信息，由前端轮询。

sequenceDiagram
participant FE as "前端"
participant GS as "GenerateService"
participant PC as "PromptComposer"
participant GW as "AiGateway"
participant DR as "驱动"
FE->>GS : generateField/generateForm/generateBatch
GS->>PC : compose/imagePrompt
PC-->>GS : messages/prompt
alt 文本生成
GS->>GW : chat/chatJson
else 图像生成
GS->>GW : generateImage
end
GW->>DR : 调用具体驱动
DR-->>GW : 返回结果
GW-->>GS : 标准化响应
GS-->>FE : 文本/图片URL/任务ID

提示词管理（PromptComposer）

• 文本消息：按task_type取system，user消息包含站点知识、表单快照、当前字段、用户要求与应用默认提示。
• 图像提示：将任务基调、banner样式/标题/素材用法、表单主题、用户要求拼接为单段prompt。
• instruction：为异步任务提供兜底指令。

异步任务（TaskService）

• 提交：校验应用状态，构造prompt与透传参数（size/width/height/duration/resolution），调用网关提交异步任务。
• 列表：分页查询任务，补齐模型/供应商/管理员名称映射。
• 删除：仅可删除终态任务，二次确认后删除。

网关与驱动（AiGateway, OpenAiDriver, BailianDriver）

• 配置解析：按模型→供应商→密钥→端点顺序解析，自动加密迁移密钥，计算驱动标识与端点路径。
• 对话与结构化输出：chat/chatJson，支持JSON Schema强约束（由供应商声明）。
• 图像生成：统一入口，优先同步驱动，失败时尝试移除尺寸重试；若驱动支持异步则走异步提交。
• 异步任务：通过AsyncTaskPoller提交并维护任务状态。

classDiagram
class AiGateway {
+resolveConfig(modelId)
+getModel(id)
+getDefaultModel()
+getAvailableKey(providerId)
+chat(messages, modelId)
+chatJson(messages, schema, modelId)
+generateImage(modelId, params, meta)
+submitAsyncTask(modelId, params, meta)
}
class OpenAiDriver {
+generateImage(config, params)
}
class BailianDriver {
+generateImage(config, params)
}
class AsyncTaskPoller {
+submit(config, params, meta)
}
AiGateway --> OpenAiDriver : "选择驱动"
AiGateway --> BailianDriver : "选择驱动"
AiGateway --> AsyncTaskPoller : "异步任务"

依赖关系分析

• 控制器依赖服务：AiController依赖ApplicationService、GenerateService、TaskService。
• 服务依赖网关与工具：GenerateService依赖PromptComposer、SchemaBuilder、UsageRecorder、ImportManager、ApplicationPolicy、BatchRequestGuard。
• 网关依赖驱动与任务轮询：AiGateway通过DriverFactory路由到具体驱动，并通过AsyncTaskPoller管理异步任务。
• 外部依赖：OpenAI/DALL·E/CogView、阿里百炼(DashScope)等第三方平台。

graph LR
AC["AiController"] --> ASvc["ApplicationService"]
AC --> GSvc["GenerateService"]
AC --> TSvc["TaskService"]
GSvc --> PC["PromptComposer"]
GSvc --> GW["AiGateway"]
TSvc --> GW
GW --> OF["OpenAiDriver"]
GW --> BD["BailianDriver"]
GW --> AP["AsyncTaskPoller"]

性能与可靠性

• 提示词优化：PromptComposer将站点知识、表单快照、用户要求分段注入，避免冗余上下文，降低token消耗。
• 图像尺寸归一化：按模型族与协议默认策略归一化尺寸，极端比例自动换基础尺寸出图，减少上游拒绝率。
• 密钥轮换与熔断：AiGateway按failure_count与冷却时间选择可用密钥，达到阈值自动熔断，避免雪崩。
• 异步任务：长耗时任务通过异步提交与轮询，避免阻塞请求线程，提升吞吐。
• 批量防重：BatchRequestGuard基于指纹防止重复提交，保障幂等性。

故障排查指南

• 无模型配置：检查模型是否启用且存在可用密钥；查看AiGateway::resolveConfig返回值。
• 图像生成失败：关注尺寸被拒时的重试逻辑；必要时移除size参数重试。
• 异步任务无provider_task_id：检查驱动提交结果，失败会标记为failed并记录错误。
• 密钥失败计数过高：可通过前端重置按钮重置失败计数，恢复该密钥可用性。
• 提示词为空：图像应用需确保prompt非空；文本应用检查assemble后的messages。

结论

DouPHP的AI智能服务以清晰的分层与解耦设计，实现了文本生成、图像生成、内容创作辅助等能力。通过提示词编排、尺寸归一化、密钥熔断与异步任务机制，系统在稳定性与性能上具备良好表现。结合第三方平台的驱动适配，可灵活扩展更多AI能力。

附录：集成示例与最佳实践

• 文本字段辅助（assist）

  • 调用路径：AiController → GenerateService::generateField
  • 关键点：传入field、currentValue、formSnapshot、currentModule；文本应用返回正文。
  • 参考：admin/service/ai/GenerateService.php:215-259

• 表单填充（fill）

  • 调用路径：AiController → GenerateService::generateForm
  • 关键点：按模块Schema生成字段值，返回键值对供前端回填。
  • 参考：admin/service/ai/GenerateService.php:167-194

• 批量生成（batch）

  • 调用路径：AiController → GenerateService::generateBatch
  • 关键点：生成items数组后经导入管理器入库；注意批量防重与数量限制。
  • 参考：admin/service/ai/GenerateService.php:102-156

• 翻译（translate）

  • 调用路径：AiController → GenerateService::generateTranslate
  • 关键点：source_text与target_lang必填；返回译文。
  • 参考：admin/service/ai/GenerateService.php:601-633

• 图像生成（image/banner）

  • 调用路径：AiController → GenerateService::generateField（图像应用）
  • 关键点：构建prompt与尺寸；同步直出或异步任务；banner支持风格与素材用法。
  • 参考：admin/service/ai/GenerateService.php:284-326
  • 参考：_'/module/ai/core/service/ai/AiGateway.php:582-694

• 异步任务提交与轮询

  • 提交：TaskService::submit → AiGateway::submitAsyncTask → AsyncTaskPoller::submit
  • 轮询：前端按task_id查询任务状态与结果。
  • 参考：admin/service/ai/TaskService.php:70-105
  • 参考：core/service/ai/Task/AsyncTaskPoller.php:118-146

• 第三方平台集成要点

  • API密钥管理：AiGateway自动解密与加密迁移，选择可用密钥，失败计数熔断。
  • 请求限流与重试：驱动侧按平台协议处理；图像生成失败时尝试移除size重试。
  • 错误处理：统一返回success/error，上层抛出DomainException并记录日志。
  • 参考：_'/module/ai/core/service/ai/AiGateway.php:66-88
  • 参考：_'/module/ai/core/service/ai/AiGateway.php:763-807