Snail AI

Appearance

常见问题 ​

本页整理了 Snail AI 使用过程中的常见问题和解答，按类别分组。如果这里没有你要找的答案，请参阅 故障排除 或在 Gitee Issues 中搜索和提问。

安装与环境 ​

Q：Snail AI 需要什么版本的 Java？ ​

Snail AI 要求 Java 17 或更高版本。推荐使用 OpenJDK 17 或 GraalVM。

检查当前版本：

bash
java -version

如果版本低于 17，请参考 快速开始 中的环境准备部分安装正确版本。

Q：支持哪些操作系统？ ​

Snail AI 后端是标准的 Spring Boot 应用，支持所有能运行 Java 17+ 的操作系统：

  • Linux（推荐生产部署）：CentOS 7+、Ubuntu 18.04+、Debian 10+、统信 UOS、麒麟 OS
  • macOS：12+（Intel 和 Apple Silicon 均支持）
  • Windows：Windows 10/11、Windows Server 2019+

Q：如何选择关系型数据库？ ​

场景推荐数据库
初次体验、互联网团队MySQL
希望关系数据库和向量数据库合一PostgreSQL + PgVector
已有 SQL Server 基础设施SQL Server
政企信创项目达梦 (DM)
追求更开放的 MySQL 替代MariaDB

详细对比请参阅 生产环境部署 -- 多数据库选型指南。

Q：如何选择向量数据库？ ​

数据规模推荐方案
文档 < 10 万篇PgVector（轻量、运维简单）
文档 10 万 - 1000 万篇Milvus（专业向量数据库）
需要混合全文 + 向量检索Elasticsearch

详细对比请参阅 生产环境部署 -- 向量数据库容量规划。

Q：是否可以不部署向量数据库？ ​

可以。如果你不使用 RAG 知识库和长期记忆功能，可以不配置向量数据库。但以下功能将不可用：

  • RAG 知识库文档检索
  • 长期记忆的向量召回
  • 基于文档的问答

Q：最低硬件配置是什么？ ​

最低体验配置：2 核 CPU、4 GB 内存、20 GB 磁盘。此配置仅适合个人体验和测试，不建议用于生产环境。

生产环境推荐配置请参阅 生产环境部署 -- 硬件资源推荐。

智能体 (Agent) ​

Q：一个平台可以创建多少个智能体？ ​

目前没有数量限制。你可以根据业务需求创建任意数量的智能体。未来多租户版本可能引入租户级配额限制。

Q：智能体支持哪些大模型？ ​

Snail AI 通过模型提供商抽象层支持多种大模型：

提供商典型模型
OpenAIGPT-4o、GPT-4o-mini、GPT-3.5 Turbo
ClaudeClaude 3.5 Sonnet、Claude 3 Opus
OllamaLlama 3、Qwen2、Mistral 等本地模型
GeminiGemini Pro、Gemini Ultra
火山引擎豆包等字节跳动模型
OpenAI 兼容接口任何兼容 OpenAI API 的第三方服务

Q：一个智能体可以同时绑定多少个 MCP 工具？ ​

一个智能体可以绑定多个 MCP 工具服务器。实际可用的工具数量取决于模型的上下文窗口大小，因为每个工具的定义（名称、描述、参数）会占用上下文空间。

建议单个智能体绑定的工具数量不超过 20 个，以避免过多工具定义导致上下文溢出或模型选择困难。

Q：如何让智能体使用特定的知识进行回答？ ​

通过绑定 RAG 知识库：

  1. 创建知识库，上传相关文档
  2. 等待文档解析和向量化完成
  3. 在智能体配置中绑定该知识库
  4. 对话时智能体会自动检索相关知识片段辅助回答

详见 RAG 知识库。

Q：AI 辅助创建和手动创建有什么区别？ ​

方式适用场景特点
AI 辅助创建不确定如何编写系统提示词用自然语言描述需求，AI 自动生成全部配置
手动创建对配置有明确想法直接填写表单，完全自定义
模板创建标准场景快速上手基于预置模板一键创建

三种方式创建的智能体功能完全一致，只是配置填写过程不同。创建后均可在详情页进一步修改。

RAG 知识库 ​

Q：支持哪些文档格式？ ​

支持 10+ 种格式：

格式扩展名
PDF.pdf
Word.doc, .docx
Excel.xls, .xlsx
PowerPoint.ppt, .pptx
Markdown.md
纯文本.txt
HTML.html, .htm
CSV.csv
JSON.json
XML.xml

Q：单个文件最大支持多大？ ​

默认上传限制为 100 MB。可以通过配置调整：

yaml
spring:
  servlet:
    multipart:
      max-file-size: 200MB
      max-request-size: 200MB

注意

虽然可以上传大文件，但超大文件的解析和向量化会消耗较多时间和内存。建议将大型文档拆分为合理大小后上传。

Q：有哪些分片策略？如何选择？ ​

策略适用场景说明
固定长度通用场景按固定字符数切分，简单高效
递归字符结构化文档按段落、句子等自然边界递归切分
Token 级别精确控制 Token 消耗按 Token 数切分，与模型对齐
语义分片高质量需求基于语义相似度切分，保持语义完整性

选择建议：

  • 大多数场景使用 递归字符 即可获得不错的效果
  • 对检索质量要求高的场景可尝试 语义分片
  • 需要精确控制 Token 消耗时使用 Token 级别

Q：检索结果不准确怎么办？ ​

优化建议（按优先级排列）：

  1. 启用混合检索：同时使用向量检索 + BM25 关键词检索，通过 RRF 融合提升召回
  2. 启用 Reranker 重排序：配置重排序模型对检索结果精排
  3. 调整分片策略：尝试不同的分片大小和策略
  4. 使用更好的 Embedding 模型：如从 text-embedding-3-small 升级到 text-embedding-3-large
  5. 增大 Top-K 值：返回更多候选结果供模型参考
  6. 优化文档质量：清理文档中的噪声内容、统一格式

Q：文档更新后需要重新嵌入吗？ ​

是的。如果文档内容发生变化，需要删除旧文档并重新上传新版本。系统会基于内容哈希进行文档级去重，避免重复嵌入相同内容。

客户端 (Client) ​

Q：拦截器的执行顺序是什么？ ​

拦截器按 order 值升序执行：

  • order 值越小，优先级越高，越先执行
  • beforeRequest 按 order 升序执行
  • afterResponse 按 order 降序执行（类似 Spring MVC 拦截器的洋葱模型）
Request → [order=1] → [order=2] → [order=3] → LLM Call
                                                   ↓
Response ← [order=1] ← [order=2] ← [order=3] ← LLM Response

Q：一个应用可以部署多少个 Client 节点？ ​

没有硬性限制。你可以根据负载需求部署任意数量的 Client 节点。所有节点使用相同的 app-id 和 token 加入同一个应用，Server 会根据路由策略将请求分发到各节点。

建议至少部署 2 个节点 以实现高可用。

Q：Client 与 Server 断开连接后会怎样？ ​

Client 内置了自动重连机制：

  1. 连接断开后，Client 会按配置的间隔（默认 5 秒）自动重连
  2. 重连期间，Server 不会将新请求路由到该节点
  3. 重连成功后，节点自动恢复为可用状态
  4. 其他在线节点不受影响，继续正常处理请求

Q：是否可以不使用客户端模式？ ​

可以。客户端模式是可选功能。如果不需要分布式执行和拦截器定制能力，Snail AI Server 本身也可以直接调用大模型完成对话。

客户端模式的核心价值在于：

  • 数据安全（敏感数据不经过中心服务器）
  • 自主可控（代码级深度定制 AI 交互流程）
  • 弹性扩展（多节点水平扩展）

如果你的场景不需要这些能力，使用默认的 Server 模式即可。

Q：Client 的日志如何查看？ ​

两种方式：

  1. 管理后台在线查看：在应用详情 -> 客户端节点页面，点击节点可查看实时日志
  2. 本地日志文件：Client 节点的本地日志文件（默认位于 logs/ 目录）

详见 在线日志与追踪。

部署运维 ​

Q：Docker 部署和裸机部署哪个好？ ​

对比项Docker 部署裸机部署
部署速度快（一键启动）需要逐个安装组件
环境隔离好（容器隔离）需要手动管理环境
运维复杂度低中-高
性能开销略有损耗（通常 < 5%）无额外开销
适用场景快速体验、中小规模生产大规模生产、对性能敏感

建议：

  • 初次体验和中小规模部署使用 Docker
  • 大规模生产环境或对性能有严格要求时考虑裸机部署

Q：如何配置反向代理？ ​

Snail AI 前端是标准的 SPA 应用，后端提供 REST API 和 SSE 流式接口。配置 Nginx 反向代理时需注意：

  1. 前端路由使用 try_files 支持 History 模式
  2. API 代理需关闭 proxy_buffering 以支持 SSE 流式输出
  3. 适当增大 proxy_read_timeout 以适应长时间的模型调用

完整配置示例请参阅 生产环境部署 -- Nginx 反向代理配置。

Q：如何扩展以支持更多用户？ ​

水平扩展策略：

组件扩展方式
Server部署多个 Server 实例，前面加 Nginx 负载均衡
Agent Client增加 Client 节点数量，使用轮询路由策略
数据库主从复制 / 读写分离
向量数据库PgVector 扩容或迁移到 Milvus 集群
文件存储从本地存储迁移到 MinIO 集群

Q：如何备份数据？ ​

需要备份以下内容：

  1. 关系型数据库：定期 mysqldump 或 pg_dump
  2. 向量数据库：PgVector 随 PG 一起备份；Milvus 使用 Milvus Backup
  3. 文件存储：本地存储备份目录；MinIO 配置桶复制
  4. 配置文件：备份 application.yml 和加密密钥

建议使用 cron 定时任务设置自动备份，详见 升级指南 -- 数据备份。

Q：数据库和向量存储的数据可以迁移到另一种类型吗？ ​

关系型数据库之间的迁移需要使用数据迁移工具（如 DBeaver、Navicat 的数据迁移功能），并注意不同数据库的 SQL 方言差异。

向量数据库之间的迁移（如从 PgVector 迁移到 Milvus）目前需要重新嵌入文档。建议在项目初期选定好向量存储方案，避免后期迁移成本。

模型与费用 ​

Q：使用 Snail AI 需要付费吗？ ​

Snail AI 本身是开源免费的（Apache 2.0 协议），可以免费用于商业项目。

但使用大模型 API 会产生费用，这取决于你选择的模型提供商：

  • 商业模型（OpenAI、Claude 等）：按 Token 用量计费
  • 本地模型（通过 Ollama 部署）：完全免费，但需要本地 GPU 资源

Q：如何控制 Token 消耗？ ​

  1. 合理配置上下文窗口：减少短期记忆的滑动窗口大小
  2. 精简系统提示词：避免过长的 System Prompt
  3. 控制 RAG 注入量：减少 Top-K 值，减少注入的知识片段数量
  4. 选择性价比高的模型：如使用 GPT-4o-mini 代替 GPT-4o 处理简单任务
  5. 利用可观测性：在追踪面板中分析各阶段的 Token 消耗，针对性优化

Q：可以同时使用多个模型提供商吗？ ​

可以。Snail AI 支持同时配置多个模型提供商和多个模型配置。不同的智能体可以绑定不同的模型，甚至可以为 CHAT、EMBEDDING、RERANKER 分别选用不同提供商的模型。

其他 ​

Q：Snail AI 与 Dify、FastGPT 有什么区别？ ​

核心差异在于技术栈、架构模式和可控程度：

特性Snail AIDifyFastGPT
技术栈Java + Spring BootPython + FlaskNode.js + Next.js
架构分布式 Server-Agent单体单体
数据库MySQL/PG/达梦等 5 种仅 PostgreSQL仅 MongoDB
客户端可控拦截器 + Advisor 深度可控无无
信创适配原生支持达梦等国产数据库不支持不支持

详细对比请参阅 首页对比表。

Q：是否支持私有化部署？ ​

完全支持。Snail AI 是开源项目，所有代码和组件均可在企业私有网络中部署运行，无需连接任何外部服务（除了你选择的大模型 API）。

如果使用 Ollama 等本地模型，可以实现完全离线的私有化部署。

Q：如何获取技术支持？ ​

  1. 文档：查阅本文档站点的各章节
  2. Issue：在 Gitee Issues 中搜索或提问
  3. 社区：参与社区讨论和交流
  4. 贡献：参与开源贡献，详见 参与贡献

没有找到答案？

如果以上内容没有解决你的问题，请：

  1. 查阅 故障排除 文档
  2. 搜索 Gitee Issues
  3. 提交新的 Issue，附上详细的问题描述和环境信息

Apache 2.0 Licensed

Copyright © 2024-present OpenSnail