spring-ai-alibaba / website

spring-ai-alibaba/website

open_in_new前往仓库

Spring AI Alibaba 官方网站的源代码。📚

项目概览

项目概述

该仓库是 Spring AI Alibaba 官方文档网站的源代码，基于 Docusaurus 构建，提供中英文双语文档。仓库内容主要涵盖 Spring AI Alibaba 框架的 Agent 框架、Graph 核心、RAG、多智能体协作、人工介入、记忆管理、沙箱运行时等高级主题，以及模型、消息、工具、结构化输出等基础教程。

核心功能

  • Agent 框架：提供 ReactAgent 实现，支持 ReAct 范式、工具调用、多智能体协作（顺序、并行、路由、监督者模式）、人工介入（HITL）、上下文工程、记忆管理等。
  • Graph 核心：提供底层工作流编排引擎，支持状态管理、节点/边定义、条件分支、并行执行、检查点持久化、时间旅行等。
  • RAG 支持：涵盖两步 RAG、Agentic RAG、混合 RAG 的架构与实现，以及知识库构建、文档加载、向量存储等组件。
  • 沙箱运行时：提供隔离的代码执行和浏览器自动化环境，支持 Python、Shell 和浏览器操作。
  • 技能系统：支持技能的渐进式披露，通过 SkillRegistry 和 SkillsAgentHook 实现按需加载。
  • 文档站点：基于 Docusaurus 构建，支持中英文切换，提供 Markdown 文档和代码示例。

适用与不适用场景

适用场景：

  • 需要构建生产级 AI Agent 应用的开发者，尤其是使用 Java/Spring 技术栈。
  • 需要实现复杂多智能体协作、人工审批、长期记忆等高级功能的场景。
  • 需要将 RAG 与 Agent 结合，构建知识库问答或研究助手。
  • 需要隔离执行 Python/Shell/浏览器操作的场景。
  • 需要学习 Spring AI Alibaba 框架的开发者。

不适用场景：

  • 非 Java 技术栈的开发者（框架基于 Java/Spring）。
  • 简单的单轮对话应用，无需 Agent 或工作流编排。
  • 需要图形化低代码编排的场景（虽然支持 Dify DSL 导出，但主要面向代码开发）。
  • 对实时性要求极高且不能容忍 LLM 调用延迟的场景。

技术架构与依赖

  • 基础框架：Spring AI Alibaba，基于 Spring AI 构建。
  • 文档站点：Docusaurus（React 静态站点生成器）。
  • 核心组件：
    • spring-ai-alibaba-agent-framework：Agent 框架，提供 ReactAgent、多智能体、Hook/Interceptor 等。
    • spring-ai-alibaba-graph-core：Graph 引擎，提供 StateGraph、节点/边、检查点等。
    • spring-ai-alibaba-sandbox-tool：沙箱工具，提供代码执行和浏览器自动化。
    • spring-ai-alibaba-starter-dashscope：DashScope 模型适配。
  • 外部依赖：Nacos（服务注册与发现）、Docker（沙箱容器）、Redis/PostgreSQL/MongoDB（检查点持久化）、向量数据库（Milvus、Pinecone、Redis、Elasticsearch 等）。
  • 构建工具：Make、npm。

安装与快速开始

仓库资料未提供具体的安装步骤，但根据 README 和文档，可以推断：

  1. 确保本地安装 npm。
  2. 克隆仓库后，运行 make install && make preview 启动中文文档站点。
  3. 运行 make preview-en 启动英文文档站点。
  4. 运行 make build && make serve 构建并服务站点。
  5. 提交前运行 make npm-lint && make markdown 确保 CI 通过。

典型使用方法

仓库主要作为文档网站，典型使用是浏览文档学习框架。但文档中提供了大量代码示例，例如：

  • 创建 ReactAgent：ReactAgent.builder().name("agent").model(chatModel).tools(tool).build()。
  • 构建工作流：使用 StateGraph 添加节点和边，编译后执行。
  • 实现 RAG：通过 Hook 或 Interceptor 在模型调用前检索文档。
  • 多智能体协作：使用 SequentialAgent、ParallelAgent、LlmRoutingAgent、SupervisorAgent。
  • 人工介入：配置 HumanInTheLoopHook 和检查点，实现工具调用审批。
  • 沙箱执行：通过 BaseSandbox 和 BrowserSandbox 提供工具。

配置与部署要点

  • 模型配置：需要设置 DashScope API Key（环境变量 AI_DASHSCOPE_API_KEY）。
  • Nacos 配置：A2A 场景需要配置 Nacos 地址、用户名、密码，并启用 registry/discovery。
  • 沙箱配置：需要配置 Docker socket 地址（sandbox.docker.host）和容器池大小。
  • 检查点持久化：生产环境建议使用 Redis、PostgreSQL 或 MongoDB 作为检查点存储。
  • 文档站点部署：使用 make build 生成静态文件，可部署到任意静态托管服务。

限制、风险与许可证

  • 许可证：Apache-2.0。
  • 限制：
    • 框架主要面向 Java/Spring 技术栈。
    • 沙箱依赖 Docker，需要 Docker 环境。
    • 部分功能（如 A2A）依赖 Nacos 3 及以上版本。
    • 结构化输出对部分模型依赖提示词增强，不保证严格格式。
  • 风险：
    • 沙箱执行代码存在安全风险，需确保容器隔离和资源限制。
    • 人工介入机制需要合理配置检查点，否则可能丢失状态。
    • 多智能体协作可能增加 LLM 调用成本，需合理设计。

官方链接

信息来源和分析时间

  • 信息来源：GitHub 仓库 README 和文档内容。
  • 分析时间：2025年4月。