简介

本文件面向AI应用开发者，系统化梳理本项目中AI能力相关的API与实现要点，覆盖以下方面：

• 智能聊天：对话发送、消息接收、上下文拼装与提示词模板。
• 图像生成：提示词构建、尺寸归一化、参考图处理、结果返回与任务轮询。
• 健康检测：系统状态监控、指标采集与健康检查入口。
• AI任务管理：任务提交、状态查询、产物获取、删除等。
• 模型配置与管理：供应商、密钥、模型元数据增删改查与启用切换。
• 容错机制：限流、熔断、降级策略在关键路径中的体现。
• 性能优化：异步驱动、白名单透传、批量去重、图片安全校验等。

项目结构

AI相关能力主要分布在后台控制器与服务层，并通过统一的网关与驱动抽象对接外部AI服务；健康模块提供独立的健康档案与小程序入口。

graph TB
subgraph "后台"
AC["AiController"]
TC["TaskController"]
MC["ModelController"]
HC["HealthController(后台)"]
end
subgraph "服务层"
GS["GenerateService"]
TS["TaskService"]
HS["HealthService"]
end
subgraph "核心网关"
AG["AiGateway"]
DR["DriverFactory / AsyncDriverInterface"]
end
subgraph "配置"
CFG["ai.php"]
end
AC --> GS
TC --> TS
MC --> |"增删改供应商/密钥/模型"| MC
TC --> AG
GS --> AG
TS --> AG
AG --> DR
GS --> CFG
TC --> CFG
HC --> HS

核心组件

• 应用与提示词编排：通过应用配置（placement/task_type）与内置提示词模板组装消息，支持文本/翻译/表单填充/批量生成。
• 图像生成流水线：提示词构建、尺寸归一化、参考图解析、调用文生图驱动，统一返回任务结果供前端轮询或同步展示。
• 异步任务：基于驱动是否实现异步接口自动选择同步/异步路径，并提供任务提交、轮询、产物下载、删除等能力。
• 模型与供应商管理：以供应商为主键组织密钥与模型行，支持批量增改、启用/停用、事务性写入。
• 健康检测：提供后台健康档案管理与小程序端入口，便于业务侧接入健康检查。

架构总览

AI能力通过“控制器→服务→网关→驱动”的分层设计解耦业务与外部AI服务，同时以配置集中管理提示词、图像尺寸策略与素材限制。

sequenceDiagram
participant FE as "前端/客户端"
participant C as "TaskController"
participant S as "TaskService"
participant G as "AiGateway"
participant D as "驱动(同步/异步)"
participant R as "任务存储"
FE->>C : POST 提交任务(app_id, prompt, 可选size/width/height/duration/resolution)
C->>S : submit(app_id, prompt, admin_id, post)
S->>G : submitAsyncTask(model_id, params, meta)
alt 驱动为异步
G-->>S : {success : true, task_id, status}
S-->>C : {task_id, status}
C-->>FE : JSON 返回任务ID与状态
else 驱动为同步
G->>D : 直接调用并返回结果
D-->>G : 成功/失败
G-->>S : {success, data/error}
S-->>C : 结果
C-->>FE : JSON 返回内容或错误
end

详细组件分析

智能聊天与上下文管理

• 提示词模板与标签：按任务形态（assist/polish/rewrite/image/banner/translate/fill/batch）与放置位（assist/translate/fill/batch）组合生成消息。
• 上下文拼装：站点基础信息、表单快照、当前字段值、用户要求等段落由提示词编排器注入。
• 输出契约：结构化输出使用Schema约束（fill/batch），纯文本场景直接返回正文。

flowchart TD
A["输入: app_id, placement, user_prompt"] --> B["加载应用与模型配置"]
B --> C{"是否图像应用?"}
C -- 否 --> D["组装messages(system/user/labels)"]
D --> E["调用chat/chatJson"]
E --> F{"成功?"}
F -- 是 --> G["记录用量并返回content/data"]
F -- 否 --> H["抛出错误"]
C -- 是 --> I["构建图像提示词+尺寸归一化+参考图"]
I --> J["调用generateImage或submitAsyncTask"]
J --> K["返回任务结果或图片数据"]

图像生成功能

• 提示词构建：根据banner风格、目标尺寸、内容对齐、参考图用法等注入指令。
• 尺寸归一化：按模型族/供应商策略将极端比例映射为合法预设，必要时回退默认尺寸。
• 参考图处理：仅当上游支持图生图时解析data URI或本地附件为base64载体，限制数量与大小。
• 结果返回：同步驱动直接返回图片数据；异步驱动返回任务ID与状态，前端轮询获取产物。

sequenceDiagram
participant UI as "前端弹窗"
participant GS as "GenerateService"
participant GW as "AiGateway"
participant DR as "驱动"
UI->>GS : generateField(field, snapshot, size, banner)
GS->>GS : buildImagePrompt(尺寸/风格/参考图)
GS->>GW : generateImage(model_id, params)
alt 同步驱动
GW->>DR : 文生图请求
DR-->>GW : 图片数据
GW-->>GS : {success, data}
GS-->>UI : 图片数据
else 异步驱动
GW->>DR : 提交任务
DR-->>GW : {task_id, status}
GW-->>GS : 任务结果
GS-->>UI : {task_id, status}
end

AI任务管理

• 提交任务：校验应用与提示词，白名单透传参数（size/width/height/duration/resolution），交由网关提交。
• 轮询状态：直接调用网关轮询，终态成功时补记用量。
• 产物获取：仅从任务结果中解析URL或data URI，服务端代取并做类型/大小校验后返回base64。
• 删除任务：二次确认，终态可删。

sequenceDiagram
participant FE as "前端"
participant TC as "TaskController"
participant TS as "TaskService"
participant AG as "AiGateway"
FE->>TC : GET show?id=taskId
TC->>AG : pollAsyncTask(taskId)
AG-->>TC : {status, success, error?}
alt 成功且succeeded
TC->>TS : findTask(taskId)
TC->>TC : recordAsyncTaskSuccess(task, ip)
end
TC-->>FE : JSON 任务状态

健康检测功能

• 后台健康档案：列表、详情、状态切换、允许编辑开关、随访记录CRUD、字段配置。
• 小程序入口：健康模块入口控制器用于路由收录与兜底响应。

flowchart TD
H1["HealthController(后台)"] --> H2["HealthService.buildHealthListData"]
H1 --> H3["HealthService.buildHealthViewData"]
H1 --> H4["HealthService.delete / action"]
H1 --> H5["HealthService.followupAdd/Update/Delete"]
H1 --> H6["HealthService.fieldStore/Update/Delete"]
API["HealthController(API)"] --> |index| RESP["返回空成功响应"]

模型配置与管理

• 供应商维度管理：列表、新增、编辑、删除、批量操作。
• 密钥与模型行式表格：随表单统一提交，单事务内处理供应商、密钥、模型的增改删。
• 启用/停用：行内快捷切换供应商状态。

classDiagram
class ModelController {
+index(request) Response
+create() Response
+store(formRequest, request) Response
+edit(request) Response
+update(formRequest, request) Response
+destroy(request) Response
+action(request) Response
+toggleStatus(request) Response
}

依赖关系分析

• 控制器依赖服务：AiController→ApplicationService；TaskController→TaskService；ModelController→ModelService；HealthController→HealthService。
• 服务依赖网关与驱动：GenerateService/TaskService→AiGateway→DriverFactory/AsyncDriverInterface。
• 配置集中：ai.php提供提示词、图像尺寸策略、素材上限等全局配置。

graph LR
AC["AiController"] --> ASvc["ApplicationService"]
TC["TaskController"] --> TSvc["TaskService"]
MC["ModelController"] --> MSvc["ModelService"]
HC["HealthController"] --> HSvc["HealthService"]
TSvc --> AG["AiGateway"]
ASvc --> AG
AG --> DF["DriverFactory / AsyncDriverInterface"]
TSvc --> CFG["ai.php"]
ASvc --> CFG

性能与资源管理

• 异步优先：对图像/视频等长耗时任务，若驱动实现异步接口则自动走异步路径，降低阻塞。
• 白名单透传：仅允许size/width/height/duration/resolution等受控参数透传给驱动，避免任意参数注入。
• 批量去重：批量生成前基于指纹防重复提交，避免重复计算与入库。
• 图片安全：产物下载严格校验MIME、大小与格式，防止SSRF与恶意文件注入。
• 尺寸归一化：按模型族/供应商策略将非标准尺寸映射为合法预设，减少失败重试。
• 用量记录：所有生成路径均记录用量，便于成本核算与限流策略依据。

故障排查指南

• 任务提交失败：检查应用是否存在且启用、提示词是否为空、模型是否支持该任务类型。
• 轮询失败：确认任务ID有效、任务处于终态后再读取产物；注意网络超时与远程地址策略。
• 图片下载失败：校验URL来源是否来自任务结果、MIME是否为image/*、大小是否超限、格式是否受支持。
• 批量生成重复：检查指纹是否命中去重锁；失败会释放锁，需重试。
• 模型不匹配：应用绑定的模型不支持所选任务类型时会拒绝执行。

结论

本项目AI能力采用清晰的分层架构与可插拔驱动设计，结合集中化的提示词与图像尺寸配置，实现了文本生成、翻译、表单填充、批量生成与图像生成的完整链路。通过异步优先、白名单透传、批量去重与安全校验等手段，兼顾了性能与安全性。健康模块提供了独立的档案管理与小程序入口，便于业务扩展。建议在实际集成中关注用量记录与限流策略，结合驱动特性选择合适的同步/异步路径，以获得更稳定的用户体验。

附录：接口清单

以下为与AI能力直接相关的后端接口概览（路由命名来源于控制器注释与方法名）：

• AI应用管理
  • 列表/创建/编辑/更新/删除/批量操作/获取字段
  • 对应控制器：AiController
• AI任务管理
  • 提交任务、轮询状态、获取产物图片、删除任务
  • 对应控制器：TaskController
• 模型与供应商管理
  • 列表/创建/编辑/更新/删除/批量操作、启用/停用
  • 对应控制器：ModelController
• 健康检测
  • 后台：档案列表/详情/删除/批量、状态切换、随访CRUD、字段配置
  • 小程序：模块入口（index）
  • 对应控制器：HealthController(后台)、HealthController(API)