🤖 AI

SunAdmin 接入 Laravel AI，通过统一服务层调用文本模型、向量模型和知识库。模型供应商、API Key、Base URL 和模型名称由后台配置中心管理，业务代码只通过服务入口调用。本页讲 AI 这一侧；MCP 工具与 AI Agent 工具适配详见 MCP。

🎯 本页目标

读完本章节后，应能掌握：

• AI 配置存储位置、读取方式和缓存策略。
• 文本模型、向量模型、知识库 RAG、AI 助手各自的入口和职责。
• 用户端 AI 提问、推荐、会话接口的对接方式。
• AI 用量记录的同步与异步策略。

🔧 代码地图

文件	说明
AiConfigController.php	后台 AI 配置、驱动、用量、助手配置
AiEditorController.php	编辑器 AI 改写入口
AiKnowledgeController.php	知识库管理和同步
AiChatController.php	用户端 AI 提问、推荐、会话
LlmService.php	文本模型和向量模型统一入口
ChatService.php	用户端聊天业务
RecommendService.php	推荐能力
EditorTransformService.php	编辑器文本处理
RagService.php	知识库向量和检索
RuntimeAgent.php	管理端 AI Agent 运行时
AiUsageRecorder.php	AI 用量记录
RecordAiUsageJob.php	AI 用量异步记录任务

🧰 配置来源

AI 配置保存在 configs 表的 ai 分组中。核心字段包括：

字段	说明
ai_enabled	AI 总开关
default_driver	默认文本模型驱动
embedding_driver	默认向量模型驱动
{driver}_api_key	供应商 API Key
{driver}_base_url	供应商接口地址
{driver}_model	文本模型
{driver}_embedding_model	向量模型，适用于支持 Embedding 的驱动
{driver}_embedding_dimensions	向量维度，未配置默认 1536

LlmService 会在调用前把后台配置写入 Laravel AI 运行时配置，并清理 provider 实例缓存，确保后台保存后新配置立即生效。

🎛️ 驱动与场景

驱动枚举：

modules/System/Domain/Enums/AiProviderEnum.php

场景枚举：

modules/System/Domain/Enums/AiSceneEnum.php

建议把不同业务调用写成明确 scene，例如：

• 后台助手。
• 编辑器润色。
• 用户端问答。
• 推荐内容。
• 知识库向量。

这样后续做用量统计、额度控制、模型切换、审计日志时不会混在一起。

🧮 文本与向量

能力	推荐入口
文本对话	LlmService::chat() / LlmService::ask()
向量生成	LlmService::embedding()
推荐内容	RecommendService
编辑器改写	EditorTransformService
RAG 知识库	RagService

业务代码不要直接拼供应商请求，优先走服务层。

💬 文本调用流程

zhipu、qwen、volcano、deepseek 等供应商的文本调用统一按 OpenAI Chat Completions 兼容协议处理。这样后台只需要维护 Base URL、API Key、模型名，不需要在业务代码里写供应商分支。

🧠 向量与知识库

向量调用走 OpenAI-compatible /embeddings 协议。Embedding驱动 应选择已验证支持向量接口的供应商，例如 qwen、zhipu。DeepSeek 当前作为对话驱动使用，不作为知识库向量化驱动；火山方舟保留为对话驱动配置，待明确可用的向量接入点后再开放为 Embedding 驱动。

知识库相关表和 Dao 包括：

能力	文件
知识库模型	modules/System/Domain/Models/Ai/AiKnowledge.php
知识库 Dao	modules/System/Dao/Ai/AiKnowledgeDao.php
聊天日志	AiChatLog / AiChatLogDao
用量记录	AiUsage / AiUsageDao

知识库同步建议：

• 用稳定身份识别来源，例如 module + source_type + source_id。
• 重建时按来源覆盖旧数据，避免重复活跃 chunk。
• 保存 chunk_index，方便排查和重建。
• 向量维度必须与配置中的 {driver}_embedding_dimensions 一致。

🖥️ 管理端接口

URI	说明
/adminapi/system/ai/config/*	AI 模型与助手配置
/adminapi/system/ai/editor/transform	编辑器文本改写
/adminapi/system/ai/knowledge/*	知识库管理与同步

管理端 AI 助手与 MCP 工具调用接口详见 MCP / MCP 能力入口。

📱 用户端接口

URI	说明
/api/system/ai/ask	用户端 AI 提问
/api/system/ai/recommend	AI 推荐
/api/system/ai/session/create	创建会话
/api/system/ai/session/history	会话历史

用户端 Api 目录默认带 api.site + api.auth。AI 聊天、推荐、会话等允许游客访问但需要尽量识别登录态的接口，使用 OpenGet / OpenPost 排除强制登录，并额外挂载 api.try-auth 和限流。

📊 用量记录

AI 用量记录服务：

modules/System/Application/Services/Ai/AiUsageRecorder.php

异步任务：

modules/System/Application/Jobs/Ai/RecordAiUsageJob.php

配置：

'async' => [
    'ai_usage' => [
        'enabled' => (bool) env('SUNADMIN_AI_USAGE_ASYNC', false),
        'connection' => env('SUNADMIN_AI_USAGE_QUEUE_CONNECTION', ''),
        'queue' => env('SUNADMIN_AI_USAGE_QUEUE', 'ai'),
        'tries' => (int) env('SUNADMIN_AI_USAGE_TRIES', 3),
    ],
],

开发环境可以同步记录，生产环境如果 AI 请求较多，建议开启异步并运行队列 worker。

🗂️ 安全与治理

• AI 开关必须由后台配置控制，不能在代码中写死开启。
• API Key 不进入前端，不写入仓库。
• 用户输入进入模型前要控制长度。
• 用户端 AI 接口要保留限流。
• 知识库内容同步要考虑删除、覆盖和重复 chunk。
• 模型输出不能直接作为高风险业务动作依据，例如支付、提现、权限变更。

🧯 排查顺序

问题	排查
模型请求失败	后台 ai 配置、Base URL、API Key、模型名称
后台保存配置不生效	LlmService 运行时配置刷新、配置缓存
向量维度错误	{driver}_embedding_dimensions 与模型实际维度
AI 用量没记录	同步/异步配置、队列 worker、ai_usages 数据
用户端 AI 被拒绝	站点状态、限流、AI 总开关、登录态