核心概念

本页介绍 Snail AI 平台中的核心概念和术语。理解这些概念将帮助你更好地使用和扩展平台功能。

智能体 (Agent)

智能体是 Snail AI 的核心实体，代表一个具备特定能力的 AI 助手。每个智能体拥有独立的配置，包括：

• 系统提示词 -- 定义智能体的角色、行为边界和回复风格
• 绑定模型 -- 指定使用的大语言模型（如 GPT-4、Claude 等）
• 关联能力 -- 可绑定知识库（RAG）、MCP 工具、技能包、记忆等模块

智能体支持通过管理后台可视化创建和配置，也支持 AI 辅助一键生成。创建完成后可发布到智能体市场供其他用户订阅使用。

责任链 (Chain of Responsibility)

Snail AI 的 Agent 执行采用责任链架构，服务端对每次用户请求按固定顺序经过 10 个处理器（Handler），每个处理器负责一个独立关注点：

Init → ModelResolve → SystemPrompt → Conversation → Mcp → Rag → Skill → WebSearch → ContextCollector → LlmCall

序号	Handler	职责
1	Init	初始化请求上下文，校验参数，加载智能体配置
2	ModelResolve	解析并校验绑定的模型配置，构建模型调用参数
3	SystemPrompt	组装系统提示词，支持变量模板替换
4	Conversation	加载历史对话记录，管理上下文窗口
5	Mcp	发现并注册已绑定的 MCP 工具定义
6	Rag	执行 RAG 检索，将匹配的知识片段注入上下文
7	Skill	加载已绑定的技能指令，扩展智能体能力
8	WebSearch	执行联网搜索，注入实时信息
9	ContextCollector	汇总所有上下文信息，构建最终的 Prompt
10	LlmCall	调用大模型 API，处理流式响应并返回结果

这种设计使得每个环节可独立扩展和替换，新增能力只需插入新的 Handler。

RAG (检索增强生成)

RAG（Retrieval-Augmented Generation）是让智能体基于私有知识进行回答的核心机制。Snail AI 的 RAG 流水线包含以下阶段：

文档处理流水线

文档上传 → 格式解析 → 文本分片 → 向量化 → 存入向量数据库

• 支持格式： PDF、Word、Excel、PPT、Markdown、TXT、HTML、CSV 等 10+ 种
• 分片策略： 固定长度、递归字符、Token 级别、语义分片 4 种策略
• 智能去重： 基于内容哈希的文档级去重

检索策略

策略	说明
向量检索	基于语义相似度的 Embedding 检索
BM25 检索	基于关键词的传统全文检索
融合检索	同时执行向量和 BM25，通过 RRF（Reciprocal Rank Fusion）或加权融合合并结果
重排序	使用 Reranker 模型对检索结果进行精排

MCP (Model Context Protocol)

MCP 是一种标准化的工具调用协议，允许智能体在对话过程中调用外部工具和服务。Snail AI 完整实现了 MCP 协议：

• 传输方式： SSE（Server-Sent Events）、Streamable HTTP、Stdio 三种传输协议
• 认证方式： API Key、Bearer Token、OAuth 2.0 多种认证机制
• 工具管理： 可视化配置工具 URL、认证信息，支持一键连接测试

智能体绑定 MCP 工具后，大模型可以在对话中自主决定何时调用工具、传递什么参数，并将工具返回的结果整合到回复中。

技能 (Skill)

技能是一种轻量级的能力扩展机制，通过上传 ZIP 包的方式为智能体添加特定领域的知识和行为指令。

每个技能包中包含一个 SKILL.md 文件，定义了技能的触发条件、指令内容和行为规范。技能在责任链的 Skill Handler 阶段被加载，其指令会被注入到系统提示词中。

与 MCP 工具侧重于外部 API 调用不同，技能更侧重于通过 Prompt 工程为智能体注入领域知识和行为模式。

记忆 (Memory)

记忆系统为智能体提供跨对话的信息持久化能力，分为两种机制：

类型	机制	说明
短期记忆	滑动窗口	维护当前对话的最近 N 轮上下文，超出窗口的历史自动截断
长期记忆	向量召回	将重要的对话片段向量化存储，在后续对话中通过语义检索召回相关记忆

长期记忆使智能体能够"记住"用户的偏好、历史问题和关键信息，提供更个性化的服务体验。

客户端 (Client)

客户端是 Snail AI 分布式架构中的 Agent 执行节点。在 Server-Agent 架构中：

• Server（服务端） -- 负责请求编排、责任链执行、RAG 检索、对话管理
• Client（客户端） -- 负责实际的大模型调用，通过 gRPC 双向流与 Server 通信

客户端的核心特性是拦截器链（Interceptor Chain），开发者可以在 AI 交互的各个阶段插入自定义逻辑：

用户请求 → [前置拦截器] → 模型调用 → [后置拦截器] → 返回响应

典型应用场景包括：请求参数修改、敏感信息过滤、响应内容审查、日志记录、Token 用量统计等。

应用 (App)

应用是分布式执行环境的逻辑单元，用于管理智能体与客户端节点之间的关系和路由策略。

一个应用可以关联多个客户端节点，通过配置不同的路由策略来实现负载均衡和故障转移：

路由策略	说明
随机路由	随机选择一个可用的客户端节点
轮询路由	按顺序依次分配到各节点
指定节点	将请求固定路由到特定客户端

存储实例 (Store Instance)

存储实例是向量数据库和搜索引擎的后端连接配置。RAG 知识库通过绑定存储实例来确定数据的物理存储位置。

目前支持的存储后端：

后端	说明
PgVector	PostgreSQL 的向量扩展，推荐与 PG 关系数据库共用实例
Milvus	专业的分布式向量数据库，适合大规模向量检索场景
Elasticsearch	支持向量检索 + 全文检索，适合混合检索场景

追踪 (Trace)

追踪系统提供 Langfuse 风格的全链路可观测性，将每次 Agent 交互的完整执行过程记录为一棵 Observation 树：

Trace (一次完整交互)
├── Span: 责任链执行
│   ├── Span: RAG 检索 (耗时、召回数量)
│   ├── Span: MCP 工具调用 (工具名、参数、返回值)
│   └── Span: 上下文组装
├── Generation: LLM 调用 (模型、Token 用量、耗时)
└── Score: 用户评分 / 自动评估

追踪系统的核心能力：

• 瀑布图可视化 -- 直观展示各阶段的执行顺序和耗时分布
• Token 用量统计 -- 记录每次调用的输入/输出 Token 数量和费用
• 评分系统 -- 支持用户手动评分和自动化评估，用于持续优化智能体表现
• 客户端集成 -- 通过 Micrometer 深度集成，客户端侧的执行指标同样纳入追踪

追踪数据对于调试 Agent 行为、优化 RAG 检索效果、分析 Token 消耗具有重要价值。