JeeSite 快速开发平台
官方网站
    • 平台简介
    • 架构特点
    • 技术选型
    • 功能介绍
    • 安装部署
    • 常见问题
    • 目录结构
    • 更新日志
    • Vue 文档
    • BPM 文档
    • Cloud 文档
Vue 演示
H5 演示
💪‌Skills
视频
抖音
💖联系
  • 我要提意见、文档纠错
  • JeeSite 代码库, 请⭐Star关注
  • JeeSite Vue 代码库, 请⭐关注
  • Spring Cloud 微服务架构
  • JeeSite 手机端/移动端
  • AI + RAG + CMS 人工智能
  • Flowable 中国式工作流
  • OAauth2 统一认证服务器
  • 政务内外网环境中间件
  • 访问 ThinkGem 官方博客
  • 点击进入,下拉查看动态
官方网站
    • 平台简介
    • 架构特点
    • 技术选型
    • 功能介绍
    • 安装部署
    • 常见问题
    • 目录结构
    • 更新日志
    • Vue 文档
    • BPM 文档
    • Cloud 文档
Vue 演示
H5 演示
💪‌Skills
视频
抖音
💖联系
  • 我要提意见、文档纠错
  • JeeSite 代码库, 请⭐Star关注
  • JeeSite Vue 代码库, 请⭐关注
  • Spring Cloud 微服务架构
  • JeeSite 手机端/移动端
  • AI + RAG + CMS 人工智能
  • Flowable 中国式工作流
  • OAauth2 统一认证服务器
  • 政务内外网环境中间件
  • 访问 ThinkGem 官方博客
  • 点击进入,下拉查看动态
源码仓库:JeeSite
前后分离:JeeSite Vue
微服务版:JeeSite Cloud
点个 ⭐ 吧!感谢您的支持 😘️
  • 快速了解

  • 后端开发手册

  • Vue前端手册

  • 经典前端手册

  • 扩展功能专题

    • AI 人工智能、智能体
      • 模块简介
      • 快速运行
        • 1、环境准备
        • 2、安装 Ollama 并拉取模型
        • 3、启动 Web 服务
        • 4、访问与登录
        • 5、初始化数据与菜单
        • 6、体验路径
        • 7、两个启动类的区别
        • 8、常见问题
      • 在线演示
      • 功能菜单
      • AI 智能体管理
        • 1、查询智能体
        • 2、新增或编辑智能体
        • 3、基本信息
        • 4、对话配置
        • 5、能力配置
        • 6、结合业务检索
        • 7、对话、启停与删除
      • AI 智能体对话
        • 1、进入与切换智能体
        • 2、界面上的提示文案
        • 3、一次完整对话
        • 4、回答区的信息
        • 5、配置项与页面对照
        • 6、对话历史
      • AI 模型管理
        • 1、查询模型
        • 2、新增或编辑模型
        • 3、模型类型
        • 4、聊天模型参数
        • 5、向量模型参数
        • 6、图像模型参数
        • 7、复制、停用与删除
      • AI 工具管理
        • 1、查询工具
        • 2、新增工具
        • 3、Bean 工具
        • 4、从 Bean 批量注册
        • 5、MCP 工具
        • 6、HTTP 工具
        • 7、调试工具
      • AI 向量库管理
        • 1、查询向量库
        • 2、新增或编辑向量库
        • 3、Simple(内存向量库)
        • 4、Redis(RedisSearch)
        • 5、PgVector(PostgreSQL)
        • 6、Chroma
        • 7、向量库与业务绑定
        • 8、向量库数据查询
        • 9、启停与删除
        • 10、手工部署参考
      • AI MCP 管理
        • 1、查询 MCP 服务
        • 2、新增 MCP 服务
        • 3、解析服务器地址
        • 4、自动同步工具
        • 5、调试 MCP 工具
        • 6、MCP 服务端与 yml 配置
      • AI 模型调用测试
        • 1、对话与结构化输出
        • 2、生图与识图
        • 3、MCP 工具调用
        • 4、运行前准备
        • 5、配置读取顺序
        • 6、预期结果与失败原因
    • BPM 业务流程系统
    • 消息推送、消息提醒
    • 单点登录、OAuth2
    • 作业监控、任务调度
    • 对象存储、文件存储
    • 用户类型、类型扩展
    • 可视化数据大屏
    • 在线报表设计器
    • 文件管理、文件柜
    • 在线预览图片文档
    • 手机端移动端、Uni-App
    • CMS 内容管理系统
    • 涉密 “三员” 管理
    • 敏感词库库管理
    • OAauth2 统一认证服务
    • AI CMS 模块(旧版)
  • 云服务技术架构

  • 技术支持与服务

AI、RAG、Tool、MCP、智能体、对话助手

# 模块简介

这是一套可配置的 AI 能力平台。模型、工具、知识库和智能体都在后台维护,业务系统通过对话或接口使用,不需要把 AI 逻辑写死在代码里。

与把 AI 参数写在配置文件里的做法不同,这里的模型、工具、MCP 服务、向量库和智能体都在管理界面维护,保存后即可生效,正常使用不需要改 yml,也不需要重启服务。

配置文件仍然保留,用于底层默认值和特殊场景(自定义扩展、MCP 服务端等),属于兜底手段,日常配置不用碰。

能力由六部分组成:

  • 模型接入:支持云端模型和本地部署的模型,如 Ollama、DeepSeek、通义千问;理论上兼容所有 OpenAI 接口标准的提供商,在“AI 模型管理”中注册。
  • 工具与 MCP 调用:本地 Bean、HTTP 接口和 MCP 远端工具都能注册为工具,模型在对话中按需调用,调用时保持当前用户会话,并受数据权限控制。
  • RAG 知识检索:CMS 文章正文和 filemanager 文件管理中的 word、excel、ppt、zip 等文件都可切片入库,检索结果交给模型整合回答;业务侧新增或变更的文章、文件会增量补充进向量库,不需要每次重建全量索引。向量库内置 Simple、Redis、PgVector、Chroma、Milvus、Elasticsearch 等类型,也可以按扩展方式接入。
  • 智能体编排:把模型、工具、MCP 服务、向量库业务和提示词组合成一个助手,对话页面按智能体切换。
  • 结构化输出:支持按约定的 JSON 结构返回结果,便于业务系统直接解析使用。
  • 集群部署:多节点下配置同样只需改一次,一个节点修改模型、工具、MCP 或向量库后,会通过 Redis 广播缓存失效通知,其它节点收到后清理本地缓存并按最新配置重建,不需要重启或手工清缓存;智能体配置不缓存,改完直接生效。该能力由 spring.cache.isClusterMode 开启,单机模式不产生额外的 Redis 调用。

适合希望在现有业务系统里快速接入 AI 能力的团队:既可以直接使用后台配置好的对话助手,也可以基于本文的接口和工具扩展方式做二次开发。

各部分的操作对应文档章节:模型、工具、MCP、向量库和智能体的配置,见“AI 模型管理”“AI 工具管理”“AI MCP 管理”“AI 向量库管理”“AI 智能体管理”;对话界面的使用见“AI 智能体对话”,结构化输出的调用方式见文末。

模块基于 Spring AI 实现,结构清晰、代码简洁,既适合正式项目使用,也适合作为学习 AI 开发的参考。

# 快速运行

本地体验最快的方式:安装 Ollama、拉取两个模型、启动 web-ai 工程。数据库用内置 H2 单文件库,向量库用内置的 Simple 内存向量库,不需要安装 MySQL、Redis 或单独的向量库服务。

# 1、环境准备

  • JDK 17 及以上,推荐使用 21 或更高版本
  • Maven 3.9 及以上(以本机实际环境为准)
  • Ollama (opens new window):本地大模型运行环境,用于运行对话模型和向量模型(本机没有也可先用云端模型)

# 2、安装 Ollama 并拉取模型

  1. 从 https://ollama.com/download (opens new window) 下载并安装 Ollama,安装后确认服务已启动。
  2. 终端执行命令,拉取对话模型:
ollama pull qwen3:8b
1
  1. 拉取向量模型:
ollama pull nomic-embed-text:latest
1
  1. 执行 ollama list,确认两个模型都已下载完成。

qwen3:8b 用于对话和工具调用,nomic-embed-text:latest 用于知识库向量化。模型记录在“AI 模型管理”中维护,本地 Ollama 的接口地址默认是 http://localhost:11434。

# 3、启动 Web 服务

  1. 用 IDEA 打开工程,运行 web-ai/web-ai/src/main/java/com/jeesite/modules/AiApplication.java 的 main 方法。
  2. 首次启动自动创建 H2 单文件数据库,文件位于 ~/jeesite/db/jeesite5200ai,账号密码均为 jeesite,不需要安装 MySQL。
  3. 启动类已内置 jeesite.initdata=true,首次启动会自动建表、写入字典和示例数据、创建 AI 菜单;初始化只在表不存在时执行,后续启动不会重复。
  4. 初始化数据预置了 Simple 内存向量库,不需要安装外部向量库;没有配置持久化文件时,应用重启后向量数据不保留,适合演示。
  5. 控制台出现“启动完成,访问地址”后表示启动成功。

默认服务配置(web-ai/web-ai/src/main/resources/config/application.yml):

server:
  port: 8980
  servlet:
    context-path: /js

jdbc:
  type: h2
  url: jdbc:h2:~/jeesite/db/jeesite5200ai
  username: jeesite
  password: jeesite
1
2
3
4
5
6
7
8
9
10

# 4、访问与登录

  1. 浏览器访问 http://127.0.0.1:8980/js (opens new window)。
  2. 使用账号 system、密码 admin 登录。
  3. 登录后左侧出现 AI 菜单,从“AI 智能体对话”开始体验。

# 5、初始化数据与菜单

首次启动会自动完成初始化,不需要手工执行脚本:创建 AI 相关数据表、写入字典和示例数据,并生成 AI 模块的 6 个菜单,具体入口见「功能菜单」。

  1. 启动完成后刷新页面,左侧出现 AI 菜单即表示初始化完成,可以从“AI 智能体对话”开始体验。
  2. 如果菜单没有出现,先确认启动日志中的初始化是否成功,以及当前账号是否有对应权限。

# 6、体验路径

  1. AI 模型管理:确认 qwen3:8b(聊天模型)和 nomic-embed-text:latest(多模态模型,即向量模型)已存在并启用。
  2. AI 工具管理、AI MCP 管理:按需注册或同步工具,默认会提供演示数据,不配置也可以先对话。
  3. AI 向量库管理:使用预置的 Simple 向量库,按业务新增绑定其它向量库。
  4. AI 智能体管理:新建或编辑智能体,选择模型,勾选工具和向量库业务,填写系统提示词。
  5. AI 智能体对话:选择智能体,输入问题或点击预设问题。

# 7、两个启动类的区别

  • AiApplication(工程 web-ai):AI Web 演示服务,端口 8980,提供后台管理、Vue 页面和全部 AI 菜单。
  • AiMcpApplication(工程 web-ai-mcp):配套的 MCP 服务端示例,端口 8992,默认以 STREAMABLE 协议在 /api/v1/mcp 暴露 MCP 服务,用于演示 MCP 工具调用(包含了一些演示 Tool 集合)。
  • MCP 工程有独立的 application.yml,默认连接 MySQL(jdbc:mysql://127.0.0.1:3306/jeesite_v5)和 Redis(127.0.0.1:6379),启动前要先准备好这两个服务(也可以切换到 h2 或暂时关闭 redis 连接,不影响测试)。
  • 不启动 MCP 工程不影响主流程;需要使用 MCP 时再单独启动,然后在“AI MCP 管理”里登记 http://127.0.0.1:8992/api/v1/mcp。
  • 启动顺序没有强制依赖:先启动 web-ai 完成登录和配置,再启动 web-ai-mcp,最后在界面里解析、同步和调试工具即可。

# 8、常见问题

Ollama 没有启动

对话时报连接失败或超时。先在终端执行 ollama list,能列出模型说明服务正常;再检查“AI 模型管理”中模型的接口地址是否为 http://localhost:11434。

端口被占用

启动日志提示 8980 端口已被使用。可用 lsof -i :8980 找到占用进程并结束,或修改 server.port;修改端口后,模型和 MCP 服务里配置的地址要同步调整。

首次启动比较慢

首次启动要建表并写入初始化数据,耗时比后续启动长,等控制台出现“启动完成”再访问。

模型没下载完就开始对话

会提示模型不存在或连接失败。等 ollama pull 执行完成,确认 ollama list 中能看到模型后再重试。

换成 MySQL 或外部向量库

MySQL:修改 jdbc 配置为实际数据库地址,并按项目说明启用对应的数据库驱动。 向量库:在“AI 向量库管理”中新增 Redis、PgVector、Chroma 等向量库,再到“向量库与业务绑定”里切换;各类型的安装步骤见“AI 向量库管理 -> 手工部署参考”。

# 在线演示

  • 地址:https://vue.jeesite.com/ai/agent/chat (opens new window)

# 功能菜单

模块初始化完成后,左侧菜单中会出现以下 6 个入口,覆盖对话和各类 AI 资源的日常维护。

AI 模块功能菜单

图:AI 模块的功能菜单,从上到下依次为对话、智能体、模型、工具、MCP、向量库。

  • AI 智能体对话:面向使用者的聊天界面,选择智能体后开始多轮对话。
  • AI 智能体管理:维护智能体的名称、头像、简介、系统提示词、欢迎语、预设问题,以及关联的模型、工具、MCP 服务和向量库。
  • AI 模型管理:注册聊天模型、向量模型、图像模型等,维护接口地址、密钥和模型参数。
  • AI 工具管理:注册供大模型调用的工具,支持本地 Bean、HTTP 接口和 MCP 远端工具,并可在线调试。
  • AI MCP 管理:维护 MCP 服务地址与传输方式,解析服务端的工具列表并同步到工具注册表。
  • AI 向量库管理:维护向量库连接,以及业务类型与向量库、向量模型的绑定关系。

菜单的父级目录、显示名称和排序以实际系统的初始化数据为准。

# AI 智能体管理

进入菜单:AI 智能体管理

智能体是模型、工具、知识库和提示词的组合:选一个聊天模型,挂上需要调用的工具和 MCP 服务,绑定要用到的向量库业务,再写系统提示词,就是一个可对话的 AI 助手。对话界面在“AI 智能体对话”中,按智能体切换。

AI 智能体管理列表

图:智能体列表,展示头像、名称、简介、AI 模型、系统提示词、欢迎语、预设问题等。

# 1、查询智能体

  1. 在顶部搜索区填写“名称”,或选择“AI 模型”“状态”。
  2. 点击「查询」执行查询,点击「重置」清空条件。
  3. 点击搜索区右侧的展开箭头,可显示更多条件,具体以界面实际字段为准。

列表默认按权重倒序排列,状态列显示当前是正常还是停用。

# 2、新增或编辑智能体

  1. 点击右上角「新增」,打开“新增智能体”抽屉;在列表中点击名称,或点击操作列的编辑图标,打开“编辑智能体”。
  2. 在“基本信息”中设置头像、名称、AI 模型、简介和权重。
  3. 在“对话配置”中编写系统提示词、欢迎语、预设问题、快捷指令和输入框提示。
  4. 在“能力配置”中勾选工具、MCP 服务和向量库绑定,按需修改回答模版。
  5. 点击「确认」保存。

编辑智能体

图:编辑智能体抽屉,按基本信息、对话配置、能力配置和备注分组。

# 3、基本信息

  • 头像:点击头像或「上传头像」选择图片,裁剪后上传;不设置时使用默认头像,对话界面和列表都取这张图。
  • 名称:必填,对话界面的智能体名称。
  • AI 模型:必填,从“AI 模型管理”中已启用的模型里选择,这里只应选聊天模型;模型配置、密钥都在 AI 模型管理中维护,这里不重复填写。
  • 简介:选填,100 字以内,显示在列表和对话页的智能体介绍中。
  • 权重:数值越大排序越靠前;勾选右侧“置顶”会把权重设为 9999,用于把常用智能体固定在最前。

# 4、对话配置

  • 系统提示词:设定角色、能力和回答风格,如“你是一名资深的 Java 开发专家”。使用 Markdown 编辑器,支持标题、列表、代码块等格式,内容越具体,回答越稳定。
  • 欢迎语:进入对话时显示在页面中间,200 字以内。
  • 预设问题:每行一个,最多 20 行,对话页最多展示 6 个,点击后直接作为提问发送。
  • 快捷指令:每行一个,最多 20 行,用于在对话页提供常用操作入口。
  • 输入框提示:输入框里的占位文字,如“请输入您的问题”。

系统提示词保存在智能体上,对话时随请求一起发送;修改保存后重新进入对话即可生效。

# 5、能力配置

能力配置决定智能体能“做什么”,三个多选框分别对应前面三个管理菜单,字段含义不在这里重复。

  • 工具调用:从“AI 工具管理”中勾选,可选 Bean、MCP、HTTP 三种来源的工具;未勾选时智能体不会调用任何工具。
  • MCP 服务:从“AI MCP 管理”中勾选,选中后该服务同步过来的工具会一并挂载到智能体,不需要再去工具列表逐个勾选。
  • 向量库绑定:从“AI 向量库管理 -> 向量库与业务绑定”中勾选业务,作为该智能体的知识库;检索条数、相似度阈值直接取业务绑定里的设置。
  • 回答模版:知识库问答的提示词模板,必须包含 {question_answer_context}(检索到的参考资料),可以用 {query} 引用用户问题,留空使用默认模板。

回答模版默认内容如下,没有特殊需要不用修改:

你是一个智能助手,可以基于以下参考资料回答用户的问题。

参考资料:
{question_answer_context}

问题:{query}
1
2
3
4
5
6

智能体绑定向量库业务后的效果

图:绑定“文件管理”“内容管理-文章”两个向量库业务后,对话时会分别检索这两个业务的数据。

占位符名称要和上面一致。截图示例中的写法是手工输入的,运行时不识别,复制模板时请以本节为准。

# 6、结合业务检索

知识来自绑定的向量库业务,主要包括 CMS 文章和 filemanager 文件管理中的文件。业务侧新增或变更的文章、文件会补充进向量库,智能体回答时结合这些内容,不需要每次重建全量索引。业务类型和检索参数见「AI 向量库管理 -> 向量库与业务绑定」,这里不重复。

# 7、对话、启停与删除

  1. 智能体对话:在列表操作列点击对话图标,直接进入该智能体的对话界面,用于配置后立即验证效果。
  2. 停用:把智能体状态改为停用,需要恢复时点「启用」。
  3. 启用:恢复可用状态。
  4. 删除:删除智能体记录,操作前确认没有业务在引用。

操作按钮受 ai:agent:edit 权限控制。

# AI 智能体对话

进入菜单:AI 智能体对话

对话页是智能体的使用入口,左边是会话历史,中间是聊天区,底部是输入框和工具栏。配置好的欢迎语、预设问题、快捷指令、输入框提示都会在这里出现。

智能体对话首页

图:对话首页,自上而下为智能体标题、欢迎语、猜测您想问、输入框和工具栏。

# 1、进入与切换智能体

  1. 从左侧菜单进入“AI 智能体对话”,默认打开权重最高的智能体。
  2. 顶部依次显示头像、智能体名称和简介;简介未填写时显示 暂无简介。
  3. 点击顶部智能体名称(下拉框),切换到其它智能体;切换后标题、头像、简介、欢迎语、预设问题和可用工具都会随智能体变化。
  4. 点击右上角编辑图标,直接打开当前智能体的编辑抽屉,改完保存即回到对话。
  5. 也可以在“AI 智能体管理”列表的操作列点对话图标,直接进入指定智能体。

# 2、界面上的提示文案

欢迎语显示在对话区中央,内容取自“AI 智能体管理 -> 对话配置 -> 欢迎语”。截图中的智能体配置为:

我能帮助你,相信我,我支持 Tool、MCP、向量库

没配置欢迎语时显示默认文案:

我是你的 AI 助手,我可以帮你解答一些问题。

预设问题的标题固定为:

猜测您想问:

下面列出该智能体配置的预设问题,截图中共 4 个:

获取当前用户信息 当前服务器时间 打开房间的灯 关闭房间的灯

预设问题来自“对话配置 -> 预设问题”,每行一个,页面最多展示 6 个,点击后直接作为一条提问发送。

输入框提示取自“对话配置 -> 输入框提示”,截图中的智能体配置为:

有什么帮助的,在这里尽情的说吧!

未配置时使用默认提示:

你有什么想知道的,快来问问我,Shift+Enter 换行,Enter 发送。

工具栏从左到右依次是:附件(图片,最多 3 张,支持 jpg、jpeg、png)、快捷指令下拉(占位文字为 快捷指令,内容取自“对话配置 -> 快捷指令”)、模型下拉、发送按钮。发送按钮在回答过程中变成停止按钮,点击可中断本次回答。

# 3、一次完整对话

  1. 选择一个智能体,确认标题和欢迎语。
  2. 在输入框输入问题,或点击一个预设问题。
  3. 按 Enter 发送,Shift+Enter 换行;也可以点右侧发送按钮。
  4. 回答过程中可以点停止按钮中断,已输出的内容保留。
  5. 继续追问时直接在输入框提问,当前会话的历史会一起带给模型。
  6. 需要换个话题时点左上角「新建对话」,会新建一条标题为“新对话”的会话,上下文从头开始;已有空会话时直接切过去,不会重复创建。
  7. 需要换助手时,从顶部下拉切换智能体;切换后清空当前对话区,并加载该智能体的会话历史。

# 4、回答区的信息

带深度思考和用量统计的回答

图:回答上方是可折叠的思考过程,下方是复制、重新回答和用量统计。

  • 深度思考:支持思考的模型会先输出思考过程,折叠条显示 已深度思考,生成中显示 正在思考,生成过程中自动展开,结束后可手动展开查看。
  • 工具调用:模型决定调用工具时,会在思考内容里说明准备调用哪个工具、为什么调用,以及调用返回的结果;界面不单独弹出工具调用面板。
  • 回答正文:工具返回的数据会整理成自然语言。截图中的智能体调用了当前用户信息工具,所以能看到用户名、用户编码、所属公司、用户状态、最后登录时间和 IP。
  • 复制:点击回答下方的复制图标,复制整段回答;纯代码块回答只复制代码正文。
  • 重新回答:点击刷新图标会重新生成当前回复,并删除该回复之后的对话,确认后执行。
  • 用量统计:回答下方显示 Tokens 输入 1292 · 输出 515 · 合计 1807 · 时间 13:45;模型配置了价格时,这里还会显示本次回答的 费用。

# 5、配置项与页面对照

  • 欢迎语 -> 对话区中央的首屏文案。
  • 预设问题 -> “猜测您想问:”下面的按钮,最多 6 个。
  • 快捷指令 -> 输入框左侧的 快捷指令 下拉,选中后回填输入框,可继续编辑再发送。
  • 输入框提示 -> 输入框的占位文字。
  • AI 模型 -> 输入框右侧的模型下拉,切换后会保存到该智能体,影响所有使用者。
  • 工具调用、MCP 服务 -> 回答时模型可调用的能力,调用过程体现在思考内容里。
  • 向量库绑定 -> 回答前的知识检索范围,检索结果由模型整合进回答。

# 6、对话历史

  • 新建对话:点击左侧顶部「新建对话」。
  • 重命名:悬停历史项,点击编辑图标修改标题,失焦保存。
  • 置顶:点击图钉图标置顶,再次点击取消置顶。
  • 删除:点击删除图标并确认,删除该会话记录。

# AI 模型管理

进入菜单:AI 模型管理

模型不再写死在 yml 配置文件里,改为在界面上注册。聊天模型、向量模型、图像模型都在这里维护,智能体再从已启用的模型中挑选。

AI 模型管理列表

图:AI 模型管理列表,展示模型名称、编码、描述、提供商、类型和接口地址,右侧为操作列。

# 1、查询模型

  1. 在顶部搜索区填写“模型描述”,或选择“提供商”“模型类型”。
  2. 点击「查询」执行查询,点击「重置」清空查询条件。
  3. 点击搜索区右侧的展开箭头,可显示更多条件:模型编码、模型名称、备注信息、状态。

列表默认按权重倒序排列,点击列头可切换排序,底部可切换每页条数。

# 2、新增或编辑模型

  1. 点击右上角「新增」,打开“新增模型”抽屉;在列表中点击模型名称,或点击操作列的编辑图标,打开“编辑模型”。
  2. 在“基本信息”中填写模型名称、模型编码、提供商、接口地址、模型类型,按需填写模型图标、接口 Key 和模型描述。
  3. 在“模型选项”中设置该类型对应的参数(详见下文各类型说明)。
  4. 点击「确认」保存,点击「取消」放弃修改。

新增/编辑模型表单

图:编辑模型抽屉,按“基本信息”“模型选项”“其它选项”“金额设置”分组。

各字段说明:

  • 模型名称:必填,来自模型厂商的模型标识,如 qwen3:8b、BAAI/bge-m3。
  • 模型编码:必填,系统内唯一标识,新建时按模型名称自动生成,规则是字母开头、只含字母数字减号和下划线;保存后不可修改。
  • 提供商:必填,取自字典 ai_model_provider。选择后会自动带出该提供商的默认接口地址,可手工改成代理或网关地址(需填写完整地址,包含 /v1)。
  • 模型图标:选填,用于列表和对话界面的图标展示。
  • 接口地址:必填,模型服务的完整访问地址,如 http://localhost:11434、https://api.siliconflow.cn/v1。
  • 接口 Key:选填,可直接填密钥,也可填环境变量引用,如 ${SFLOW_APP_KEY},避免密钥明文入库。再次编辑时未修改则保持原值。
  • 模型类型:必填,决定下面显示哪组模型选项,默认“聊天模型”。
  • 模型描述:选填,说明该模型的用途,如“本地模型”“向量测试”。

# 3、模型类型

模型类型决定调用方式和参数分组,可选项如下。

模型类型下拉选项

图:模型类型下拉框,包含聊天模型、多模态模型、图像模型、语音合成、语音转写、内容审核。

  • 聊天模型:对接聊天对话接口,显示对话参数和金额设置。
  • 多模态模型:对接向量化接口,显示“向量的维度”,用于知识库检索;BAAI/bge-m3 这类向量模型就选它。
  • 图像模型:对接文生图接口,显示图片尺寸、质量等参数。
  • 语音合成:对接文本转语音接口,显示音色、语速等参数。
  • 语音转写:对接语音转文本接口,显示转写语言、提示词等参数。
  • 内容审核:对接内容审核接口,无专属参数。

字典项的显示名称可能随版本调整,以下拉框中实际显示的选项为准。

# 4、聊天模型参数

“模型选项”中的参数随所选提供商变化。以 Ollama 提供商为例,包含以下参数。

  1. 生成随机性:对应 temperature,取值 0 到 2,值越大输出越随机。
  2. 生成采样率:对应 topP,取值 0 到 1,与生成随机性建议只调整其中一个。
  3. 生成多样性:对应 topK,默认 40,值越大结果越随机。
  4. 重复惩罚:对应 repeatPenalty,大于 1 时降低重复内容,默认 1.1。
  5. 最大回复数:对应 maxTokens,控制一次最多生成的 token 数,填 -1 表示不限制。
  6. 上下文长度:对应 numCtx,不填则使用模型默认值。
  7. 停止序列:对应 stop,多个值用英文逗号分隔。
  8. 随机种子:对应 seed,设置后在参数相同时尽量返回相同结果。
  9. 思考模式:对应 think,仅 Qwen3、DeepSeek-R1 等支持思考的模型有效。

选择其它提供商时,参数项会有差异,例如 OpenAI 兼容接口会显示“存在惩罚”“最大推理回复数”“推理强度”“严格模式”等,具体以界面实际显示为准。

“其它选项”中可设置超时时间、重试次数、拉取方式、附加模型和模型权重;拉取方式的可选值为“始终拉取,保持最新”“不存在的时候拉取”“不主动拉取模型”,本地已下载好的模型一般选择“不主动拉取模型”。

参数最终以 JSON 保存在模型的配置选项中,例如上面的 Ollama 本地模型:

{
  "chat": {
    "temperature": 1.0,
    "topP": 1.0,
    "topK": 40,
    "repeatPenalty": 1.1,
    "maxTokens": 4096,
    "think": true
  },
  "timeout": 5,
  "pullModelStrategy": "NEVER",
  "price": {
    "input": 2,
    "output": 3,
    "cache": 1,
    "unit": "1K",
    "currency": "CNY"
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

聊天模型还需要维护“金额设置”,用于统计对话消耗:

  • 输入价格:每个计价单位的输入价格,缓存未命中的部分按此价计算。
  • 输出价格:每个计价单位的输出价格,深度思考内容同样计入输出。
  • 缓存命中价格:缓存命中部分的单价,留空则按输入价格计算。
  • 计价单位:每千 Token(1K)、每百万 Token(1M)或每个 Token。
  • 金额币种:人民币(CNY)或美元(USD)。

金额设置只在模型类型为“聊天模型”时显示。

# 5、向量模型参数

向量模型用于知识库检索,关键在于“向量的维度”要和模型要求一致。

向量模型的配置

图:以 BAAI/bge-m3 为例,模型类型选择多模态模型后,模型选项为“向量的维度”。

  1. 模型类型选择“多模态模型”。
  2. 在“向量的维度”中填写该模型的输出维度,如 384、512、768、1024。
  3. 接口地址填写向量服务的地址,如 https://api.siliconflow.cn/v1。
  4. 其它选项中的“组织 ID”一般无需填写。

维度必须与模型实际输出一致,否则向量入库和检索都会失败;具体数值以模型厂商文档为准。

# 6、图像模型参数

图像模型用于文生图,参数项与聊天模型不同。

图像模型的配置

图:以 Kwai-Kolors/Kolors 为例,模型类型为图像模型时的参数。

  1. 模型类型选择“图像模型”。
  2. 图片尺寸:下拉选择,如 1024x1024。
  3. 图片质量:下拉选择,如 auto。
  4. 图片风格、图片格式:非必填,按需选择。
  5. 生成数量:一次请求生成的图片数量,默认 1。
  6. 超时时间:生图耗时较长,默认 15m,支持 15m、300s、600 等写法。

# 7、复制、停用与删除

复制模型操作

图:操作列中的复制图标,鼠标悬停显示“复制模型”。

  1. 复制:以当前模型为模板打开“新增模型”,模型编码和接口 Key 需要重新填写,其余参数原样带入,适合快速新增同厂商的其它模型。
  2. 停用:停用后该模型不再出现在智能体和对话的可用模型列表中。
  3. 启用:对已停用的模型恢复可用状态。
  4. 删除:删除该模型记录,操作前请确认没有智能体或业务在使用该模型。

操作按钮受 ai:model:edit 权限控制。

旧版本在 spring.ai.model.chat 等 yml 配置中指定模型,新版本以本页面注册的模型为准。底层可调参数仍可参考 jeesite-ai-core.yml、jeesite-ai-cms.yml 中的注释,具体以实际版本的文件内容为准。

# AI 工具管理

进入菜单:AI 工具管理

工具调用 Tool Calling(也称 Function Calling)是人工智能应用程序中的常见模式,允许模型与一组 API 或工具交互,从而增强其功能。

新版把工具统一注册在“AI 工具管理”中,工具来源分三种:本地 Bean、MCP 远端工具、HTTP 接口。注册后可在智能体里勾选,模型会在对话中按需调用,调用时保持当前用户会话,并受数据权限控制。

AI 工具管理列表

图:工具列表,展示工具名称、描述、类型、权重、状态和更新时间,同一个工具可以分别以 Bean 和 MCP 两种来源注册。

# 1、查询工具

  1. 在顶部搜索区填写“工具名称”或“工具描述”,或选择“工具类型”。
  2. 点击「查询」执行查询,点击「重置」清空条件。
  3. 点击搜索区右侧的展开箭头,可显示更多查询条件,具体以界面实际字段为准。

列表默认按权重排序,状态为“正常”的工具才会被智能体加载。

# 2、新增工具

  1. 点击右上角「新增」,打开“新增工具”抽屉。
  2. 填写“基本信息”:工具名称、工具编码、工具描述,选择工具类型。
  3. 按工具类型补充对应的专属字段(见下文)。
  4. 填写权重,权重越大排序越靠前。
  5. 点击「确认」保存。

保存时后台会立即加载一次工具做校验,提示“保存并加载成功,共 N 个工具”表示配置可用;提示“保存成功,但工具加载失败”时按后面的报错信息修正配置。

通用字段说明:

  • 工具名称:必填,必须与源端工具名一致。Bean 工具对应 @Tool(name),MCP 工具对应远端工具名;从 Bean 同步时以源端名称为准。
  • 工具编码:必填,即模型侧的函数名,只能使用字母、数字、下划线和减号,保存后不可修改。
  • 工具描述:交给大模型判断是否调用,建议写清用途和触发场景。
  • 工具类型:必填,可选 Bean、MCP、HTTP,切换类型后下方字段随之变化。
  • 权重:选填,控制列表和加载顺序。

# 3、Bean 工具

本地 Java 方法通过 @AiTools 和 @Tool 注解暴露给大模型,是接入业务逻辑最直接的方式。

Bean 类型工具的表单

图:工具类型选择 Bean 时,需填写 Bean 名称,并可指定生图模型。

  1. 工具类型选择「Bean」。
  2. Bean 名称:必填,填 Spring Bean 名称,取自类上的 @AiTools("Bean名"),如 localUserAiTools。
  3. 生图模型:仅生图类工具需要,选择模型类型为图像模型的模型;留空时使用 AI 模型中权重最高的图像模型。
  4. 工具名称和工具编码按 Bean 中 @Tool 方法名填写,保存时后台会按 Bean 名称查找并加载。

实例代码见 modules/ai/ai-tools/src/main/java/com/jeesite/modules/ai/tools/ 下的 TestAiTools.java、UserAiTools.java,照着写自己的 Bean 即可让 AI 调用你的 Java 实现。

# 4、从 Bean 批量注册

Bean 里已经写好的工具,可以一次扫描出来批量注册,不用手工逐个新增。

从 Bean 注册工具对话框

图:输入实现 Bean 名称后点击「解析」,下拉选项来自后端扫描到的 @AiTools 注解 Bean。

  1. 点击列表右上角「从 Bean 注册」。
  2. 在“实现Bean名称”中选择或手工输入 Bean 名称,点击「解析」。
  3. 解析结果会列出该 Bean 下所有 @Tool 方法。
  4. 勾选要注册的工具,工具编码按“Bean 名_工具名”生成。
  5. 点击「确认同步工具」写入工具注册表。

解析出的工具列表

图:解析结果包含工具名、工具描述和状态,已存在的工具显示“已注册”,可只勾选新增项。

需要删除时,在同一个对话框里勾选工具后点击「删除选中」,即可移除该 Bean 注册的工具。

# 5、MCP 工具

MCP 工具由 MCP 服务端提供,这里只做注册和关联,工具的具体能力在 MCP 服务端实现。

MCP 类型工具的表单

图:工具类型选择 MCP 时,需要指定所属的 MCP 服务。

  1. 工具类型选择「MCP」。
  2. 所属MCP:必填,选择已维护的 MCP 服务,如 demo-mcp。
  3. 工具名称填写 MCP 服务端的原始工具名,如 server-time。
  4. 工具编码按“MCP 编码_工具名”的形式生成,如 demo-mcp_server-time。

MCP 服务的地址和传输方式在“AI MCP 管理”中维护,详见后文「AI MCP 管理」。

# 6、HTTP 工具

已有现成的 HTTP 接口时,可以直接注册成工具,不需要写 Java 代码。

HTTP 类型工具的表单

图:工具类型选择 HTTP 时,需要填写请求地址、请求方式、参数定义、请求头和超时时间。

  1. 工具类型选择「HTTP」。
  2. 请求地址:必填,填写完整地址,如 https://api.example.com/v1/weather。
  3. 请求方式:选择 GET 或 POST,默认 POST;GET 时 URL 上的查询参数会按参数定义拼接。
  4. 参数定义:填写 JSON Schema,描述模型可以传哪些参数。
{"type":"object","properties":{"city":{"type":"string","description":"城市名称,如:北京"}},"required":["city"]}
1
  1. 请求头:每行一个,格式为 Header-Name: 值,如 Authorization: Bearer xxx;值支持环境变量引用,如 ${API_TOKEN}。保存后再次编辑时,密钥类请求头显示为星号,不修改则保持原值。
  2. 超时秒数:选填,默认值以界面提示为准。

HTTP 工具会让模型访问外部地址,生产环境建议在配置文件里限制可用范围:

ai:
  tool:
    http:
      # 是否允许使用 HTTP 工具
      enabled: true
      # 允许访问的域名白名单,逗号分隔,支持后缀匹配
      allowHosts: jeesite.com,demo.jeesite.com
      # 是否允许访问内网、本机地址,默认禁止,防止 SSRF
      allowPrivateAddress: false
      # 是否允许 http 协议,生产环境建议改为 false
      allowHttpProtocol: true
      # 响应内容最大字符数,超出部分截断
      maxResponseSize: 262144
1
2
3
4
5
6
7
8
9
10
11
12
13

# 7、调试工具

编辑工具时,抽屉底部有「调试工具」按钮,可以按当前表单里的配置直接调用一次工具,未保存的修改同样生效。

工具调试弹窗

图:调试工具弹窗,顶部显示工具名称和类型,参数按参数定义生成示例,执行结果显示在下方。

  1. 在工具列表点击工具名称,或点击操作列的编辑图标,打开编辑抽屉。
  2. 点击抽屉底部的「调试工具」。
  3. 弹窗顶部确认工具名称和类型,如 server-time(mcp)。
  4. 在“调用参数(JSON,已按参数定义生成示例)”中按需修改参数;工具没有参数定义时显示 {}。
  5. 点击「执行」。
  6. 在“执行结果”中查看返回值;参数不是合法 JSON 时会提示“调用参数不是合法的 JSON,请检查”,调用失败时这里显示错误信息。
  7. 点击「关闭」退出,确认配置无误后再点「确认」保存。

调试只验证工具能否调通,弹窗里改的参数不会写回工具配置。

MCP 类型工具在“AI MCP 管理”里也能调试,两者调用同一套逻辑,区别见「AI MCP 管理 -> 调试 MCP 工具」。

调试 MCP 的 STDIO 传输时要注意:STDIO 等于让服务在本机执行命令,默认关闭,需要在配置中显式开启。

ai:
  mcp:
    stdio:
      enabled: false
      # 允许执行的命令白名单,逗号分隔
      allowCommands: npx,uvx,node,java,python,python3
      # 是否禁止命令行中的 shell 元字符,防止命令注入
      denyShellChars: true
1
2
3
4
5
6
7
8

# AI 向量库管理

进入菜单:AI 向量库管理

向量库用于知识库检索(RAG):业务数据切片后由向量模型转成向量存进去,提问时先检索相似片段,再交给大模型整合回答。不同业务可以分别入库、分别检索。连接信息、索引参数和业务绑定都在这个菜单里维护。

下面是平台内置的几种向量库示例(Simple、Redis、PgVector、Chroma,以及下拉中的 Milvus、Elasticsearch)。实际支持的类型取决于当前版本的实现,也可以按扩展方式接入其它向量库。内置的模型清单同理,不代表全部。

AI 向量库管理列表

图:向量库列表,展示名称、描述、提供商、权重、状态和服务地址。

# 1、查询向量库

  1. 在顶部搜索区填写“向量库名称”“向量库描述”,或选择“提供商”。
  2. 点击「查询」执行查询,点击「重置」清空条件。
  3. 点击搜索区右侧的展开箭头,可显示更多条件,具体以界面实际字段为准。

# 2、新增或编辑向量库

  1. 点击右上角「新增」,打开“新增向量库”抽屉。
  2. 在“基本信息”中填写向量库名称、向量库编码、向量库描述,选择提供商和权重。
  3. 在“存储选项”“连接信息”等分组中填写该提供商对应的参数(见下文各类型说明)。
  4. 点击「确认」保存,点击「取消」放弃修改。

编辑向量库的基本信息

图:以 Simple 为例,基本信息包含名称、编码、描述、提供商和权重。

通用字段说明:

  • 向量库名称:必填,页面上显示的名称,如“简单内存向量库”。
  • 向量库编码:必填,全局唯一,供知识库和智能体引用,如 simple;保存后不可修改。
  • 向量库描述:选填,说明用途,如“适合功能演示”。
  • 提供商:必填,决定下方显示哪组连接参数。
  • 权重:必填,多个知识库同时检索时按权重融合,推荐 10。
  • 备注信息:选填。

向量库提供商下拉选项

图:提供商下拉框,内置 Simple、Chroma、PgVector、Redis、Milvus、Elasticsearch。

提供商由后端接口 AiVectorFactory 的实现类支撑(现有实现位于 com.jeesite.modules.ai.factory.vector 包),前端参数表单放在 vector/provider 目录,一个提供商对应一个配置文件。新增其它向量库时,按这个方式实现接口并补充表单即可,具体步骤以实际版本代码为准。

# 3、Simple(内存向量库)

无需外部服务,适合演示和测试,数据量小。

  1. 提供商选择「Simple」。
  2. 持久化文件:填写文件名,如 vector-store.json;文件固定保存在 {用户主目录}/jeesite/vector 目录,只允许字母、数字、下划线和减号。
  3. 留空表示纯内存存储,应用重启后数据丢失;配置文件后数据可保留,但不支持多实例部署。
  4. 点击「确认」保存。

参数位置见上方基本信息截图中的“存储选项”分组。

# 4、Redis(RedisSearch)

使用 Redis Stack 的向量检索能力,底层依赖 RedisSearch 模块建立向量索引并执行相似度查询,因此 Redis 服务需要具备 RedisSearch 功能(Redis Stack 自带,普通 Redis 需要单独安装模块)。

Redis 向量库的连接与索引参数

图:Redis 提供商需要填写连接信息、索引选项、HNSW 参数和其它选项。

  1. 提供商选择「Redis」。
  2. 服务地址:填 Redis 连接串,如 redis://127.0.0.1:16379/0。
  3. 用户名、密码或密钥:按 Redis 实际配置填写,没有密码可留空;再次编辑时密码显示为星号,不修改则保持原值。
  4. 索引选项:
    • Key 前缀:向量数据的键前缀,如 embedding:。
    • 向量算法:默认 HNSW。
    • 距离度量:默认 COSINE。
  5. HNSW 参数:每节点连接数(默认 16)、建索引候选数(默认 200)、检索候选数(默认 10)。
  6. 其它选项:初始化索引开关(默认开启),连接超时(默认 2000,单位毫秒)。
  7. 点击「确认」保存。

# 5、PgVector(PostgreSQL)

使用 PostgreSQL 的 vector 扩展存储向量。

PgVector 向量库的连接与表结构参数

图:PgVector 提供商需要填写连接信息,以及表结构初始化相关的开关。

  1. 提供商选择「PgVector」。
  2. 服务地址:填 JDBC 地址,如 jdbc:postgresql://127.0.0.1:5433/jeesite-ai。
  3. 用户名、密码或密钥:数据库账号,如 postgres。
  4. 主键类型:下拉选择,默认 TEXT。
  5. 索引类型:默认 HNSW;距离类型默认 COSINE_DISTANCE。
  6. 批量写入大小:一次写入的文档数量,默认 10000。
  7. 表结构选项:
    • 初始化表结构:默认开启,保存后自动建表和索引。
    • 重建向量表:默认关闭,开启后会删除并重建已有向量表,仅在需要清空数据时使用。
    • 模式名称:默认 public。
  8. 点击「确认」保存。

# 6、Chroma

使用 Chroma 服务存储向量,按集合隔离数据。

Chroma 向量库的连接与集合参数

图:Chroma 提供商需要填写服务地址,并设置集合初始化选项。

  1. 提供商选择「Chroma」。
  2. 服务地址:填 Chroma 服务地址,如 http://127.0.0.1:8000。
  3. 用户名、密码或密钥:按实际部署填写,未开启认证可留空。
  4. 集合选项:
    • 初始化集合:默认开启。
    • 重建集合:默认开启,请确认是否需要清空已有数据。
  5. 点击「确认」保存。

# 7、向量库与业务绑定

不同业务的数据可以分别写入向量库,智能体对话时按绑定的业务范围检索,再把检索结果带进上下文一起回答。整条链路是:

  1. 业务数据写入:文章、文件等业务内容保存时,由业务模块调用向量库写入,入口在各业务自己的保存逻辑里。
  2. 向量化入库:按绑定的向量模型把内容切片转成向量,写入绑定的索引(集合或表),元数据同时记录业务标识。
  3. 按业务检索:对话时,智能体按绑定的业务类型找到对应的向量库、索引和向量模型,只在该索引内检索。
  4. 整合回答:检索到的片段作为上下文交给大模型,生成最终回答。

绑定关系在“AI 向量库管理”里建立,一个业务类型对应一条绑定记录,同一个向量库连接可以被多个业务共用,各自使用独立索引。

  1. 在向量库列表工具栏点击「绑定业务」,打开“向量库绑定”弹窗。
  2. 点击「新增绑定」,打开“新增向量库绑定”抽屉。
  3. 填写业务名称、业务类型,选择向量库和向量模型。
  4. 填写索引名称、向量维度、检索条数、相似度阈值和权重。
  5. 点击「确认」保存。

向量库绑定列表

图:绑定列表,按业务名称、业务类型、向量库、向量模型、索引名称、向量维度展示,可编辑或删除。

编辑向量库绑定

图:编辑绑定抽屉,业务名称和业务类型决定这条绑定服务的业务范围。

字段说明:

  • 业务名称:必填,便于识别的名称,如“内容管理-文章”。
  • 业务类型:必填,业务代码,如 cms-article、filemanager;检索时按它找到对应绑定,相当于业务标识。
  • 向量库:必填,选择已维护的向量库连接。
  • 向量模型:必填,选择用于向量化的模型,如 nomic-embed-text:latest。
  • 索引名称:必填,该业务在向量库中的索引名,如 vector_store_cms_article;不同业务用不同索引,实现数据隔离。
  • 向量维度:必填,必须与所选向量模型的输出维度一致,如 768。
  • 检索条数:必填,一次检索返回的片段数量,默认 6。
  • 相似度阈值:必填,0 到 1 之间,越大越严格,默认 0.60。
  • 权重:必填,多个业务同时检索时按权重融合,推荐 10。

业务类型是检索范围的依据:同一个向量库里,不同业务写入各自的索引,检索时只查绑定给该业务的那个索引,不会串数据。

# 8、向量库数据查询

数据查询用于核对某个业务实际写入了哪些内容,排查“检索不到”的问题。

向量库数据查询

图:数据查询弹窗,选择业务类型后按查询内容做相似度检索,结果按文档展示。

  1. 在绑定列表点击「数据查询」,或在向量库列表工具栏点击「数据查询」。
  2. 业务类型:必填,下拉中显示“业务名称 - 业务类型(向量库编码 / 索引名称)”,如“文件管理 - filemanager(simple / vector_store_filemanager)”。
  3. 过滤条件:选填,按元数据过滤,语法以界面提示为准。
  4. 查询内容:填写要检索的文本。
  5. 返回条数:默认 20。
  6. 点击「查询」,下方列表展示序号、文档编号、内容和元数据;点击「重置」清空条件。

业务类型下拉实际上就是在选检索范围:选中哪条绑定,就查哪个向量库的哪个索引。

元数据列展示写入时附加的业务属性。以内容管理文章为例,包含 bizType、id、title、url、categoryCode、categoryName、siteCode、status 等字段;其它业务写入哪些元数据,取决于该业务的入库实现。

# 9、启停与删除

  1. 停用:停用后该向量库不再参与检索和写入,调用时会提示“向量库已停用”。
  2. 启用:恢复可用状态。
  3. 删除:删除向量库记录,操作前请确认没有业务绑定在使用它。

操作按钮受 ai:vector:edit 权限控制。

# 10、手工部署参考

以下命令和建表语句用于手工准备向量库服务,按需使用。连接信息仍然在“AI 向量库管理”里填写,不需要改 yml。

# 安装 Chroma

docker run -d --name chroma -p 8000:8000 ghcr.io/chroma-core/chroma:1.0.0
1

# 安装 PGVector

docker run -d --name pgvector -p 5433:5432 -e POSTGRES_USER=postgres \
              -e POSTGRES_PASSWORD=postgres pgvector/pgvector:pg17
1
2
  • 进入容器
docker exec -it pgvector psql -U postgres
1
  • 建库语句
CREATE DATABASE "jeesite-ai";

-- 激活数据库
\connect "jeesite-ai";

-- 建立数据表和索引
CREATE EXTENSION IF NOT EXISTS vector;
CREATE EXTENSION IF NOT EXISTS hstore;
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";

-- 使用 all-minilm 模型时创建
DROP TABLE IF EXISTS vector_store_384;
CREATE TABLE IF NOT EXISTS vector_store_384 (
	id varchar(64) DEFAULT uuid_generate_v4() PRIMARY KEY,
	content text,
	metadata json,
	embedding vector(384)
);
CREATE INDEX ON vector_store_384 USING HNSW (embedding vector_cosine_ops);

-- 使用 nomic-embed-text 模型时创建
DROP TABLE IF EXISTS vector_store_786;
CREATE TABLE IF NOT EXISTS vector_store_786 (
	id varchar(64) DEFAULT uuid_generate_v4() PRIMARY KEY,
	content text,
	metadata json,
	embedding vector(768)
);
CREATE INDEX ON vector_store_786 USING HNSW (embedding vector_cosine_ops);

-- 使用 bge-m3 模型时创建
DROP TABLE IF EXISTS vector_store_1024;
CREATE TABLE IF NOT EXISTS vector_store_1024 (
	id varchar(64) DEFAULT uuid_generate_v4() PRIMARY KEY,
	content text,
	metadata json,
	embedding vector(1024)
);
CREATE INDEX ON vector_store_1024 USING HNSW (embedding vector_cosine_ops);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

# AI MCP 管理

进入菜单:AI MCP 管理

MCP(Model Context Protocol)是模型与外部工具之间的标准协议。这一节维护 MCP 服务的地址和传输方式,解析出服务端提供的工具,再同步到工具注册表,供智能体勾选使用。

AI MCP 管理列表

图:MCP 服务列表,展示名称、描述、传输类型、服务地址、权重、状态和更新时间。

# 1、查询 MCP 服务

  1. 在顶部搜索区填写“MCP名称”“MCP描述”,或选择“传输类型”。
  2. 点击「查询」执行查询,点击「重置」清空条件。
  3. 点击搜索区右侧的展开箭头,可显示更多条件,具体以界面实际字段为准。

# 2、新增 MCP 服务

  1. 点击右上角「新增」,打开“新增 MCP 服务”抽屉。
  2. 在“基本信息”中填写协议名称、MCP 编码和协议描述。
  3. 在“连接配置”中选择协议类型,填写服务地址、请求头和超时秒数。
  4. 在“其它信息”中填写权重和备注。
  5. 点击「确认」保存,保存时后台会自动连接一次并同步工具。

新增/编辑 MCP 服务表单

图:编辑 MCP 服务抽屉,底部“工具箱”展示该服务解析到的工具及同步状态。

字段说明:

  • 协议名称:必填,页面上显示的名称,如“演示 MCP 服务”。
  • MCP 编码:必填,全局唯一,供工具和智能体引用,如 demo-mcp;保存后不可修改。
  • 协议描述:选填,说明该服务的用途。
  • 协议类型:必填,可选 Streamable_HTTP、SSE、Stdio,默认 Streamable_HTTP。
  • 服务地址:非 Stdio 类型必填,填 MCP 服务的完整地址。
  • 请求头:JSON 键值对,用于认证或自定义标识,如 {"Authorization":"Bearer xxx"};值支持环境变量引用,如 ${API_TOKEN}。再次编辑时密钥类值显示为星号,不修改则保持原值。
  • 命令行、环境变量:仅 Stdio 类型显示,命令行填本地可执行命令及启动参数,如 npx -y @modelcontextprotocol/server-filesystem /tmp。
  • 超时秒数:超时时间,单位秒,默认 60。
  • 权重:数值越大排序越靠前,列表默认按权重倒序排列。

服务地址按协议类型填写:

  • Streamable_HTTP:http://127.0.0.1:8992/api/v1/mcp,不带路径时自动追加端点 /mcp。
  • SSE:http://127.0.0.1:8992/api/v1/sse,不带路径时自动追加端点 /sse。
  • Stdio:不填服务地址,改为填写命令行和环境变量。

# 3、解析服务器地址

“解析”用于在保存前验证配置:按当前表单内容连接 MCP 服务,读取工具列表,但不保存配置。

  1. 在“服务地址”(或 Stdio 的“命令行”)右侧点击「解析地址」。
  2. 系统立即按当前表单内容连接服务,读取服务端提供的工具清单。
  3. 结果显示在下方“工具箱”中,提示“解析成功,共 N 个工具”;连接失败时按提示检查地址、请求头和 MCP 服务是否已启动。
  4. 解析过程中按钮变为「停止解析」,点击可中断本次请求。
  5. 切换协议类型会清空工具箱,避免看到上一次协议解析的结果。

工具箱中的每一行显示工具名称、描述和状态:新解析出来的工具显示“未同步”,已存在对应记录时显示“已同步”或“已停用”。

# 4、自动同步工具

同步会把 MCP 服务端的工具写入“AI 工具管理”,智能体就能像使用本地工具一样调用它们。

  1. 保存 MCP 服务时,后台自动执行一次同步,提示“保存并同步工具成功,共 N 个工具:xxx”。
  2. 已保存过的服务,也可以点击工具箱右上角的「同步工具」,按当前表单配置再同步一次;新建的服务需要先保存。
  3. 同步完成后,到“AI 工具管理”列表按工具类型 MCP 筛选,即可看到新同步的工具。

同步规则:

  • 同步位置:写入 AI 工具管理,工具类型为 MCP,所属 MCP 为该服务编码。
  • 工具编码:按“MCP 编码_工具名”生成,如 demo-mcp_server-time;工具名称直接取远端工具名。
  • 重复同步:按工具编码匹配,已存在的记录只更新名称、描述、类型和归属,不会产生重复数据,新增的工具才会插入。
  • 源端已删除:再次同步时,该服务下本次没有返回的工具会自动停用,已停用的记录不会删除。
  • 服务状态联动:停用 MCP 服务会同步停用其全部工具;删除 MCP 服务会一并删除这些工具。
  • 同步失败:保存时提示“保存成功,但同步工具失败:…”,表示配置已保存、工具未同步,修正配置后点「同步工具」重试即可。

# 5、调试 MCP 工具

调试用于验证服务是否连通、工具参数是否正确,调用结果直接显示在弹窗里。

MCP 工具调试弹窗

图:调试工具弹窗,上方显示所属 MCP 服务并选择工具,下方填写参数、查看执行结果。

  1. 在 MCP 编辑抽屉底部点击「调试工具」,或在列表操作列点击调试图标。服务需要先保存,且工具箱里已有工具;没有工具时先点「解析地址」。
  2. 在“工具”下拉框中选择该服务下的一个工具,如 server-time。
  3. 在“调用参数(JSON)”中填写参数,例如:
{
  "city": "北京"
}
1
2
3
  1. 点击「执行」。
  2. 在下方“执行结果”中查看返回内容;调用失败时这里显示错误信息,例如工具不存在、参数不合法或连接超时。
  3. 点击「关闭」退出,调试不会修改工具注册表数据。

调试使用的是已保存的服务配置,改了地址、请求头后要先保存再调试。

这里的调试和“AI 工具管理”里的调试功能一致,区别只在入口和工具范围:

  • AI MCP 管理:针对某个 MCP 服务,可在同一弹窗里切换该服务下的任意工具,参数由手工填写。
  • AI 工具管理:针对某一条已注册的工具,参数按该工具的参数定义自动生成示例。

# 6、MCP 服务端与 yml 配置

平台内置了 MCP 服务端示例 web-ai-mcp(启动类 AiMcpApplication),默认使用 STREAMABLE 协议,启动后即可在“AI MCP 管理”里登记。

spring:
  ai:
    mcp:
      server:
        enabled: true
        name: jeesite-mcp-server
        version: 1.0.0
        type: SYNC
        protocol: STREAMABLE
        streamable-http:
          mcp-endpoint: /api/v1/mcp
        capabilities:
          tool: true
          resource: true
          prompt: true
          completion: true
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

对应地址:http://127.0.0.1:8992/api/v1/mcp。

MCP 规范已不建议使用 SSE,需要兼容旧客户端时可把协议改回 SSE,并配置 sse-endpoint、sse-message-endpoint;此时接口地址为 /api/v1/sse。

另外,旧版本通过 yml 维护 MCP 客户端连接,这种方式仍然可用,但不会同步工具到工具注册表,只适合临时验证或特殊场景。常规接入建议使用界面配置。

spring:
  ai:
    mcp:
      client:
        enabled: true
        sse:
          connections:
            jeesite:
              url: http://127.0.0.1:8992
              sse-endpoint: /api/v1/sse
1
2
3
4
5
6
7
8
9
10

聊天窗口询问“当前服务器时间”,在 MCP 服务端会显示调用日志,并返回相应信息。使用新版时,聊天模型在“AI 模型管理”中注册,不需要在 yml 里指定 spring.ai.model.chat。

# AI 模型调用测试

这一章用于在开发环境验证模型接入,不经过页面。三个测试类分工如下,配置全部来自“AI 模型管理”,不在代码里写死接口地址和 API Key。

  • AiModelChatTest:对话、结构化输出、向量模型、本地工具调用,共 5 个用例。
  • AiModelImageTest:生图与识图,共 1 个用例。
  • AiModelMcpTest:MCP 工具调用,共 1 个用例。

三个类都在 unit_test 环境下运行,指定测试启动类 ApplicationTest,继承 BaseSpringContextTests,方法按名称顺序执行:

// 三个类的类注解相同
@ActiveProfiles("unit_test")
@SpringBootTest(classes = ApplicationTest.class)
@TestMethodOrder(MethodOrderer.MethodName.class)
public class AiModelChatTest extends BaseSpringContextTests {
1
2
3
4
5

# 1、对话与结构化输出

对应测试类:AiModelChatTest。

依赖两个模型编码,另有一个工具编码常量:

private static final String MODEL_CODE_CHAT = "qwen3-8b";
private static final String MODEL_CODE_EMBEDDING = "nomic-embed-text-latest";
private static final String TOOL_CODES = "";
1
2
3

test01Text:文本对话

向对话模型发送一句自我介绍的中文问题,断言返回内容不为空。实际运行输出:

文本输出:我是通义千问,一个能够处理多种任务的对话模型,可以回答问题、创作文本,并支持多轮对话。
1

test02Json:结构化输出 JSON

要求模型从一段文本中提取 name、gender、age、city,用 MapOutputConverter 转成 Map,断言结果非空。实际运行输出:

JSON 输出:{"gender":"男","city":"北京市朝阳区","name":"张三","age":17}
1

test03Entity:结构化输出 Java 对象

先转成单个 PersonInfo,再转成 List<PersonInfo>,验证单对象和列表两种解析方式。实际运行输出:

Java 对象:{"age":28,"city":"上海市浦东新区","gender":"女","name":"李四"}
Java 对象列表:[{"age":17,"city":"北京市","gender":"男","name":"张三"},{"age":28,"city":"上海市","gender":"女","name":"李四"}]
1
2

test04Embedding:向量模型

对固定文本做向量化,断言返回向量非空且维度大于 0。实际运行输出:

向量维度:384
1

test05Tool:工具调用

先直接调用 server-time 验证工具实现可用,再把工具注册到 ChatClient,让模型自动发起 function calling。实际运行输出:

工具:server-time - 当前服务器日期时间,格式为 yyyy-MM-dd HH:mm:ss。
工具:root-light-switch - 控制指定房间的灯光开关。……
工具直调结果:"当前日期时间:2026-11-19 15:41:23"
工具调用结果:当前服务器时间是:2026-11-19 15:41:33
客厅的灯已成功打开,请查收反馈信息。
1
2
3
4
5

TOOL_CODES 为空时使用类内的本地 @Tool Bean TestAiTools,包含 server-time 和 root-light-switch 两个工具;填入工具编码后改为从“AI 工具管理”读取,读取失败会回退本地 Bean。

结构化输出的写法:

Map<String, Object> json = AiModelUtils.getChatClient(aiModel)
        .prompt()
        .system(JSON_ONLY_PROMPT)
        .user("从下面文本中提取人员信息,字段为 name、gender、age、city:……")
        .call()
        .entity(new MapOutputConverter());
assertNotNull(json);
assertFalse(json.isEmpty());
1
2
3
4
5
6
7
8

跳过条件:模型未注册、已停用或未配置接口地址;未找到可用工具;模型不支持 function calling。

# 2、生图与识图

对应测试类:AiModelImageTest。

依赖两个模型编码,其中识图模型必须是多模态模型:

private static final String MODEL_CODE_IMAGE = "kwai-kolors-kolors";
private static final String MODEL_CODE_VISION = "qwen3-vl-4b";
1
2

覆盖 test01ImageAndVision 一个用例,流程是:按模型配置生图,取回图片字节,再组装成多模态消息交给视觉模型描述。生图结果同时兼容 b64_json 和图片地址两种返回,图片地址按 5 分钟超时下载:

// AiModelImageTest(节选)
byte[] imageBytes = generateImage(imageModel,
        "一只可爱的橘猫坐在窗台上晒太阳,写真风格,柔和的光线");
Media media = Media.builder()
        .mimeType(getImageMimeType(imageBytes))
        .data(new ByteArrayResource(imageBytes) {
            @Override
            public String getFilename() {
                return "ai-image" + getImageExtension(imageBytes);
            }
        })
        .build();
1
2
3
4
5
6
7
8
9
10
11
12

验证点:生图返回的字节不为空;识图返回的文字不为空。图片类型按文件头识别 jpg 或 png。

实际运行输出:

生图成功,图片大小:1697470 字节
识图结果:这张图片展示了一只橘色长毛猫坐在窗台上,沐浴在温暖阳光中。……
1
2

生图返回的是图片字节,日志只记录大小,没有输出图片文件路径。

跳过条件:生图模型或识图模型未注册、停用、无接口地址;识图调用抛异常(多为模型不支持多模态),提示“识图失败(请配置多模态视觉模型)”。

# 3、MCP 工具调用

对应测试类:AiModelMcpTest。

依赖对话模型和 MCP 服务:

private static final String MODEL_CODE_CHAT = "qwen3-8b";
private static final String MCP_CODE = "jeesite-ai-mcp";
private static final String MCP_URL = "http://127.0.0.1:8992/api/v1/mcp";
1
2
3

覆盖 test01Mcp 一个用例:获取 MCP 工具列表,注册到 ChatClient,让模型自动调用 server-time 等 MCP 工具回答“当前服务器的日期和时间”。

MCP 服务按三级顺序取用:

  1. 按编码 jeesite-ai-mcp 查找“AI MCP 管理”中已启用且能取到工具的服务。
  2. 没有命中时,遍历所有启用的服务,取第一个类型为 streamable_http 或 sse 且可用的。
  3. 都没有时,探测本机 127.0.0.1:8992 端口(超时 2 秒),连通后临时创建 MCP 客户端,测试结束后在 @AfterEach 中释放。

实际运行输出:

使用 MCP 服务:演示 MCP 服务(http://127.0.0.1:8992/api/v1/mcp)
MCP 工具调用结果:当前服务器的日期和时间是:2026-11-19 15:42:07
1
2

这次运行先按 jeesite-ai-mcp 查询,结果为 Total: 0,即库里没有这条记录,随后命中已启用的 demo-mcp,与上面的取用顺序一致。该服务暴露 5 个工具:generate-image、server-time、root-light-switch、find-user-info、current-user。

跳过条件:对话模型不可用;未获取到 MCP 工具;模型不支持 function calling;MCP 服务端未启动或端口探测失败。

# 4、运行前准备

以下条件三个测试类通用,缺一项时对应的用例跳过,不判定为失败。

  1. 测试基座:unit_test 环境和 ApplicationTest 启动类需存在,工程自带。

  2. 模型记录:在“AI 模型管理”中注册 qwen3-8b、nomic-embed-text-latest、kwai-kolors-kolors、qwen3-vl-4b,状态为“正常”,接口地址不为空。

  3. 本地模型:qwen3-8b 和 nomic-embed-text-latest 对应 ollama pull qwen3:8b、ollama pull nomic-embed-text:latest。

  4. 识图模型:测试代码里的模型编码是 qwen3-vl-4b,本地 Ollama 的模型名是 qwen3-vl:4b,两者写法不同,拉取时用:

    ollama pull qwen3-vl:4b
    
    1

    在“AI 模型管理”中新增时,模型名称填 qwen3-vl:4b,模型编码按名称自动生成(即 qwen3-vl-4b),需与测试常量一致。识图必须选多模态模型,普通对话模型跑识图会跳过或失败。

  5. 生图模型:测试使用的是硅基流动的图像生成模型 kwai-kolors-kolors,需要先准备账号和密钥:

    1. 登录硅基流动控制台,在 API 密钥页面创建 API Key,形如 sk-xxx,不要使用真实密钥作为文档示例。
    2. 在“AI 模型管理”点击「新增」,按“基本信息”填写:提供商选硅基流动(以字典 ai_model_provider 实际选项为准),接口地址填 https://api.siliconflow.cn/v1,如账号区域或网关不同,按提供商官方文档填写。
    3. 模型名称按提供商文档中的模型标识填写,模型编码需为 kwai-kolors-kolors(新建时按名称自动生成,生成结果要与测试常量一致),模型类型选“图像模型”。
    4. 接口 Key 填入刚才创建的 Key,也可以填 ${SFLOW_APP_KEY} 这类环境变量引用,避免明文入库。
    5. 保存后,测试通过 AiModelUtils 读取该记录,不需要改 yml;表单其它字段的含义见「AI 模型管理 -> 基本信息」,这里不再重复。
  6. 工具:不需要额外配置,AiModelChatTest 默认用本地 @Tool Bean。

  7. MCP:需要验证 MCP 时,先启动 web-ai-mcp,或在“AI MCP 管理”中配置可用的 streamable_http 或 sse 服务。

  8. 运行位置:三个测试类位于 modules/ai/ai-core 模块(实际运行日志中的工作目录)。

三个类各自实现了同名的 getModelOrSkip,跳过规则一致:

assumeTrue(aiModel != null, "未在「AI模型」中配置" + modelType + "模型:" + modelCode);
assumeTrue(AiModel.STATUS_NORMAL.equals(aiModel.getStatus()), "模型已停用:" + modelCode);
assumeTrue(StringUtils.isNotBlank(aiModel.getBaseUrl()), "模型未配置接口地址:" + modelCode);
1
2
3

# 5、配置读取顺序

  1. 模型:以“AI 模型管理”中注册的记录为准,三个类都只按编码取用,不在 yml 中指定 spring.ai.model.chat。
  2. 工具:仅 AiModelChatTest 涉及,TOOL_CODES 非空时读“AI 工具管理”,为空或读取失败时回退本地 TestAiTools。
  3. MCP:仅 AiModelMcpTest 涉及,按“已配置编码 → 任一可用 HTTP 服务 → 本机默认地址”的顺序取用。
  4. 以上任一项取不到,用 assumeTrue 跳过当前用例,构建结果记为跳过而不是失败。

# 6、预期结果与失败原因

实际运行时,三个测试类共 7 个用例依次执行,没有跳过和失败记录,退出码为 0(JDK 17.0.17、Spring Boot 4.1.2、unit_test 环境)。正常情况下,控制台按类打印各自的日志头,AiModelChatTest 依次输出文本、JSON、Java 对象、向量维度、工具列表和工具调用结果;AiModelImageTest 输出图片大小与识图结果;AiModelMcpTest 输出 MCP 工具列表与调用结果。

跳过不算失败,常见原因:

  • 模型未注册、已停用或未配置接口地址。
  • 未找到可用工具,或未获取到 MCP 工具。
  • 模型不支持 function calling,工具或 MCP 用例跳过。
  • MCP 服务端未启动,端口探测 2 秒内连不上。
  • 识图模型不支持多模态。

失败时优先检查:

  • Ollama 是否启动,模型是否已 ollama pull 完成。
  • “AI 模型管理”中的模型编码、接口地址、API Key 是否与测试常量匹配,尤其 qwen3-vl-4b 是否已注册。
  • 生图返回图片地址时,本机能否访问该地址。
  • MCP 服务地址是否为 http://127.0.0.1:8992/api/v1/mcp,类型是否为 STREAMABLE。

模型、工具、MCP 的界面配置分别见「AI 模型管理」「AI 工具管理」「AI MCP 管理」,本地把服务跑起来见「快速运行」。

进入 JeeSite 源码仓库页面,点击右上角 ⭐ Star 加星关注。
若文档中存在疏漏或您有宝贵建议,敬请不吝告知,我们将非常感谢并及时跟进。

← 修改内置视图、修改登录页 BPM 业务流程系统→

联系我们:s.jeesite.com  |  微信号:jeesitex  |  邮箱:jeesite@163.com
© 2013-2026 济南卓源软件有限公司 版权所有 | Theme Vdoing

请关注 JeeSite 微信公众号,了解最新动态

  • 跟随系统
  • 浅色模式
  • 深色模式
  • 阅读模式