夜雨聆风一、写在前面
在AI大模型浪潮席卷全球的今天，Python几乎成了AI开发的"标配"。但对于占据企业应用半壁江山的Java技术栈团队来说，如何快速接入AI能力、构建生产级的AI Agent系统，一直是个难题。
今天，我们要介绍的 Snail AI，就是为Java/Spring技术栈量身打造的企业级AI Agent开源平台。
二、Snail AI 是什么?
Snail AI 是一款基于 Java 21 + Spring Boot 4 + Spring AI 2.0 构建的开源AI Agent平台，采用分布式Server-Agent架构，为企业提供安全、可控、可扩展的智能体开发与运行环境。
简单来说：
🤖 智能体管理：AI辅助一键创建，可视化配置提示词，内置智能体市场 🔌 客户端自主可控：拦截器深度介入AI交互全流程,本地工具执行数据不出域 📚 RAG知识库：支持10+文档格式，混合检索（向量+BM25+融合+重排） 🧠 多模型支持：统一接入OpenAI、Claude、Ollama、Gemini等主流大模型 🗄️ 多数据库适配：MySQL、PostgreSQL、SQL Server、达梦等，满足信创合规 🛠️ MCP工具集成：完整支持Model Context Protocol 📊 全链路追踪：Langfuse风格可观测性，瀑布图可视化各阶段耗时
三、为什么选择 Snail AI?
1. 深度拥抱Spring生态
不同于大多数AI框架使用Python开发，Snail AI 基于Spring AI 2.0构建，天然适合Java/Spring技术栈团队。无需学习新语言，用你最熟悉的Spring方式开发AI应用。
2. 分布式gRPC架构
采用Server-Agent分离架构：
Server端：负责编排调度、知识库管理、可观测性 Agent Client：负责实际执行，支持多节点水平扩展 gRPC双向流：高性能实时通信
3. 强大的拦截器机制
Agent Client SDK提供完整的拦截器链（Interceptor）和Advisor流水线，可在AI交互的每个环节深度定制：
请求前置处理（敏感词过滤、参数校验） 响应后置处理（内容审核、格式转换） 本地工具执行（数据不出域，满足企业安全合规）
4. 生产级RAG能力
不是玩具级的Demo，而是真正面向生产的RAG引擎：
10+文档格式：PDF、Word、Excel、Markdown、HTML等 4种分片策略：固定大小、段落、语义、递归分割 混合检索：向量检索 + BM25全文检索 + RRF融合 + 重排序 智能去重：文档级别自动去重，避免冗余
四、功能全景
核心表达：
从智能体创建、配置、对话、工具调用到外部集成形成闭环。 从文档上传、切片、向量化、检索、问答到智能体调用形成 RAG 闭环。 模型、资源、用户、技能、MCP、OpenAPI、数据库适配进入稳定可用阶段。 开源版文档、SQL、Docker、截图和源码保持一致，降低部署和二次开发成本。
版本演进概览
0.0.1 | ||
0.0.2 | ||
0.0.3 | ||
0.0.4 | ||
0.0.5 | ||
0.0.6 | ||
1.0.0 | ||
1.1.0 |
1.1.0 功能全景
新增功能
智能体对话支持图片附件链路，独立聊天页、OpenAPI 和 Agent SDK 可上传图片并随消息发送，支持图片消息预览、附件校验与会话记录元数据持久化。 模型配置新增能力标记，CHAT 模型可开启 vision支持图片输入，并可配置默认视觉模型用于图片识别和 RAG 图片 OCR 兜底。RAG 知识库新增 Docling 解析引擎，支持 PDF/文档版面元素解析、Markdown 内容留存、解析统计和解析引擎参数回显。 RAG 图片识别能力增强，支持 Docling 图片提取、PaddleOCR/多模态模型 OCR、图片 chunk 构建、图片证据召回与检索结果图片证据返回。 模型配置新增连通性验证，支持 Chat、Embedding、Reranker 三类模型测试，并完善模型用量统计持久化。 首页新增运营概览聚合接口，支持 KPI、趋势、排行、知识库、技能与资源数据汇总，Token 趋势改为按对话记录读时聚合。 OpenAPI 增加会话标题更新、资源上传、用户解析等能力，图片对话与资源返回结构同步扩展。 MCP 服务配置支持超时时间和请求头配置，便于对接需要自定义 Header 或较长响应时间的 MCP 服务。 新增 Docling API 与 PaddleOCR API 工具目录及 Docker 化部署支持，补充 .env.example、Docker Compose 与相关启动脚本。
功能优化
拆分 Agent、模型配置、RAG 文档、Skill 等管理端大服务类，补充 Assembler、Validator、QueryService、FileService 等职责边界，降低服务复杂度。 优化智能体对话链路，新增附件解析处理，调整模型视觉能力分发、Prompt 构建、RAG/Skill/MCP 工具解析和流式输出元数据。 优化 RAG 文档导入与检索流水线，支持图片 OCR 质量评估、图片与文本 chunk 匹配、检索结果重排和图片证据增强。 优化客户端实例管理和心跳调度，补充客户端踢出处理、路由策略可观测性和异常路径日志。 完善资源、向量存储、全文检索、OpenAPI、鉴权、异常处理、RAG 和 Agent 链路的观测性日志与公开 API 注释。 接入 EditorConfig、Spotless、commit-msg 钩子和 git-submit/frontend-dev/env-config 技能，统一代码格式、提交规范和开发流程说明。
问题修复
修复 Docling v2 API 兼容、图片 caption 前瞻提取、页码识别和 Media 构造方式等问题。 修复 RAG 文档管道资源引用、图片 OCR/图注/公式内容不可检索、知识库编辑时解析配置未保留等问题。 修复批量上传超时，增加上传预览耗时日志和 axios 超时配置。 修复首页模型用量统计为空、首页 Token 趋势统计口径不准确的问题。 修复 AdminWebController与 Agent ChatWebControllerBean 名称冲突。修复模型配置字段长度校验不足导致插入异常，以及删除模型/存储/MCP 时缺少引用检查的问题。 修复图片对话执行端依赖版本、模型视觉能力返回和图片附件校验链路中的兼容问题。
数据库变更
MySQL、PostgreSQL、达梦三套建表脚本同步更新： docs/sql/snail_ai_schema.sql、docs/sql/snail_ai_schema_pgsql.sql、docs/sql/snail_ai_schema_dameng.sql。sai_agent_conversation_record新增metadata字段，用于保存图片附件、工具结果等消息扩展元数据。sai_rag_document新增 Docling 解析统计与内容字段：page_count、element_count、table_count、image_count、parse_time、md_content、doc_metadata。新增 sai_rag_document_image表，保存 RAG 文档解析出的图片、资源关联、页码、图注、章节、OCR 文本和 chunk 关联，并增加 rag/document/chunk/resource 维度索引。sai_rag_chunk新增source_type字段和(rag_id, source_type)索引，用于区分TEXT文本 chunk 与IMAGE图片 chunk。sai_mcp_server移除旧的version、auth_type、auth_config、capabilities字段，新增timeout与headers字段，对应 MCP 超时和请求头配置。PostgreSQL 与达梦脚本补充 sai_rag_document_image.update_dt自动更新时间触发器。
SQL 变更记录
对话记录表： sai_agent_conversation_record增加metadata字段。RAG 文档表： sai_rag_document增加 Docling 解析统计、Markdown 内容和元数据字段。RAG 图片表：新增 sai_rag_document_image，并增加rag_id、document_id、chunk_id、resource_id索引。RAG 分块表： sai_rag_chunk增加source_type字段和(rag_id, source_type)索引。MCP 服务表： sai_mcp_server删除version、auth_type、auth_config、capabilities，新增timeout、headers。
MySQL 升级参考 DDL：
ALTERTABLE sai_agent_conversation_record
ADDCOLUMN metadata LONGTEXT DEFAULTNULLCOMMENT'消息扩展元数据JSON';
ALTERTABLE sai_rag_document
ADDCOLUMN page_count INTDEFAULT0COMMENT'Docling parse page count',
ADDCOLUMN element_count INTDEFAULT0COMMENT'Docling parse element count',
ADDCOLUMN table_count INTDEFAULT0COMMENT'Docling parse table count',
ADDCOLUMN image_count INTDEFAULT0COMMENT'Docling parse image count',
ADDCOLUMN parse_time INTDEFAULT0COMMENT'Parse duration in milliseconds',
ADDCOLUMN md_content LONGTEXT DEFAULTNULLCOMMENT'Docling markdown content',
ADDCOLUMN doc_metadata LONGTEXT DEFAULTNULLCOMMENT'Docling document metadata JSON';
CREATETABLE sai_rag_document_image
(
idBIGINTNOTNULL AUTO_INCREMENT PRIMARY KEY,
rag_id BIGINTNOTNULL,
document_id BIGINTNOTNULL,
chunk_id BIGINTDEFAULTNULL,
resource_id BIGINTDEFAULTNULL,
image_index INT,
image_url VARCHAR(1024),
caption TEXT,
figure_no VARCHAR(64),
figure_title VARCHAR(512),
section_title VARCHAR(512),
source_page INT,
document_name VARCHAR(255),
ocr_text TEXT,
create_dt TIMESTAMPDEFAULTCURRENT_TIMESTAMP,
update_dt TIMESTAMPDEFAULTCURRENT_TIMESTAMPONUPDATECURRENT_TIMESTAMP
) ENGINE = InnoDB
DEFAULTCHARSET = utf8mb4
COLLATE = utf8mb4_unicode_ci;
CREATEINDEX idx_rag_doc_image_rag ON sai_rag_document_image (rag_id);
CREATEINDEX idx_rag_doc_image_document ON sai_rag_document_image (document_id);
CREATEINDEX idx_rag_doc_image_chunk ON sai_rag_document_image (chunk_id);
CREATEINDEX idx_rag_doc_image_resource ON sai_rag_document_image (resource_id);
ALTERTABLE sai_rag_chunk
ADDCOLUMN source_type VARCHAR(20) NOTNULLDEFAULT'TEXT'COMMENT'chunk来源类型：TEXT文本、IMAGE图片';
CREATEINDEX idx_chunk_rag_source_type ON sai_rag_chunk (rag_id, source_type);
ALTERTABLE sai_mcp_server
DROPCOLUMNversion,
DROPCOLUMN auth_type,
DROPCOLUMN auth_config,
DROPCOLUMN capabilities,
ADDCOLUMNtimeoutBIGINTDEFAULT60000COMMENT'超时时间(毫秒)',
ADDCOLUMN headers TEXTCOMMENT'请求头(JSON对象)';
文档与部署
新增 Docling 解析引擎设计文档、RAG 图片识别与证据匹配说明、图片对话设计方案和 Docker 部署说明。 更新管理端、OpenAPI、模型配置、RAG、Skill、独立聊天页等使用文档，并补充图片对话、模型视觉能力和 RAG 图片证据截图。 Docker 部署增加 Docling 与 PaddleOCR 服务配置，完善环境变量模板和工具服务 README/API 文档。
升级说明
本版本涉及数据库结构变更，升级前请先备份数据库，并按实际数据库类型同步执行或合并新版 schema 中的字段、索引、触发器和新表变更。 已有 MCP 服务配置需要从旧的认证/能力字段迁移到 timeout、headers配置模型，历史auth_type/auth_config/capabilities字段不再保留。使用图片对话或 RAG 图片 OCR 前，需要在模型配置中为可处理图片的 CHAT 模型开启 vision能力，并按需配置默认视觉模型。使用 Docling/PaddleOCR 解析能力时，需要部署对应工具服务并配置 .env/Docker Compose 中的服务地址、超时和 OCR 参数。
[1.0.0] - 2026-06-28
版本亮点
发布首个 1.0 正式版本，围绕开源版可落地能力完成文档、部署、数据库和智能体对话链路整理。 新增独立「智能体对话」能力，提供 /snail-chat页面、会话 Token、嵌入配置和前后端源码说明。完善 RAG、智能体、技能、模型、智能体对话等核心页面的实际界面截图，提升文档可读性和上手体验。
新增功能
新增 VitePress 文档站点与文档打包脚本，文档源码、Docker、SQL、部署说明统一迁移到 docs/目录。新增文档维护智能体规范，明确开源版文档必须以当前源码、配置、SQL 和脚本为准。 新增达梦数据库支持，包含 snail-ai-dm-storage存储模块、Mapper 适配、依赖声明和docs/sql/snail_ai_schema_dameng.sql初始化脚本。新增 GitNexus 代码智能规范与相关 Skill 文档，用于代码影响分析、调试、重构和索引维护。 智能体对话新增独立前端 snail-ai-chat与后端snail-ai-agent-chat文档说明，前端构建产物可嵌入 Starter 静态资源目录。
功能优化
优化 Docker Compose 一键启动配置，统一依赖服务、初始化脚本和示例应用构建路径。 优化 MCP 服务连接测试， testConnection仅返回本次连接结果true/false，不再把连接状态作为持久状态维护。删除 MCP 连接状态相关枚举、VO 字段、持久化字段和查询条件，避免把瞬时连接结果展示为长期状态。 优化 Chat 与 OpenAPI 的启用开关，智能体对话 Starter 复用 OpenAPI 客户端能力自动装配。 优化向量存储缓存刷新逻辑，缓存判断同时考虑模型配置和向量库存储实例更新时间，修复向量库配置变更后缓存不刷新的问题。 优化 RAG 处理链路中文档、切片、检索、问答等页面说明，补充当前实际 UI 的使用路径。
文档与站点
新增并校验 Admin API、OpenAPI、部署、架构、RAG、智能体、模型、MCP、Skill、资源、用户、记忆等文档页面。 移除开源版未实现功能的完成态描述，包括独立 Admin Memory API、全局 Dashboard、Trace/Score/Langfuse 风格观测、独立 OpenAPI RAG 端点等。 修正认证说明：OpenAPI 外部集成使用 Snail-Ai-App-Id与Snail-Ai-Token；Snail-Ai-Auth仅用于 Admin API 或智能体对话会话。「客户端 Chat 模式」更名为「智能体对话」，并移动到智能体菜单下。 新增智能体对话、技能管理、智能体列表/配置、模型管理、RAG 列表/创建/文档/切片/检索/问答等截图。
问题修复
修复向量存储实例缓存不随配置更新时间失效的问题。 修复 MCP 工具解析中依赖连接状态导致状态不准确的问题。 修复 Docker Compose 和示例 Dockerfile 在一键启动场景下的路径与初始化问题。 修复文档中旧路径、旧端口、旧认证方式和未实现功能描述与当前开源源码不一致的问题。
升级说明
如果历史数据库中存在 MCP 连接状态字段，需要按新版 SQL 删除相关字段并以实时连接测试结果为准。 文档相关脚本和资源路径已从 script/迁移到docs/，部署与打包请使用docs/docker/、docs/sql/和docs/package-docs.sh。如需使用达梦数据库，请使用新增的达梦存储模块与 docs/sql/snail_ai_schema_dameng.sql初始化脚本。原文档路径 /guide/client/chat已调整为/guide/agent/conversation。
登录使用
访问 http://localhost:8900/snail-ai默认账号： admin/admin123创建你的第一个AI智能体 前端内置对话 http://localhost:8081/snail-chat
五、系统架构一览
六、支持的数据库和模型
数据库支持
关系型：MySQL、PostgreSQL、SQL Server、达梦(DM)、MariaDB 向量存储：PgVector、Milvus、Elasticsearch
大模型支持
OpenAI（GPT系列） Claude（Anthropic） Ollama（本地开源模型） Gemini（Google） 火山引擎（豆包等） 更多模型持续接入中...
支持五种模型类型：对话 / 嵌入 / 重排 / 图像 / 语音
七、谁在使用?
Snail AI特别适合：
✅ 企业内部AI助手/客服系统 ✅ 智能文档问答/知识管理系统 ✅ 代码助手/自动化工具 ✅ 业务流程自动化 ✅ 需要数据不出域的安全场景
八、开源协议
采用 Apache License 2.0 开源协议，可免费用于商业项目。
九、立即体验
Gitee仓库（后端）：https://gitee.com/aizuda/snail-ai Gitee仓库（前端）：https://gitee.com/opensnail/snail-ai-admin Gitee仓库（前端）：https://gitee.com/opensnail/snail-ai-chat 问题反馈：https://gitee.com/aizuda/snail-ai/issues
如果你是Java开发者，如果你的团队正在探索AI落地，如果你需要一个生产级、可扩展、安全可控的AI Agent平台，那么 Snail AI 值得你一试！
🌟 Give us a Star! 觉得不错的话，欢迎到Gitee给我们点个Star，你的支持是我们持续更新的动力！
#AI Agent #Spring AI #开源项目 #企业级AI #Java开发 #RAG #大模型
 |  |
 |  |
 |  |
 |  |
 |  |
 |  |
 |  |
