AI 助手

AI 助手模块基于 laravel/ai 封装了后台配置、运行时调用、会话记录和调用追踪能力。模块代码位于 modules/Ai，后台页面位于 web/src/views/ai，核心执行入口是 Modules\Ai\Services\AiRuntimeService。

INFO

使用该模块需要安装 laravel/ai 使用下面的命令安装

composer require "laravel/ai"

模块组成

模块安装器位于 modules/Ai/Installer.php，安装时会引入：

• laravel/ai
• league/commonmark

后台菜单当前包含以下能力：

功能	页面目录	后端资源
服务商管理	web/src/views/ai/providers	ai/providers
提示词管理	web/src/views/ai/prompts	ai/prompts
输出结构管理	web/src/views/ai/outputSchemas	ai/output/schemas
智能体管理	web/src/views/ai/agents	ai/agents
调用记录	web/src/views/ai/callRecords	ai/call/records
知识库管理	web/src/views/ai/knowledgeBase	ai/knowledge/base
知识库文件	web/src/views/ai/knowledgeFiles	ai/knowledge/files

数据模型

核心表结构可以先看配置关系，再看运行沉淀。

表	作用
ai_providers	服务商配置，保存 driver、地址、加密后的 API Key 和扩展参数
ai_provider_models	服务商下的模型配置，区分普通模型和图片模型
ai_prompts	可复用提示词
ai_prompt_providers	提示词与服务商绑定关系
ai_output_schemas	JSON 输出结构定义
ai_agents	智能体配置，组合服务商、提示词、能力和输出类型
ai_agent_models	智能体与模型绑定关系
ai_model_sessions	会话主记录
ai_model_session_messages	用户与智能体消息记录
ai_knowledge_bases	知识库
ai_knowledge_files	知识库文件记录
ai_call_records	每次调用的完整追踪记录

ai_call_records 是排障中心，保留 trace_id、输入、输出、Token 消耗、耗时、错误信息、提示词快照、输出结构快照、上下文快照和运行时 Prompt 快照。

配置关系

服务商与模型

服务商负责保存真实接入配置，api_key 使用加密 cast 入库，列表接口只暴露脱敏值。每个服务商可以挂多个模型，图片能力依赖 is_support_image = 1 的模型。

提示词

提示词可以绑定多个服务商。创建智能体时，提示词列表会按当前服务商过滤，保证运行时能找到对应绑定关系。

输出 Schema

当智能体 output_type 为 json 时，需要配置输出 Schema。Schema 支持：

• string
• integer
• number
• boolean
• object
• array

Schema 在保存阶段完成字段校验，在运行阶段由 OutputSchemaCompiler 编译成 Laravel AI SDK 可消费的 JSON Schema 定义。

智能体

智能体是最终运行单元，主要字段如下：

字段	说明
key	对外调用标识
provider_id	运行服务商
prompt_id	系统提示词
ability	text、chat、image
output_type	text、json、image
contexts	对话上下文保留条数
max_tokens / temperature / top_p	模型调用参数
options	透传给 Provider 的扩展参数

后台表单负责把服务商、提示词、能力和输出类型组装成一份可运行配置。

运行链路

运行时入口集中在 RuntimeController，核心流程如下：

文本调用

文本能力通过 runText() 执行。运行时会：

1. 校验智能体、服务商、提示词和输出结构状态。
2. 选择当前服务商下可用模型。
3. 使用 PromptComposer 组合系统提示词和运行输入。
4. 使用 ConfiguredAgent 调用模型。
5. 记录调用结果、Token 和快照。

当输出类型为 json 时，运行时会切换为 ConfiguredStructuredAgent，返回结构化结果和序列化文本。

对话调用

对话能力通过 reply() 和 chatStream() 执行。系统会先写入用户消息，再由 ConversationContextBuilder 按 contexts 读取最近消息，组装为 SDK 消息上下文。回复完成后，系统会继续保存智能体消息，并把 session_id 回传给前端。

图片调用

图片能力走异步流程：

1. queueImage() 先创建 pending 状态的调用记录。
2. GenerateAiImageJob 入队执行。
3. 任务调用 runQueuedImageRecord() 完成图片生成。
4. 结果写回调用记录，状态依次进入 running、success 或 failed。

这条链路适合响应时间较长的图片任务，前端调试页会提示到调用记录中查看结果。

调用接口

运行接口定义在 modules/Ai/routes/route.php。

Method	接口	用途
POST	ai/prompt	同步文本调用
POST	ai/prompt/stream	流式文本调用
POST	ai/prompt/image	提交图片生成任务
POST	ai/chat/reply	同步对话调用
POST	ai/chat/stream	流式对话调用
POST	ai/agents/{key}/debug	后台调试智能体

文本调用示例

{
  "key": "article.optimize",
  "title": "原始标题",
  "content": "原始正文"
}

PromptCallRequest 支持两种输入形态：

• 直接传普通字段，除 key 之外的字段都会进入运行输入。
• 显式传 input，值可以是字符串或数组。

对话调用示例

{
  "key": "customer.chat",
  "message": "帮我总结这段内容",
  "session_id": "4b6b22ab-8758-49b3-b5a5-cad5602f5db1",
  "input": {
    "scene": "support"
  }
}

ChatReplyRequest 要求：

• message 必填。
• session_id 使用 UUID。
• input 使用数组。

统一响应

控制器统一返回 AiRuntimeResult：

{
  "content": "模型输出",
  "record_id": 1,
  "record": {},
  "file_path": null,
  "structured_output": null,
  "meta": {
    "session_id": "..."
  }
}

关键服务

类	作用
AiRuntimeService	运行时总入口，负责解析配置、执行调用、记录结果
DynamicAiProviderRegistry	将数据库中的服务商配置临时注册到 config('ai.providers')
PromptComposer	组合系统提示词和运行输入
PromptTemplateRenderer	把字符串或数组输入渲染为运行 Prompt
ConversationContextBuilder	读取最近消息并构造对话上下文
OutputSchemaCompiler	将后台 Schema 配置编译为 SDK Schema
ConfiguredAgent	普通文本 Agent
ConfiguredStructuredAgent	结构化输出 Agent

后台开发入口

新增一个服务商

1. 在“服务商管理”创建服务商，选择 driver、填写地址和 API Key。
2. 在服务商下维护可用模型。
3. 使用“测试连接”验证当前配置。

新增一个智能体

1. 创建提示词，并绑定目标服务商。
2. 需要 JSON 输出时，先创建输出 Schema。
3. 创建智能体，选择服务商、提示词、能力和输出类型。
4. 在“智能体管理”中使用调试功能验证结果。

调整模型输出

• 改系统行为：调整提示词。
• 改响应结构：调整输出 Schema。
• 改模型参数：调整智能体的 max_tokens、temperature、top_p 和 options。