使用说明

项目简介

WildFly AI Feature Pack 是一个为 WildFly 应用服务器设计的扩展，旨在简化人工智能 (AI) 与 Jakarta EE 应用的集成。该 Feature Pack 提供了在 WildFly 中部署和管理 AI 模型、工具和 Prompt 的能力，并实验性地支持将 Jakarta EE 应用暴露为 Model Context Protocol (MCP) 服务器。通过 MCP 服务器，可以以标准化的方式向 LLM 客户端提供上下文信息和功能，从而构建强大的 AI 应用后端。

主要功能点

AI 模型支持: 支持多种聊天模型 (如 GitHub, Groq, Mistral AI, Ollama, OpenAI) 和 Embedding 模型，方便集成不同的 LLM 提供商。
内容检索 (RAG): 提供内容检索器 (Content Retriever) 用于支持 RAG (Retrieval-Augmented Generation) 应用，包括默认的内存存储、Neo4j 和 Web Search Engine 等多种数据源。
MCP 服务器: 实验性支持将 Jakarta EE 应用发布为 MCP 服务器，允许通过 Server-Sent Events (SSE) 或 Stdio 协议与 MCP 客户端通信。
工具支持 (MCP): 支持注册和使用 Tool Provider，允许 LLM 客户端调用 Jakarta EE 应用提供的外部功能。
灵活部署: 基于 WildFly Galleon Feature Pack，可以灵活选择和组合所需的功能层进行部署。
LangChain4J 和 SmallRye LLM 集成: 底层基于 LangChain4J 和 SmallRye LLM，利用成熟的 AI 工具库。

安装步骤

WildFly AI Feature Pack 需要与 WildFly Galleon Feature Pack 一起部署。安装可以通过 Galleon CLI 工具或 WildFly Maven Plugin/JAR Maven plugin 进行。

1. 使用 Galleon CLI 工具安装

a. 下载 Galleon CLI 工具：从 Galleon releases 下载最新版本。 b. 创建 Galleon provisioning 配置文件 (例如 'provisioning.xml')，内容如下 (以 Ollama 聊天模型和默认内容检索器为例):

<?xml version="1.0" ?>
<installation xmlns="urn:jboss:galleon:provisioning:3.0">
  <feature-pack location="org.wildfly:wildfly-galleon-pack:34.0.0.Final">
    <default-configs inherit="false"/>
    <packages inherit="false"/>
  </feature-pack>
  <feature-pack location="org.wildfly:wildfly-ai-galleon-pack:1.0.0-SNAPSHOT">
    <default-configs inherit="false"/>
    <packages inherit="false"/>
  </feature-pack>
  <config model="standalone" name="standalone.xml">
    <layers>
      <!-- Base layer -->
      <include name="cloud-server"/>
      <include name="ollama-chat-model"/>
      <include name="default-embedding-content-retriever"/>
    </layers>
  </config>
  <options>
    <option name="optional-packages" value="passive+"/>
    <option name="jboss-fork-embedded" value="true"/>
  </options>
</installation>

c. 使用 Galleon CLI 工具执行安装命令：

galleon.sh provision provisioning.xml --dir=my-wildfly-server

2. 使用 WildFly Maven Plugin 或 JAR Maven plugin 安装

在 Maven 项目的 'pom.xml' 文件中，配置 WildFly Maven Plugin 或 JAR Maven plugin，添加 'wildfly-ai-galleon-pack' feature-pack 和相应的 layer。示例如下:

<plugin>
    <groupId>org.wildfly.plugins</groupId>
    <artifactId>wildfly-maven-plugin</artifactId>
    <version>${version.wildfly.maven.plugin}</version>
    <configuration>
        <feature-packs>
            <feature-pack>
                <location>org.wildfly:wildfly-galleon-pack:${version.wildfly}</location>
            </feature-pack>
            <feature-pack>
                <location>org.wildfly:wildfly-ai-galleon-pack:1.0.0-SNAPSHOT</location>
            </feature-pack>
        </feature-packs>
        <layers>
            <layer>cloud-server</layer>
            <layer>ollama-chat-model</layer>
            <layer>default-embedding-content-retriever</layer>
        </layers>
    </configuration>
</plugin>

更多配置细节可以参考 example 项目。

服务器配置 (MCP Server)

要将 Jakarta EE 应用暴露为 MCP 服务器，需要：

添加依赖: 在 Jakarta EE 应用的 'pom.xml' 中，添加 'org.wildfly:wildfly-mcp-api' 作为 provided 依赖:

<dependency>
    <groupId>org.wildfly</groupId>
    <artifactId>wildfly-mcp-api</artifactId>
    <version>最新版本号</version> <!- - 请替换为实际版本号 - ->
    <scope>provided</scope>
</dependency>

使用 MCP 注解: 使用 'org.wildfly.mcp.api' 包提供的 '@Tool', '@Prompt', '@Resource' 等注解来标注需要暴露为 MCP 功能的 Jakarta EE 组件 (通常是 CDI bean 的方法)。

例如，可以参考 wildfly-weather 示例项目，该项目展示了如何使用注解将一个简单的天气应用暴露为 MCP 服务器。
部署应用: 将 Jakarta EE 应用部署到已安装 WildFly AI Feature Pack 的 WildFly 服务器上。

基本使用方法 (MCP Client 配置)

WildFly AI Feature Pack 提供了 'mcp-sse' 和 'mcp-stdio' 两种 MCP 客户端实现，用于连接到 MCP 服务器。您可以使用 'wildfly-mcp-chatbot' 项目通过 SSE 连接到 WildFly MCP 服务器。

MCP 客户端配置示例 (以 'mcp-sse' 为例):

在 WildFly 配置 (例如 'standalone.xml') 中，配置 'mcp-client-sse' 子系统，指定连接到 MCP 服务器所需的参数。以下是一个示例配置，假设 MCP 服务器运行在 'localhost:8080'，SSE Path 为 '/sse'：

<subsystem xmlns="urn:wildfly:extension:mcp:1.0">
    <mcp-server name="default-mcp-server">
        <mcp-endpoint sse-path="sse" messages-path="messages"/>
    </mcp-server>
    <mcp-client-sse name="my-mcp-sse-client">
        <sse-socket-binding socket-binding="http"/> <!- -  指向配置的 HTTP socket binding - ->
        <sse-path value="/sse"/> <!- - MCP 服务器 SSE endpoint path - ->
        <connect-timeout value="5000"/> <!- - 连接超时时间 (毫秒) - ->
        <log-requests value="true"/> <!- - 是否记录请求日志 - ->
        <log-responses value="true"/> <!- - 是否记录响应日志 - ->
        <ssl-enabled value="false"/> <!- - 是否启用 SSL - ->
    </mcp-client-sse>
    <mcp-tool-provider name="my-mcp-tool-provider">
        <mcp-clients>
            <mcp-client value="my-mcp-sse-client"/> <!- - 引用配置的 MCP 客户端 - ->
        </mcp-clients>
        <fail-if-one-server-fails value="false"/>
    </mcp-tool-provider>
</subsystem>

配置说明:

'mcp-client-sse name="my-mcp-sse-client"': 定义一个名为 'my-mcp-sse-client' 的 MCP SSE 客户端。
- 'sse-socket-binding socket-binding="http"': 指定用于连接的 HTTP socket binding，需要预先在 WildFly 中配置 (例如 'http' socket binding)。
- 'sse-path value="/sse"': MCP 服务器提供的 SSE endpoint 的路径，需要与服务器端配置一致。
- 'connect-timeout value="5000"': 客户端连接超时时间，单位为毫秒。
- 'log-requests value="true"' / 'log-responses value="true"': 控制是否记录请求和响应日志，方便调试。
- 'ssl-enabled value="false"': 指示是否使用 SSL 加密连接。
'mcp-tool-provider name="my-mcp-tool-provider"': 定义一个 MCP Tool Provider，用于聚合多个 MCP 客户端提供的工具。
- 'mcp-clients': 列出该 Tool Provider 使用的 MCP 客户端名称，这里引用了上面配置的 'my-mcp-sse-client'。
- 'fail-if-one-server-fails value="false"': 当连接到多个 MCP 服务器时，如果一个服务器连接失败，是否导致整个 Tool Provider 失败。

配置完成后，您可以在 Jakarta EE 应用中通过 CDI 注入 'ToolProvider' 接口的实例 (使用 '@Named("my-mcp-tool-provider")') 来使用 MCP 服务器提供的工具。

MCP 客户端配置示例 (以 'mcp-stdio' 为例):

<subsystem xmlns="urn:wildfly:extension:mcp:1.0">
    <mcp-server name="default-mcp-server">
        <mcp-endpoint sse-path="sse" messages-path="messages"/>
    </mcp-server>
    <mcp-client-stdio name="my-mcp-stdio-client">
        <cmd value="/path/to/mcp-server-command"/> <!- - MCP 服务器启动命令路径 - ->
        <args> <!- -  MCP 服务器启动命令参数 - ->
            <arg value="--server-arg1"/>
            <arg value="value1"/>
        </args>
    </mcp-client-stdio>
    <mcp-tool-provider name="my-mcp-tool-provider">
        <mcp-clients>
            <mcp-client value="my-mcp-stdio-client"/> <!- - 引用配置的 MCP 客户端 - ->
        </mcp-clients>
        <fail-if-one-server-fails value="false"/>
    </mcp-tool-provider>
</subsystem>