简介

本文件面向开发者，系统性说明 DouPHP 的大语言模型（LLM）集成功能。内容覆盖多供应商对接（OpenAI、Claude、国内主流服务商等）、抽象层设计、请求封装、响应解析、错误处理、模型选择策略、参数配置、流式与异步任务、Token 计数、成本控制、性能优化、缓存与降级方案，以及新增模型、自定义提示词模板、构建 AI 工作流的实践指南。

项目结构

DouPHP 的 AI 能力以“服务层 + 网关 + 驱动”的分层组织：

• 后台业务服务：生成编排、应用管理、密钥与模型管理
• 网关层：统一解析配置、路由到具体驱动、统一错误与用量统计
• 驱动层：按供应商实现请求体组装、头部、内容提取、用法统计、图像/视频生成、异步任务提交
• 配置中心：集中管理提示词、图片尺寸策略、素材限制等

graph TB
subgraph "后台服务"
GS["GenerateService<br/>生成编排"]
ASvc["ApplicationService<br/>应用管理"]
MSvc["ModelService<br/>模型/供应商管理"]
KSvc["KeyService<br/>密钥管理"]
end
subgraph "网关"
GW["AiGateway<br/>配置解析/路由/错误/用量"]
end
subgraph "驱动"
OF["OpenAiDriver"]
QD["QwenDriver"]
BD["BaiduDriver"]
BL["BailianDriver"]
VD["VolcanoDriver"]
DF["DriverFactory"]
end
GS --> GW
ASvc --> GW
MSvc --> KSvc
GW --> DF
DF --> OF
DF --> QD
DF --> BD
DF --> BL
DF --> VD

核心组件

• GenerateService：后台 AI 创作运行时，负责拼装提示词、调用网关、记录用量、处理结构化输出与图像生成任务。
• ApplicationService：AI 应用（挂载模块、字段、形态）的增删改查与表单数据准备。
• ModelService：供应商、密钥、模型的统一管理，含事务性写入与删除保护。
• KeyService：密钥加密存储、脱敏展示、失败计数重置等。
• AiGateway：统一配置解析、驱动路由、非流式对话、结构化 JSON 输出、图像生成、异步任务、用量与错误归一化。
• Driver*：各供应商驱动，实现请求体/头构造、内容提取、用法统计、图像/视频生成、异步任务。

架构总览

系统通过“服务层 → 网关 → 驱动”的解耦设计，屏蔽不同供应商差异，提供统一的对话、结构化输出、图像/视频生成与异步任务能力。

sequenceDiagram
participant UI as "后台界面"
participant GS as "GenerateService"
participant GW as "AiGateway"
participant DF as "DriverFactory"
participant D as "具体驱动(OpenAI/Qwen/百度/百炼/火山)"
participant DB as "数据库"
UI->>GS : 发起生成(文本/结构化/图像)
GS->>GW : chat/chatJson/generateImage/submitAsyncTask
GW->>DF : make(config)
DF-->>GW : 返回驱动实例
GW->>D : buildRequestBody/buildHeaders
D-->>GW : 原始响应
GW->>GW : 解析内容/用法/错误
GW-->>GS : 标准化结果
GS->>DB : 记录用量/日志
GS-->>UI : 返回结果或任务ID

详细组件分析

生成编排服务（GenerateService）

职责

• 批量生成（batch）：按 Schema 生成 items 并批量入库
• 表单填充（fill）：生成完整字段值供前端回填
• 单字段辅助（assist）：纯文本生成或文生图任务
• 翻译（translate）：主字段原文译为目标语言
• 提示词预览：仅拼装不下发模型
• 图像提示词构建：尺寸规划、参考图解析、Banner 风格注入
• 异步任务分流：对支持异步驱动的模型提交任务并返回 task_id

关键流程（批量生成）

flowchart TD
Start(["开始"]) --> LoadApp["加载应用并校验形态"]
LoadApp --> CheckModule{"模块是否支持导入?"}
CheckModule -- 否 --> Err1["抛出异常: 不支持模块"]
CheckModule -- 是 --> CountPolicy["按策略限制生成数量"]
CountPolicy --> Guard["防重复提交指纹校验"]
Guard --> Compose["拼装消息(系统/用户/快照)"]
Compose --> ChatJson["网关结构化对话(chatJson)"]
ChatJson --> Record["记录用量/日志"]
Record --> Success{"success?"}
Success -- 否 --> Err2["抛出异常: 生成失败"]
Success -- 是 --> Import["批量导入items"]
Import --> End(["结束"])

应用管理服务（ApplicationService）

职责

• 列表筛选分页（按形态、任务类型、状态）
• 新增/编辑表单数据准备（模型分组、可挂载模块）
• 写入与更新应用记录（应用策略校验）
• 删除与批量删除
• 动态返回模块字段集合（用于前端联动）

模型与密钥管理（ModelService / KeyService）

• ModelService：供应商、密钥、模型的一体化 CRUD；删除前进行用量/会话/应用引用检查；支持批量启用/停用与删除。
• KeyService：密钥加密存储、脱敏展示、失败计数重置；合并敏感字段（如 client_secret）到 config。

网关与驱动（AiGateway / Driver*）

• AiGateway：统一解析模型/供应商/密钥，计算端点与驱动代码；提供 chat、chatJson、generateImage、submitAsyncTask/pollAsyncTask；统一错误、用量、熔断与冷却。
• DriverFactory：根据 provider_code 与 stream_format 路由到具体驱动。
• OpenAiDriver/QwenDriver/BaiduDriver/BailianDriver/VolcanoDriver：各自实现请求体/头、内容提取、用法统计、图像/视频生成、异步任务。

classDiagram
class AiGateway {
+resolveConfig(modelId) array
+chat(messages, modelId, options) array
+chatJson(messages, schema, modelId, options) array
+generateImage(modelId, params, meta) array
+submitAsyncTask(modelId, params, meta) array
+pollAsyncTask(taskId) array
+getAvailableKey(providerId) array
+bumpFailureCount(keyId) void
}
class DriverFactory {
+make(config) DriverInterface
+code(params) string
}
class OpenAiDriver
class QwenDriver
class BaiduDriver
class BailianDriver
class VolcanoDriver
AiGateway --> DriverFactory : "创建驱动"
DriverFactory --> OpenAiDriver
DriverFactory --> QwenDriver
DriverFactory --> BaiduDriver
DriverFactory --> BailianDriver
DriverFactory --> VolcanoDriver

依赖关系分析

• 服务层依赖网关，不直接感知驱动细节
• 网关通过工厂创建驱动，屏蔽协议差异
• 密钥与模型由管理面维护，运行时由网关动态解析
• 提示词与尺寸策略由配置中心集中管理，便于统一调整

graph LR
A["GenerateService"] --> G["AiGateway"]
B["ApplicationService"] --> G
C["ModelService"] --> K["KeyService"]
G --> F["DriverFactory"]
F --> D1["OpenAiDriver"]
F --> D2["QwenDriver"]
F --> D3["BaiduDriver"]
F --> D4["BailianDriver"]
F --> D5["VolcanoDriver"]
G --> DB[("数据库")]
A --> DB
C --> DB

性能与成本优化

• 模型选择策略
  • 优先使用应用绑定的模型；未绑定则取默认模型（可用密钥过滤）
  • 通过 ApplicationPolicy 校验任务与模型/供应商匹配
• 结构化输出
  • 支持 response_format.json_schema 强约束；否则降级为 json_object + system 重述 schema
• 流式与异步
  • 长耗时任务（图像/视频）走异步提交，前端轮询；同步驱动也统一包装为任务行
• Token 计数
  • 通过驱动 extractUsage 统一提取 prompt/completion/total tokens
• 成本控制
  • 批量生成数量受策略限制；图像尺寸归一化避免过大导致费用飙升
  • 密钥熔断与冷却时间减少无效重试
• 缓存策略
  • 提示词与模块字段可在上层按需缓存（例如字段列表、Schema），减少重复计算
• 降级方案
  • 无可用密钥/模型时返回明确错误；图像生成失败时尝试去除 size 重试一次
  • 非 json_schema 供应商自动降级为 json_object

故障排查指南

常见问题与定位

• 无可用模型/密钥
  • 检查供应商状态、密钥过期、失败次数阈值与冷却时间
• HTTP 错误
  • 查看 http_code 与 error 字段；网关已记录日志
• JSON 解析失败
  • 检查驱动返回内容是否为合法 JSON；必要时放宽约束或增加 system 指令
• 图像生成失败
  • 若带 size 被拒，网关会尝试去掉 size 重试；确认尺寸策略与模型预设
• 异步任务无结果
  • 使用 pollAsyncTask 查询任务状态；确认任务类型与驱动支持

操作建议

• 在后台重置密钥失败计数（KeyService::resetKey）
• 检查应用绑定模型与任务类型是否匹配（ApplicationPolicy）
• 查看用量日志与提示词预览，确认输入质量

结论

DouPHP 的 LLM 集成通过清晰的分层与驱动抽象，实现了多供应商的统一接入与扩展。服务层专注业务编排，网关负责配置解析与错误归一，驱动层屏蔽协议差异。结合结构化输出、异步任务、用量统计与熔断机制，系统在可用性、可扩展性与成本控制方面具备良好基础。

附录：扩展开发规范

新增 AI 模型支持（以某新供应商为例）

步骤

1. 新建驱动类，实现必要接口（请求体/头、内容提取、用法统计、可选图像/视频生成与异步任务）
2. 在工厂中注册该驱动（provider_code 与 stream_format 映射）
3. 在后台添加供应商与模型（ModelService），配置 base_url、endpoints、temperature 等
4. 录入密钥（KeyService），确保加密存储与可用密钥筛选生效
5. 在应用管理中绑定模型，并通过 GenerateService 验证端到端流程

注意事项

• 遵循统一返回格式（success/content/usage/error）
• 若支持 json_schema，声明 supports_json_schema 以获得强约束
• 图像/视频任务需实现对应接口或异步提交

自定义提示词模板

• 在配置中心集中管理 system/instruction/labels/banner_styles/banner_material
• 通过 PromptComposer 按 placement 与 task_type 拼装消息
• 预览功能可快速验证最终提示词效果

构建 AI 工作流

• 使用 GenerateService 串联多个步骤：先生成结构化数据，再批量入库；或先生成文案，再触发图像生成
• 利用异步任务将耗时步骤解耦，提升用户体验
• 通过 UsageRecorder 记录用量与上下文，便于分析与优化