AI功能表 | DouPHP 开发手册 | 文档中心 | DouPHP企业建站系统

AI功能表

简介

本设计文档聚焦 DouPHP 的全新 AI 功能模块，围绕 dk_ai、dk_ai_key、dk_ai_log、dk_ai_model、dk_ai_provider、dk_ai_task 等核心数据表进行系统化说明。文档从表结构、字段语义、索引策略、业务关联、以及面向智能聊天、图像生成、内容创作等能力的建模方式出发，给出完整的参考设计与优化建议，帮助开发者与算法工程师快速理解并扩展 AI 能力。

更新系统已全面升级至新的 dk_ 前缀命名规范，提供更完善的AI工作流管理能力。

项目结构

AI 相关的数据定义与模型主要分布在以下位置：

新数据库建表脚本：_'\table\new\schema_new.sql
后台模型（ORM）：_'\module\ai\admin\model\ai/*
异步任务仓储：_'\module\ai\core\service\ai\Task\AsyncTaskRepository.php

graph TB
subgraph "数据层"
A["dk_ai<br/>AI应用表"]
B["dk_ai_model<br/>AI模型表"]
C["dk_ai_provider<br/>AI供应商表"]
D["dk_ai_key<br/>API密钥表"]
E["dk_ai_log<br/>使用日志表"]
F["dk_ai_task<br/>异步任务表"]
end
subgraph "模型层"
M1["AiApplication"]
M2["AiModelCatalog"]
M3["AiProvider"]
M4["AiKey"]
M5["AiLog"]
end
subgraph "服务层"
S1["AsyncTaskRepository"]
end
A --> B
B --> C
A --> D
E --> C
E --> B
E --> D
F --> C
F --> B
F --> D
F --> A
M1 --> A
M2 --> B
M3 --> C
M4 --> D
M5 --> E
S1 --> F

图表来源

schema_new.sql:36-148
AiApplication.php:27-197
AiModelCatalog.php:28-171
AiProvider.php:28-138
AiKey.php:29-159
AiLog.php:28-240
AsyncTaskRepository.php:39-73

核心组件

本节概述各表职责与关键字段，便于快速定位与理解。

dk_ai（AI 应用表）
- 用途：描述后台可用的 AI 应用形态与挂载点，如"商品批量生成""文生图""Banner 生成"等。
- 关键字段：name、placement（应用形态）、task_type（任务形态）、module（挂载模块）、field（字段约束 JSON）、model_id（默认模型）、default_prompt（预设提示词）、config（应用配置 JSON）。
- 索引：module+placement+status 复合索引，用于按挂载模块与应用形态筛选。
dk_ai_model（AI 模型表）
- 用途：记录供应商提供的具体模型及其能力参数（上下文长度、最大输出 tokens 等）。
- 关键字段：provider_id、name、model_code（唯一键）、context_length、max_tokens。
- 索引：model_code 唯一索引；provider_id 索引。
dk_ai_provider（AI 供应商表）
- 用途：管理不同 AI 供应商的基础信息与开关状态。
- 关键字段：name、code（唯一键）、base_url、sort、status、config（JSON）。
- 索引：code 唯一索引。
dk_ai_key（API 密钥表）
- 用途：存储各供应商的 API Key 及元信息，支持别名、过期时间、最后使用时间、失败计数等。
- 关键字段：provider_id、api_key（加密存储）、alias、expires_at、last_used_at、failure_count、config（加密存储）。
- 索引：provider_id、last_used_at。
dk_ai_log（使用日志表）
- 用途：记录每次 AI 调用的完整审计信息，包括输入/输出 token、耗时、状态码、错误信息、端点、IP、元数据等。
- 关键字段：admin_id、app_id、model_id、provider_id、key_id、request_id、prompt_tokens、completion_tokens、total_tokens、duration、status_code、has_error、error_message、prompt_content、response_content、endpoint、ip、metadata。
- 索引：admin_id、app_id、created_at。
dk_ai_task（异步任务表）
- 用途：承载需要长时间运行的 AI 任务（如图文生成），支持轮询与结果过期管理。
- 关键字段：provider_id、model_id、key_id、app_id、admin_id、task_type、provider_task_id、status、request_payload、result、error、expires_at、last_polled_at。
- 索引：status+created_at、provider_id+provider_task_id、admin_id+created_at。

章节来源

schema_new.sql:36-148
AiApplication.php:27-197
AiModelCatalog.php:28-171
AiProvider.php:28-138
AiKey.php:29-159
AiLog.php:28-240
AsyncTaskRepository.php:39-73

架构总览

AI 能力通过"应用—模型—供应商—密钥—日志—任务"的链路组织：

应用（dk_ai）定义业务场景与挂载点，指定默认模型与提示词模板。
模型（dk_ai_model）抽象供应商的具体模型能力。
供应商（dk_ai_provider）提供基础连接与开关。
密钥（dk_ai_key）负责鉴权与配额控制。
日志（dk_ai_log）记录调用细节，支撑成本统计与问题定位。
任务（dk_ai_task）处理长耗时任务，支持轮询与结果过期。

sequenceDiagram
participant Admin as "管理员/前端"
participant App as "AI应用(dk_ai)"
participant Model as "模型(dk_ai_model)"
participant Provider as "供应商(dk_ai_provider)"
participant Key as "密钥(dk_ai_key)"
participant Log as "日志(dk_ai_log)"
participant Task as "任务(dk_ai_task)"
Admin->>App : 选择应用与参数
App->>Model : 解析默认模型或覆盖模型
Model->>Provider : 获取供应商能力
Provider->>Key : 校验并选择可用密钥
Note over Key,Provider : 支持轮换与失败计数
Admin->>Task : 提交长时任务(可选)
Task-->>Admin : 返回任务ID与查询接口
App->>Log : 写入调用日志(文本/图片/翻译等)
Log-->>Admin : 可审计与成本统计

图表来源

schema_new.sql:36-148
AiApplication.php:27-197
AiModelCatalog.php:28-171
AiProvider.php:28-138
AiKey.php:29-159
AiLog.php:28-240
AsyncTaskRepository.php:39-73

详细组件分析

AI 应用表（dk_ai）

设计要点
- placement 表示应用形态（assist/fill/batch/translate），task_type 表示任务形态（assist/polish/rewrite/image/banner/translate/fill/batch），二者解耦，便于统一提示词匹配与流程编排。
- module 与 field 将 AI 能力挂载到具体业务模块与字段，实现"内容创作"场景的灵活接入。
- model_id 指向默认模型，default_prompt 与 config 支持模板化与参数化。
典型用法
- "商品批量生成"：placement=batch，task_type=batch，module=product，field=[title,content,keywords,description]。
- "文生图"：task_type=image，走独立图像管道。
索引与查询
- 复合索引 module+placement+status 提升列表与筛选性能。

classDiagram
class AiApplication {
+int id
+string name
+enum placement
+enum task_type
+string module
+text field
+text description
+int model_id
+text default_prompt
+text config
+smallint sort
+tinyint status
+datetime created_at
+datetime updated_at
}

图表来源

schema_new.sql:36-53
AiApplication.php:27-197

章节来源

schema_new.sql:36-53
AiApplication.php:27-197

AI 模型表（dk_ai_model）

设计要点
- provider_id 关联供应商，model_code 唯一标识模型，context_length 与 max_tokens 描述能力边界。
- 支持多供应商多模型的统一管理，便于在应用中动态切换。
索引与查询
- model_code 唯一索引确保全局唯一性；provider_id 索引加速按供应商筛选。

classDiagram
class AiModelCatalog {
+int id
+int provider_id
+string name
+string model_code
+int context_length
+int max_tokens
+datetime created_at
+datetime updated_at
}

图表来源

schema_new.sql:98-110
AiModelCatalog.php:28-171

章节来源

schema_new.sql:98-110
AiModelCatalog.php:28-171

AI 供应商表（dk_ai_provider）

设计要点
- code 唯一标识供应商，base_url 为 API 基础地址，status 控制启用/禁用，config 保存供应商特定配置。
- 提供统计方法以评估影响面（如被应用引用数量）。
索引与查询
- code 唯一索引；排序字段 sort 用于展示顺序。

classDiagram
class AiProvider {
+int id
+string name
+string code
+string base_url
+smallint sort
+tinyint status
+text config
+datetime created_at
+datetime updated_at
}

图表来源

schema_new.sql:112-124
AiProvider.php:28-138

章节来源

schema_new.sql:112-124
AiProvider.php:28-138

AI 密钥表（dk_ai_key）

设计要点
- api_key 与 config 采用加密存储，避免明文泄露；alias 便于识别；expires_at 支持过期管理；failure_count 支持失败熔断；last_used_at 支持最近使用统计。
- 提供统计方法：按 key 的使用日志数、会话数，以及别名回退显示。
索引与查询
- provider_id 与 last_used_at 索引提升筛选与轮转效率。

classDiagram
class AiKey {
+int id
+int provider_id
+text api_key
+string alias
+datetime expires_at
+datetime last_used_at
+int failure_count
+text config
+datetime created_at
+datetime updated_at
}

图表来源

schema_new.sql:55-69
AiKey.php:29-159

章节来源

schema_new.sql:55-69
AiKey.php:29-159

AI 使用日志表（dk_ai_log）

设计要点
- 记录每次调用的关键指标：prompt_tokens、completion_tokens、total_tokens、duration、status_code、has_error、error_message、prompt_content、response_content、endpoint、ip、metadata。
- 支持按 admin_id、app_id、model_id、provider_id、时间范围筛选，便于成本核算与问题追踪。
索引与查询
- admin_id、app_id、created_at 索引提升报表与审计查询性能。

classDiagram
class AiLog {
+bigint id
+int admin_id
+int app_id
+int model_id
+int provider_id
+int key_id
+string request_id
+int prompt_tokens
+int completion_tokens
+int total_tokens
+int duration
+int status_code
+tinyint has_error
+text error_message
+text prompt_content
+longtext response_content
+string endpoint
+string ip
+text metadata
+datetime created_at
}

图表来源

schema_new.sql:71-96
AiLog.php:28-240

章节来源

schema_new.sql:71-96
AiLog.php:28-240

AI 异步任务表（dk_ai_task）

设计要点
- 支持 image/video/audio 等多模态任务的异步执行，status 管理生命周期（pending/running/succeeded/failed/timeout）。
- request_payload 与 result 分别记录提交体与结果（含 URL 与有效期），expires_at 控制结果保留期，last_polled_at 记录最近轮询时间。
- 支持后台（admin_id）与前台（user_id 预留）双归属，便于统一调度。
索引与查询
- status+created_at、provider_id+provider_task_id、admin_id+created_at 提升调度与查询效率。

flowchart TD
Start(["提交任务"]) --> Create["创建任务记录<br/>status=pending"]
Create --> Submit["提交至上游供应商"]
Submit --> Running{"提交成功?"}
Running --> |是| UpdateRunning["更新status=running<br/>记录provider_task_id"]
Running --> |否| MarkFailed["标记失败<br/>记录error"]
UpdateRunning --> Poll["定时轮询结果"]
Poll --> CheckStatus{"是否完成?"}
CheckStatus --> |否| Wait["等待下次轮询"]
CheckStatus --> |是| SaveResult["保存result与expires_at<br/>更新status=succeeded"]
SaveResult --> End(["结束"])
MarkFailed --> End
Wait --> Poll

图表来源

schema_new.sql:126-148
AsyncTaskRepository.php:39-73

章节来源

schema_new.sql:126-148
AsyncTaskRepository.php:39-73

概念总览

智能聊天：通过 dk_ai_log 记录对话交互的 token 与错误信息，结合 dk_ai_key 的失败计数与过期管理，实现成本控制与稳定性保障。
图像生成：通过 dk_ai_task 管理长时任务，result 中保存图片 URL 与有效期，配合 expires_at 清理过期资源。
内容创作：通过 dk_ai 的 module 与 field 将 AI 能力挂载到商品、文章等业务模块，实现字段级润色、重写、批量生成等。

依赖关系分析

应用与模型：dk_ai.model_id → dk_ai_model.id
模型与供应商：dk_ai_model.provider_id → dk_ai_provider.id
日志与三方：dk_ai_log.provider_id/model_id/key_id/app_id/admin_id 分别关联供应商、模型、密钥、应用、管理员
任务与三方：dk_ai_task.provider_id/model_id/key_id/app_id/admin_id 分别关联供应商、模型、密钥、应用、管理员

erDiagram
DK_AI ||--o{ DK_AI_LOG : "被记录"
DK_AI_MODEL ||--o{ DK_AI_LOG : "被记录"
DK_AI_PROVIDER ||--o{ DK_AI_LOG : "被记录"
DK_AI_KEY ||--o{ DK_AI_LOG : "被记录"
DK_AI ||--o{ DK_AI_TASK : "所属应用"
DK_AI_MODEL ||--o{ DK_AI_TASK : "所属模型"
DK_AI_PROVIDER ||--o{ DK_AI_TASK : "所属供应商"
DK_AI_KEY ||--o{ DK_AI_TASK : "所属密钥"

图表来源

schema_new.sql:36-148
AiLog.php:28-240
AsyncTaskRepository.php:39-73

章节来源

schema_new.sql:36-148
AiLog.php:28-240
AsyncTaskRepository.php:39-73

性能考虑

索引策略
- dk_ai：module+placement+status 复合索引，提高按模块与应用形态的筛选效率。
- dk_ai_model：model_code 唯一索引，避免重复；provider_id 索引加速按供应商筛选。
- dk_ai_key：provider_id 与 last_used_at 索引，支持密钥轮换与最近使用统计。
- dk_ai_log：admin_id、app_id、created_at 索引，提升审计与报表查询性能。
- dk_ai_task：status+created_at、provider_id+provider_task_id、admin_id+created_at 提升调度与查询效率。
数据量增长
- dk_ai_log 与 dk_ai_task 为高频写入表，建议定期归档与分区（按月份或业务维度）。
- response_content 与 request_payload 为大字段，注意存储与备份策略，必要时落盘或压缩。
并发与轮询
- 异步任务采用轮询机制，需限制轮询频率与超时策略，避免对上游造成压力。
缓存与去重
- 对热点查询（如模型列表、供应商列表）可引入缓存；对重复请求可进行幂等去重（基于 request_id）。

故障排查指南

常见问题定位
- 使用日志：通过 dk_ai_log 的 has_error、error_message、status_code、endpoint、ip 快速定位错误来源。
- 密钥问题：检查 dk_ai_key 的 failure_count、expires_at、last_used_at，确认密钥是否过期或频繁失败。
- 任务异常：通过 dk_ai_task 的 status、error、expires_at、last_polled_at 判断任务是否卡住或超时。
排查步骤
- 根据 app_id、model_id、provider_id、key_id 过滤日志，缩小范围。
- 核对 dk_ai 的 task_type 与 dk_ai_model 的能力参数是否匹配。
- 对于长时任务，检查轮询间隔与上游响应，必要时调整 expires_at 与重试策略。

章节来源

AiLog.php:28-240
AiKey.php:29-159
AsyncTaskRepository.php:39-73

结论

DouPHP 的全新 AI 表结构以 dk_ 前缀为核心，通过"应用—模型—供应商—密钥—日志—任务"的完整链路，既满足内容创作、智能聊天、图像生成等多模态能力，又提供了完善的审计与成本控制基础。通过合理的索引与归档策略，可在高并发与大数据量场景下保持稳定与高效。建议在实际使用中结合业务需求，持续优化任务调度与日志留存策略。

更新系统现已具备完整的AI工作流管理能力，支持多种AI供应商集成，为未来的AI功能扩展奠定了坚实基础。

附录

术语说明
- 应用形态（placement）：assist/fill/batch/translate，表示应用在不同场景下的行为模式。
- 任务形态（task_type）：assist/polish/rewrite/image/banner/translate/fill/batch，表示具体任务类型与提示词匹配键。
- 上下文长度（context_length）：模型支持的上下文窗口大小。
- 最大输出（max_tokens）：模型单次请求的最大输出 token 数。
扩展建议
- 增加用量配额与计费规则表，结合 dk_ai_log 实现精细化成本核算。
- 为 dk_ai_task 增加重试次数与退避策略字段，提升鲁棒性。
- 对 dk_ai_log 的大字段进行分表或对象存储，降低数据库压力。
安全增强
- API密钥采用加密存储，防止敏感信息泄露。
- 支持密钥过期管理与失败熔断机制。
- 提供完整的操作审计日志，便于安全追踪。

添加日期：2026-10-05