简介

本设计文档围绕 AI 模型表 dou_ai_model（代码中通过 AiModelCatalog 模型访问 ai_model 表）展开，系统阐述其表结构设计、字段含义、与供应商/密钥/应用/日志的关联关系，以及后台管理流程。文档面向 AI 模型管理员，提供多供应商模型管理、价格计算接入点、性能参数配置的实施方案与最佳实践。

项目结构

AI 模型相关的数据与逻辑分布在以下位置：

• 数据库定义：备份 SQL 中包含 ai_model、ai_provider、ai_key、ai_log、ai_task 等表的建表语句与初始数据。
• 模型层：AiModelCatalog 封装 ai_model 表的读写、筛选与依赖统计；AiProvider 封装 ai_provider 表。
• 控制器与服务：ModelController 负责后台路由与请求处理；ModelService 实现供应商、密钥、模型的增删改查与事务一致性。
• 配置：config/ai.php 提供图像输入、尺寸策略、提示词等全局配置，作为模型能力与行为的外部化配置补充。

graph TB
subgraph "数据层"
A["ai_model<br/>AI模型配置表"]
B["ai_provider<br/>AI供应商配置表"]
C["ai_key<br/>API密钥表"]
D["ai_log<br/>使用日志表"]
E["ai_task<br/>异步任务表"]
end
subgraph "业务层"
F["AiModelCatalog<br/>模型模型封装"]
G["AiProvider<br/>供应商模型封装"]
H["ModelService<br/>供应商/密钥/模型服务"]
I["ModelController<br/>后台控制器"]
end
subgraph "配置"
J["config/ai.php<br/>AI全局配置"]
end
I --> H
H --> F
H --> G
F --> A
G --> B
H --> C
F --> D
F --> E
J -.-> I

核心组件

• 表 ai_model（AiModelCatalog）：存储各供应商下的模型元数据，包括名称、模型代码、上下文长度、最大输出 tokens 等。
• 表 ai_provider（AiProvider）：存储供应商基础信息与启用状态、排序、特殊配置 JSON。
• 表 ai_key：存储供应商 API 密钥及过期时间、别名、配置等。
• 表 ai_log：记录每次调用的输入/输出 tokens、耗时、错误信息、端点等。
• 表 ai_task：记录图像/视频/音频等异步任务的提交与结果。

架构总览

后台以“供应商”为分组单位管理模型与密钥：列表展示供应商，编辑页内嵌该供应商的密钥与模型行式表格，统一提交由 ModelService 在单事务内完成增删改。模型代码唯一性校验、删除前依赖检查（日志、会话、消息、应用引用）确保数据安全。

sequenceDiagram
participant U as "管理员"
participant C as "ModelController"
participant S as "ModelService"
participant M as "AiModelCatalog"
participant P as "AiProvider"
participant DB as "数据库"
U->>C : 打开模型管理页面
C->>S : getAdminIndexPageData()
S->>P : filterByKeyword()/applyDefaultOrder()
P-->>S : 供应商分页列表
S-->>C : 返回页面数据
U->>C : 新增/编辑供应商+密钥+模型
C->>S : insertWithKeys()/updateWithKeys()
S->>DB : 开启事务
S->>P : 保存/更新供应商
S->>DB : 保存/更新密钥
S->>M : 保存/更新模型(含唯一性校验)
S->>DB : 提交事务
S-->>C : 成功/失败
C-->>U : 跳转并提示结果

详细组件分析

表结构与字段说明（ai_model）

• id：自增主键。
• provider_id：所属供应商 ID，用于多供应商隔离与管理。
• name：模型显示名称。
• model_code：模型代码（唯一），用于调用时识别具体模型。
• context_length：上下文长度（tokens），用于限制输入长度或做容量规划。
• max_tokens：最大输出 tokens，用于控制生成上限。
• created_at / updated_at：创建与更新时间。

当前实现未包含“模型类型”“输入输出价格”“特性支持”“默认模型设置”“启用状态”等字段。若需扩展，可在不破坏现有索引的前提下增加列，并在 ModelService 的 buildModelRow 中纳入写入逻辑。

供应商与密钥管理

• 供应商表 ai_provider 包含 name、code、base_url、sort、status、config(JSON) 等字段，其中 status 表示启用/停用，config 可存放供应商特殊配置。
• 密钥表 ai_key 包含 provider_id、api_key、alias、expires_at、last_used_at、failure_count、config(JSON) 等，用于鉴权与计费统计。

后台管理流程与事务一致性

• 新建/编辑表单统一提交供应商、密钥、模型集合，ModelService 在单事务内执行，保证原子性。
• 新增模型时进行 model_code 唯一性校验；删除模型前检查是否被日志、会话、消息、应用引用。
• 删除供应商前检查是否有会话、日志、应用引用，避免误删影响运行。

flowchart TD
Start(["开始"]) --> Validate["校验输入<br/>model_code 唯一性"]
Validate --> TxStart{"开启事务?"}
TxStart --> |是| SaveProv["保存/更新供应商"]
TxStart --> |否| EndErr["回滚并报错"]
SaveProv --> SaveKey["保存/更新密钥"]
SaveKey --> SaveModel["保存/更新模型"]
SaveModel --> CheckDep{"删除依赖检查"}
CheckDep --> |通过| Commit["提交事务"]
CheckDep --> |不通过| Rollback["回滚并报错"]
Commit --> End(["结束"])
Rollback --> End
EndErr --> End

模型配置 JSON 与全局配置

• 供应商 config(JSON)：可存放供应商特定参数（如 base_url、认证方式、速率限制等）。
• 密钥 config(JSON)：可存放密钥级附加参数（如租户标识、区域等）。
• 应用 config(JSON)：ai 应用表中的配置项，用于挂载模块、字段约束、默认提示词等。
• 全局配置 config/ai.php：提供提示词模板、图像输入模型通配、图像尺寸策略、banner 素材限制等。

多供应商模型管理与默认模型

• 多供应商：通过 provider_id 将模型归属到不同供应商，便于隔离与独立计费。
• 默认模型：应用表 ai 中存在 model_id 字段，值为 0 表示使用系统默认模型；非 0 则指向具体模型。可通过应用配置选择默认模型。

启用状态与批量操作

• 供应商启用/停用：ai_provider.status 控制供应商是否可用；支持批量启用/停用与行内切换。
• 模型启用：当前 ai_model 无启用字段；如需按模型粒度启用/停用，可扩展 status 字段并在调用链中判断。

价格计算与用量统计

• 用量统计：ai_log 记录 prompt_tokens、completion_tokens、total_tokens、duration、status_code、has_error、error_message、endpoint、metadata 等，可用于成本核算。
• 价格计算：建议在 ai_log.metadata 或 ai_key.config 中扩展单价字段（如 input_price_per_token、output_price_per_token），结合 tokens 计算费用；或在外部计费系统中根据 model_code 映射单价。

性能参数配置

• 上下文长度与最大输出：context_length 与 max_tokens 用于限制输入与输出规模，避免超限导致失败或资源浪费。
• 图像尺寸策略：config/ai.php 中 image_size.policies 与 protocol_defaults 提供按模型族/协议归一化的尺寸策略，保障不同供应商图像模型的一致性。

依赖关系分析

• ai_model 通过 provider_id 关联 ai_provider，形成“供应商-模型”层级。
• ai_log 通过 model_id 关联 ai_model，形成“模型-使用日志”追踪。
• ai_task 通过 model_id、provider_id、key_id 关联模型、供应商与密钥，支撑异步任务生命周期。
• ai 应用通过 model_id 绑定模型，决定默认模型与任务形态。

erDiagram
AI_PROVIDER ||--o{ AI_MODEL : "拥有"
AI_PROVIDER ||--o{ AI_KEY : "拥有"
AI_MODEL ||--o{ AI_LOG : "产生"
AI_MODEL ||--o{ AI_TASK : "参与"
AI_APP ||--o{ AI_MODEL : "引用"

性能与扩展性

• 索引与查询：ai_model 对 model_code 建立唯一索引，对 provider_id 建立索引，利于按供应商快速检索与唯一性校验。
• 事务与一致性：ModelService 在增删改过程中使用事务，避免部分成功导致的脏数据。
• 扩展建议：
  • 增加模型类型字段（text/image/audio/embedding/multimodal/video），便于前端过滤与调用路由。
  • 增加输入/输出单价字段，结合 ai_log 的 tokens 计算成本。
  • 增加特性支持字段（JSON），描述模型能力（如流式、工具调用、多模态）。
  • 增加模型启用字段（status），实现细粒度开关。
  • 增加默认模型标记（is_default），简化应用默认选择。

故障排查指南

• 模型代码重复：新增/更新模型时报错，需修改 model_code 确保唯一。
• 删除受限：若模型存在日志、会话、消息或应用引用，将无法删除，需先清理依赖。
• 供应商禁用：若供应商被停用，相关应用与任务会跳过该供应商，需检查 ai_provider.status。
• 密钥无效：密钥为空或过期可能导致调用失败，检查 ai_key.api_key 与 expires_at。
• 日志异常：查看 ai_log.error_message 与 status_code 定位上游错误。

结论

ai_model 表提供了多供应商模型的基础管理能力，配合 ai_provider、ai_key、ai_log、ai_task 形成完整的模型配置、调用与计费追踪闭环。当前实现聚焦于模型元数据与供应商管理，后续可按需扩展模型类型、价格、特性、启用状态与默认模型标记，以满足更精细化的运营与计费需求。

附录：字段与配置说明

ai_model 字段字典

• id：自增主键。
• provider_id：供应商 ID。
• name：模型名称。
• model_code：模型代码（唯一）。
• context_length：上下文长度（tokens）。
• max_tokens：最大输出 tokens。
• created_at / updated_at：时间戳。

模型配置 JSON 建议

• 供应商 config(JSON)：base_url、认证方式、速率限制、重试策略等。
• 密钥 config(JSON)：租户标识、区域、配额等。
• 应用 config(JSON)：字段约束、默认提示词、任务形态等。

默认模型设置

• 应用表 ai.model_id=0 表示使用系统默认模型；非 0 指向具体模型。
• 可通过应用配置选择默认模型，或在模型层增加 is_default 标记。

启用状态

• 供应商启用/停用：ai_provider.status。
• 模型启用：当前未实现，可扩展 status 字段并在调用链中判断。

价格计算接入点

• 在 ai_log 中记录 tokens 与耗时，结合单价计算费用。
• 建议在 ai_key.config 或 ai_model 扩展字段中维护单价，便于灵活定价。

性能参数配置

• context_length 与 max_tokens 控制输入输出规模。
• config/ai.php 提供图像尺寸策略，保障跨供应商一致性。