核心概念

了解 Sira AI 的核心概念，帮助您更好地使用平台。

三层架构

Sira AI 采用创新的三层架构设计，实现了从用户接入到 AI 处理的完整链路：

Application (应用层) → Orchestrator (编排层) → Agent (智能体层)

Application（应用层）

Application 是用户与系统交互的入口，负责不同平台的适配和消息处理。

支持的平台：

企业微信 AI Bot：流式响应，打字机效果
企业微信传统应用：传统回调模式
Web 聊天客户端：独立的 Web 界面
OpenAI 兼容 API：标准化的 API 接口

核心功能：

平台消息格式转换
多模态内容处理（图片链接检测）
流式响应管理
会话管理

Orchestrator（编排层）

Orchestrator 是系统的核心，负责智能体的编排和协调。

8 种编排模式：

Single（单体）：单个 Agent 直接处理。当 Agent 配置了 Skill 包时，引擎会透明地路由到 DeepAgents 执行器，从而获得文件系统 / 沙箱 / Skill 脚本能力
Supervisor（监督者）：Supervisor 动态调度 Worker Agents
Collaboration（协作）：多个专家 Agent 平等协作（顺序 / 并行）
Workflow（工作流）：预定义的固定流程
Conditional（条件路由）：基于规则的智能分发
External（外部集成）：Dify / n8n 应用集成
DeepAgents 🆕：脚本驱动的多步骤 Agent，原生支持 Backend（filesystem / local_shell / sandpod 沙箱）和 Skill 包
KnowledgeBase 🆕：RAG 直答模式，基于 LightRAG（向量 + 图谱）+ 多种解析器（auto / mineru 等）做知识库检索

编排引擎：

基于 LangGraph 的状态管理
Redis Checkpointer 持久化
流式执行支持
错误处理和重试

Agent（智能体层）

Agent 是具备特定能力的 AI 智能体，可以独立完成任务。

Agent 组成：

LLM 模型：GPT-4、Claude、DeepSeek、Qwen 等
系统提示词：定义 Agent 的角色和能力
MCP 工具：外部工具调用能力
知识库：RAG 检索增强

Agent 特性：

独立的身份和能力
可复用的配置
支持多种模型类型（LLM、VISION、EMBEDDING、RERANK）
跨会话记忆管理

核心实体详解

1. Agent（智能体）

定义：具备特定能力的 AI 智能体，是系统的最小执行单元。

属性：

json

{
  "id": "agent-uuid",
  "name": "tech_expert",
  "display_name": "IT技术专家",
  "description": "专业的IT技术专家，擅长...",
  "system_prompt": "你是一个专业的IT专家...",
  "model_id": "model-uuid",
  "model_types": ["LLM", "VISION"],
  "mcp_tools": ["context7", "web_search"],
  "knowledge_bases": ["tech_docs"],
  "is_active": true
}

Agent 类型：

通用 Agent：处理一般性任务
专家 Agent：特定领域的专家（技术、法律、医疗等）
工具 Agent：专门使用工具的 Agent
路由 Agent：Supervisor 模式中的调度者

2. Orchestrator（编排器）

定义：定义多个 Agent 如何协同工作的编排配置。

属性：

json

{
  "id": "orch-uuid",
  "name": "customer_service",
  "orchestration_type": "SUPERVISOR",
  "supervisor_config": {
    "supervisor_agent_id": "supervisor-uuid",
    "worker_agent_ids": ["worker1-uuid", "worker2-uuid"],
    "enable_summarization": true
  }
}

编排配置：

Single：{"agent_id": "..."}
Supervisor：{"supervisor_agent_id": "...", "worker_agent_ids": [...]}
Collaboration：{"agent_ids": [...], "collaboration_strategy": "sequential"}
Conditional：{"routes": [...], "default_agent_id": "..."}
External：{"integration_type": "dify", "api_url": "...", "api_key": "..."}

3. Application（应用）

定义：面向最终用户的应用入口，连接到一个 Orchestrator。

属性：

json

{
  "id": "app-uuid",
  "display_name": "智能客服",
  "platform": "webclient",
  "orchestrator_id": "orch-uuid",
  "platform_config": {
    "token": "access_token_xxx"
  },
  "is_active": true
}

平台类型：

wework_aibot：企业微信 AI Bot
wework_traditional：企业微信传统应用
webclient：Web 聊天客户端
api_service：OpenAI 兼容 API

4. AI Model（AI 模型）

定义：LLM 模型的配置和管理。

属性：

json

{
  "id": "model-uuid",
  "provider": "openai",
  "model_name": "gpt-4o",
  "model_types": ["LLM", "VISION"],
  "api_key": "sk-xxx",
  "base_url": "https://api.openai.com/v1",
  "parameters": {
    "temperature": 0.7,
    "max_tokens": 2000
  }
}

支持的提供商：

OpenAI (GPT-4, GPT-3.5)
Anthropic (Claude 3)
DeepSeek (deepseek-chat)
阿里云通义 (qwen-turbo, qwen-vl-plus)
自定义兼容 OpenAI API 的模型

模型类型（4 种，与 app/services/llm/ 一致）：

LLM：标准语言模型
VISION：支持图片分析
EMBEDDING：向量化（用于知识库索引）
RERANK：检索结果重排（提升 RAG 准确率）

5. MCP Tool（MCP 工具）

定义：遵循 Model Context Protocol 的外部工具。

属性：

json

{
  "id": "tool-uuid",
  "name": "context7",
  "display_name": "Context7 文档查询",
  "tool_type": "mcp",
  "source_config": {
    "transport": "streamable_http",
    "url": "https://mcp.context7.com/mcp"
  }
}

工具类型：

预置工具：Context7、Weather、WebSearch
自定义工具：企业内部系统集成
第三方工具：社区提供的工具

6. Knowledge Base（知识库）

定义：用于 RAG 检索增强的文档库。

功能：

文档上传和解析
向量化存储
语义检索
上下文注入

数据流转

单次对话流程

1. 用户发送消息 "帮我查询天气"
   ↓
2. Application 接收并验证
   - 平台: webclient
   - Session ID: web_xxx_12345
   ↓
3. 路由到 Orchestrator
   - Type: SINGLE
   - Agent: weather_assistant
   ↓
4. Agent 执行
   - 理解意图: 查询天气
   - 调用 MCP 工具: weather_tool.get_weather("北京")
   - 生成回复: "北京今天晴，温度25°C"
   ↓
5. 流式返回
   - Redis Stream 逐字推送
   - SSE 实时显示
   ↓
6. 用户看到打字机效果

多智能体协作流程（Collaboration）

1. 用户: "分析这张架构图 [图片URL]"
   ↓
2. Web客户端检测图片链接
   - 提取 image_url
   - 构建 multimodal_content
   ↓
3. Orchestrator (Collaboration Sequential)
   - State 包含 multimodal_content
   ↓
4. Agent 1 (Vision专家)
   - 接收 multimodal_content
   - 使用 GPT-4V 分析图片
   - 输出: "这是 Kubernetes 架构图..."
   ↓
5. Agent 2 (技术专家)
   - 接收 multimodal_content
   - 看到 Agent 1 的分析
   - 使用 Context7 查询 K8s 文档
   - 输出: "基于最新文档，这个架构..."
   ↓
6. Summarize
   - 汇总两个专家的观点
   - 返回完整分析

状态管理

LangGraph Checkpointer

Sira AI 使用 LangGraph 的 Checkpointer 机制管理会话状态：

存储位置：

开发环境：SQLite
生产环境：PostgreSQL / Redis

持久化内容：

会话历史消息
Agent 执行状态
工具调用记录
中间结果

TTL 管理：

默认 24 小时
可配置自动清理
支持手动清除

Redis Session Store

用于临时流式数据：

Stream Key 格式：

agent_system:stream:{session_id}

数据结构：

json

{
  "type": "content",
  "data": {
    "content": "这是一段回复..."
  }
}

消息类型：

content：文本内容
handoff：Supervisor 委派
done：执行完成
error：错误信息

多模态处理

图片处理流程

用户消息: "分析图片 http://example.com/image.jpg"
         ↓
Image Detection (image_detection.py)
         ├─ 正则匹配图片URL
         ├─ 提取: ["http://example.com/image.jpg"]
         └─ 清理文本: "分析图片"
         ↓
multimodal_content 构建
         {
           "text": "分析图片",
           "image_urls": ["http://example.com/image.jpg"],
           "images": ["http://example.com/image.jpg"]
         }
         ↓
传递给 Agent (context)
         ↓
build_multimodal_message()
         ├─ 检查模型是否支持 VISION
         ├─ 构建 HumanMessage.content = [
         │    {"type": "text", "text": "分析图片"},
         │    {"type": "image_url", "image_url": {"url": "..."}}
         │  ]
         └─ 发送给 LLM

支持的图片格式：

HTTP/HTTPS URL
data:image/jpeg;base64,... (base64)
企业微信加密图片（自动下载解密）

模型要求：

Agent 的 model_types 必须包含 VISION
LLM 必须支持 vision 能力

错误处理

用户友好错误

系统会自动转换技术错误为用户友好的提示：

转换前：

Error code: 400 - {'error': {'code': 'invalid_parameter_error'...

转换后：

❌ 无法处理图片链接

检测到 1 张图片，但AI模型无法访问这些图片链接。

可能的原因：
• 图片链接需要登录或认证才能访问
• 图片链接已失效或不存在

建议：
• 使用公开可访问的图片链接
• 确认图片链接在浏览器中可以直接打开

错误类型：

图片URL无法访问
API限流
API配额不足
认证失败
请求超时
模型不可用
内容安全过滤

权限与安全

多租户隔离

数据隔离：不同企业数据完全隔离
配置隔离：Agent/Orchestrator/Application 独立配置
会话隔离：用户会话严格隔离

访问控制

系统级：平台管理员
企业级：企业管理员
应用级：应用配置权限
用户级：普通使用权限

数据加密

传输加密：HTTPS/WSS
存储加密：敏感信息加密存储
API密钥：安全存储，不可查看原文

性能优化

缓存策略

模型缓存：LLM Client 复用
工具缓存：MCP Client 连接池
配置缓存：Agent/Orchestrator 配置缓存

并发控制

连接池：数据库连接池
限流：API 速率限制
负载均衡：支持多实例部署

资源管理

内存管理：Session 自动清理
存储管理：Redis Stream 自动过期
日志管理：日志轮转和归档

最佳实践

Agent 设计

单一职责：一个 Agent 专注一个领域
清晰提示词：明确定义角色和能力
合理工具配置：只启用必要的工具
模型选择：根据任务选择合适的模型

Orchestrator 选择

场景	推荐模式	理由
简单问答	Single	快速响应，成本低
复杂任务	Supervisor	动态分解，灵活调度
多角度分析	Collaboration	专家协作，全面覆盖
标准流程	Workflow	流程固定，可控性强
意图识别	Conditional	快速分类，精准路由
复用已有	External	无需重构，快速集成

多模态使用

模型选择：使用支持 VISION 的模型
图片格式：优先使用 HTTPS 公开链接
提示优化：文本描述 + 图片分析结合
成本控制：Vision 模型通常更贵

下一步

快速上手 - 开始使用 Sira AI
Agent System - 深入了解智能体系统
编排模式 - 掌握编排模式
多模态支持 - 使用图片分析功能

核心概念 ​

三层架构 ​

Application（应用层） ​

Orchestrator（编排层） ​

Agent（智能体层） ​

核心实体详解 ​

1. Agent（智能体） ​

2. Orchestrator（编排器） ​

3. Application（应用） ​

4. AI Model（AI 模型） ​

5. MCP Tool（MCP 工具） ​

6. Knowledge Base（知识库） ​

数据流转 ​

单次对话流程 ​

多智能体协作流程（Collaboration） ​

状态管理 ​

LangGraph Checkpointer ​

Redis Session Store ​

多模态处理 ​

图片处理流程 ​

错误处理 ​

用户友好错误 ​

权限与安全 ​

多租户隔离 ​

访问控制 ​

数据加密 ​

性能优化 ​

缓存策略 ​

并发控制 ​

资源管理 ​

最佳实践 ​

Agent 设计 ​

Orchestrator 选择 ​

多模态使用 ​

下一步 ​

核心概念

三层架构

Application（应用层）

Orchestrator（编排层）

Agent（智能体层）

核心实体详解

1. Agent（智能体）

2. Orchestrator（编排器）

3. Application（应用）

4. AI Model（AI 模型）

5. MCP Tool（MCP 工具）

6. Knowledge Base（知识库）

数据流转

单次对话流程

多智能体协作流程（Collaboration）

状态管理

LangGraph Checkpointer

Redis Session Store

多模态处理

图片处理流程

错误处理

用户友好错误

权限与安全

多租户隔离

访问控制

数据加密

性能优化

缓存策略

并发控制

资源管理

最佳实践

Agent 设计

Orchestrator 选择

多模态使用

下一步