使用说明

🤖 AI工作流编排器

一个轻量级的、Spring Boot友好的插件框架 编排复杂的人工智能工作流程——集成多个LLM、工具和 MCP（模型上下文协议）零样板服务。

🚀 为什么要使用AI编排器？

🪶 轻量级架构 没有外部AI框架。用途 自定义HTTP客户端 而不是像LangChain4j这样的重型解决方案。
📦 较小的JAR大小 –减少 15-20毫巴 由于依赖性极小。
⚡ 更快的启动 –没有自动配置开销，确保快速启动时间。
🔧 API直接控制 –完全优化的请求/响应处理 Java HttpClient.
🌱 春季靴子友好 –即插即用与任何 Spring Boot 应用程序。
🚀 高性能 –通过本机HTTP API调用实现高效、低延迟的编排。

📚 目录

🚀 特性
📁 项目结构
🛠️ 快速开始
🧠 Ollama本地LLM设置
🌐 API使用
🏗️ 建筑
🔌 工作流类型和步骤类型
⚡ 即插即用工作流创建
📊 现实世界即插即用工作流示例
⚙️ 高级配置
🧪 命令行接口命令模式
🧰 日志记录
🤝 贡献
📄 许可证
👨‍💻 作者
🆘 支持
🔗 相关项目

🚀 特性

🧠 多LLM支持：OpenAI、Anthropic和Ollama，具有自定义HTTP客户端
⚙️ 动态工作流规划：AI驱动的步骤编排
🔌 MCP协议支持：HTTP、WebSocket和异步客户端
🛠️ 工具集成：无缝注册和调用自定义工具
🔄 模式转换：基于JSON模式的数据转换
🖥️ CLI和Web模式：双执行接口
🧩 智能转型：LLM驱动的数据格式转换
🪶 轻量级架构：不依赖外部AI框架
⚡ 高性能：使用Java HttpClient直接调用HTTP API

📁 项目结构

SpringAIOrchestrator/
├── ai-orchestrator-bom/           # Bill of Materials & Core Framework
│   └── ai-orchestrator-core/      # Core orchestration engine
├── examples/                      # Example workflow implementations
│   ├── ai-travel-workflow/        # Travel planning workflow example
│   └── ai-resume_builder-workflow/ # Resume building workflow example
│   └── ai-document_summarizer-workflow/ # Summaring the document and classification
├── LICENSE                        # MIT License
├── README.md                      # This documentation
└── USAGE.md                       # Detailed usage guide

🛠️ 快速开始

✅ 先决条件

☕ Java 21+
📦 Maven 3.8+
🔑 API键（OpenAI/Anthropic/Ollama）
🌐 用于LLM API调用的Internet连接
🧠当地Ollama安装

🧠 Ollama本地LLM设置

这 AI编排器框架 可以使用完全脱机运行 奥拉玛 --开源LLM的轻量级本地运行时。
这使您能够 在没有API密钥、网络依赖性或云成本的情况下本地测试工作流。

🛠️ 第一步：安装Olama

在您的系统上安装Ollama：

MacOS：

brew install ollama

Linux

curl -fsSL https://ollama.com/install.sh | sh

视窗

从下载最新安装程序 Ollama下载
运行安装程序并按照屏幕上的说明进行操作。

🛠️ 第二步：使用Olama本地（免费）模型

在models.yml中使用任何基于Ollama的模型的核心要求是使Ollama服务器在默认主机和端口上本地运行：http://localhost:11434.
验证服务：打开终端并运行ollama。该服务通常在后台自动启动。您可以通过检查来验证它是否正在运行http://localhost:11434在您的浏览器中。
在本地使用量化模型 ：量化模型是较大LLM（如Llama 2、Mistral、Gemma）的压缩版本，针对VRAM或RAM较少的消费类硬件的性能进行了优化。Ollama模型默认进行量化（通常为4位或q4）。如果需要，您可以使用模型标记来选择特定的量化级别，但对于大多数模型，默认标记已经是量化版本。

📦 常见Olama模型拉取命令和配置

目标	🧰 Ollama命令行界面命令	🧠 `models.yml` 配置
拉默认值（通常 `q4`)	`bash<br>ollama pull llama2<br>`	`yaml<br>modelName: "llama2"<br>`
拉特定（例如3位）	`bash<br>ollama pull llama2:7b-q3_K_L<br>`	`yaml<br>modelName: "llama2:7b-q3_K_L"<br>`
拉取最新版本	`bash<br>ollama pull llama3<br>`	`yaml<br>modelName: "llama3"<br>`
Pull专用编码器型号	`bash<br>ollama pull qwen2.5-coder:14b-instruct-q3_K_L<br>`	`yaml<br>modelName: "qwen2.5-coder:14b-instruct-q3_K_L"<br>`
轻量化模型	`bash<br>ollama pull mistral<br>`	`yaml<br>modelName: "mistral"<br>`

🧩 配置本地ollama模型示例(`models.yml`)

本地别名使用 默认量化 llama2 模型取自Ollama：

models:
  - alias: "local"
    provider: "ollama"
    modelName: "llama2"
    baseUrl: "http://localhost:11434"
    enabled: true

☁️ 步骤3：使用Ollama云模型

对于以下型号 太大，无法在本地运行 在您的个人计算机上， Ollama云模型 提供无缝解决方案。他们利用 远程高性能GPU硬件 同时仍被访问 通过您的本地 http://localhost:11434 端点 --所以你的应用程序代码 不需要任何更改.

🔐 登录Ollama Cloud

云模型需要Ollama帐户。从您的终端登录：

ollama signin

☁️ 拉取/使用云模型

# Example: Pulling a cloud model
ollama pull qwen3-coder:480b-cloud

🧩 配置示例（models.yml）

下面的示例显示了如何配置默认别名以使用云卸载的qwen3编码器：480b云模型。

models:
- alias: "default"
  provider: "ollama"
  modelName: "qwen3-coder:480b-cloud"  # This model is offloaded to Ollama Cloud
  baseUrl: "http://localhost:11434"
  enabled: true

- alias: "transformer"
  provider: "ollama"
  modelName: "qwen3-coder:480b-cloud"
  baseUrl: "http://localhost:11434"
  enabled: true

⚙️ 代码安装

克隆仓库

git clone <repository-url>
cd SpringAIOrchestrator/spring-ai-orchestrator

构建框架

cd ai-orchestrator-bom
mvn clean install

设置环境变量

# Required LLM API Keys
export OPENAI_API_KEY="your-openai-key"
export ANTHROPIC_API_KEY="your-anthropic-key"
export OLLAMA_BASE_URL="http://localhost:11434"

# Application Configuration
export SERVER_PORT=8282
export CLI_MODE=false
export APP_NAME="ai-orchestrator"

# Optional: Planner Configuration
export PLANNER_FALLBACK=true
export PLANNER_MAX_ITERATIONS=5
export PLANNER_TARGET_RANK=10

运行示例工作流

cd ../examples/ai-travel-workflow
mvn spring-boot:run

# Or run resume workflow
cd ../ai-resume_builder-workflow
mvn spring-boot:run

🌐 API使用

🗺️ 运行旅行工作流

# Plan a trip to Tokyo
curl -X POST "http://localhost:8282/api/workflows/run/travel-planner" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "prompt=Plan a 5-day trip to Tokyo in March with budget of $3000"

# Business trip planning
curl -X POST "http://localhost:8282/api/workflows/run/travel-planner" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "prompt=Business trip to London for 3 days, need flights and hotel recommendations"

📄 运行恢复工作流

# Create Java developer resume
curl -X POST "http://localhost:8282/api/workflows/run/resume-builder" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "prompt=Create resume for Senior Java Developer with 5 years Spring Boot experience"

# Create data scientist resume
curl -X POST "http://localhost:8282/api/workflows/run/resume-builder" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "prompt=Build resume for Data Scientist role with Python and ML expertise"

📋 列出所有工作流

curl -X GET "http://localhost:8282/api/workflows/list"

# Response example:
{
  "travel-planner": "travel-planner - AI-powered travel planning with weather, flights, and cost analysis",
  "resume-builder": "AI Resume Builder - Create a professional resume from user inputs and job descriptions"
}

🏗️ 建筑

这 AI编排器框架 使用a 轻量级定制架构:

🧠 规划师LLM –生成智能执行计划并对其进行排名
🔄 变压器LLM –处理步骤之间的格式转换
🔗 自定义HTTP客户端 –在没有外部人工智能框架的情况下直接集成API
🪶 零依赖 –没有LangChain4j或类似的重型框架

┌─────────────────────────────────────────────────────────────────────────┐
│                        AI Orchestrator Framework                        │
└─────────────────────────────────────────────────────────────────────────┘

┌──────────────┐  ┌──────────────┐  ┌──────────────┐
│ User Input   │  │ REST API     │  │ CLI Mode     │
└──────┬───────┘  └──────┬───────┘  └──────┬───────┘
       │                 │                 │
       └─────────────────┼─────────────────┘
                         │
               ┌─────────▼─────────┐
               │ Workflow Controller│
               └─────────┬─────────┘
                         │
              ┌──────────▼──────────┐
              │ Dynamic Engine (AI) │
              └──────────┬──────────┘
                         │
           ┌─────────────▼─────────────┐
           │  🧠 Planner + 🔄 Transformer │
           └─────────────┬─────────────┘
                         │
           ┌─────────────▼─────────────┐
           │    Step Execution Engine   │
           └────────────────────────────┘

🔌 工作流类型和步骤类型

工作流类型

🔁 顺序的 –预定义的步骤顺序
🧠 动态的 –AI计划执行顺序

步骤类型

🤖 LLM –语言模型交互
🔧 工具 –自定义注释方法
🌐 主控程序 –外部服务调用（HTTP、WebSocket、异步）

⚡ 即插即用工作流创建

在中创建新的AI工作流程 5分钟 🚀

添加依赖关系

<dependency>
  <groupId>codetumblr.net.ai.orchestrator</groupId>
  <artifactId>ai-orchestrator-core</artifactId>
  <version>1.0-SNAPSHOT</version>
</dependency>

创建应用

@SpringBootApplication
@ComponentScan({"codetumblr.net.ai.orchestrator.core", "your.package"})
public class MyWorkflowApplication {
  public static void main(String[] args) {
    SpringApplication.run(MyWorkflowApplication.class, args);
  }
}

定义模型 (models.yml)

models:
  - alias: "default"
    provider: "openai"
    model: "gpt-4"
    apiKey: "${OPENAI_API_KEY}"

创建工作流 (workflows/my-workflow.yaml)

id: "document-analyzer"
executionMode: "dynamic"
steps:
  - id: "extract_content"
    type: "tool"
    parameters:
      tool: "document_extractor"
  - id: "analyze_sentiment"
    type: "llm"
    parameters:
      model: "default"
      prompt: "Analyze sentiment: {input}"

添加工具

@Component
public class DocumentTools {
  @AiTool(name = "document_extractor")
  public String extractText(String filePath) {
    return "Extracted content...";
  }
}

运行工作流

mvn spring-boot:run

📊 现实世界即插即用工作流示例

这 AI工作流编排器 附带现成的生产级工作流示例。这些演示了如何组合 LLM、工具和MCP服务 只需最少的设置即可进入强大的管道。

🚀 内置示例

🛫 旅行计划 -自动计划详细的多日旅行行程，包括航班、天气和成本分析。
📄 履历表生成器 –直接根据职位描述或技能组合生成量身定制的专业简历。
📜 文档摘要生成器 –使用 动态工作流.

🧩 即将到来的示例（计划中）

🧠 智能聊天代理 –构建一个上下文感知的工具调用助手。
📈 财务报告分析器 –分析CSV，提取关键指标，并生成业务摘要。
🧪 代码审查助理 –使用代码感知LLM分析拉取请求并提出改进建议。

💡 提示： 每个示例都是完全模块化的，可以 定制或扩展 只需编辑工作流YAML文件，无需更改代码。

🖥️ UI/Web集成-文档摘要生成器

该框架支持典型的Spring Boot web控制器，以实现简单的文件上传和动态提示生成，用于复杂的工作流程，如Document Summary er。

原理用户通过web界面上传文件（PDF、DOCX等）。

Spring控制器读取文件，Base64对二进制内容进行编码。

控制器动态构建一个详细的Planner Prompt，其中包含Base64内容和文件元数据。

用户可以在将提示提交给Orchestrator的API执行之前查看/编辑该提示。然后，LLM Planner使用Base64内容路由到初始MCP步骤（extract_text）。

运行Web示例 要运行文档摘要生成器的web应用程序，请执行以下操作：

cd examples/ai-document_summarizer-workflow
mvn spring-boot:run

在浏览器中访问应用程序：http://localhost:8383/

关键控制器端点

端点	方法	描述
`/`	`GET`	显示文档上载表单
`/generate-prompt`	`POST`	处理文件上传，对文件进行Base64编码，并构建LLM Planner提示。转到评论页面。
`/submit-prompt`	`POST`	将最终生成的提示提交给核心 AI编排器API (`/api/workflows/run/document-summarizer`)执行。

⚙️ 高级配置选项

完成应用程序配置

# application.yml
server:
  port: ${SERVER_PORT:8282}
  
spring:
  application:
    name: ${APP_NAME:ai-orchestrator-travel_planner}
  shell:
    interactive:
      enabled: ${CLI_MODE:false}
    command:
      quit:
        enabled: true
    history:
      enabled: false
    script:
      enabled: false
  main:
    allow-circular-references: true
    web-application-type: servlet
  devtools:
    restart:
      enabled: false
    livereload:
      enabled: false
  boot:
    admin:
      enabled: false

logging:
  config: classpath:log4j2.xml

ai:
  orchestrator:
    workflows:
      path: ${WORKFLOWS_PATH:classpath*:workflows/*-workflow.yaml}
    models:
      description-truncate-length: ${DESC_TRUNCATE_LENGTH:30}
      path: classpath:${MODELS_PATH:/models.yml}
    planner:
      fallback-enabled: ${PLANNER_FALLBACK:true}
      step-separator: ${STEP_SEPARATOR:,}
      max-iterations: ${PLANNER_MAX_ITERATIONS:5}
      target-rank: ${PLANNER_TARGET_RANK:10}
      prompt:
        path: ${PLANNER_PROMPT_PATH:}
    transformer:
      prompt:
        path: ${TRANSFORMER_PROMPT_PATH:}
    mcp:
      clients:
        path: classpath:${MCP_CLIENTS_PATH:/mcp-clients.yml}

MCP客户端配置

# mcp-clients.yml
clients:
  - name: "weather-services-api"
    endpoint: "${MCP_WEATHER_ENDPOINT:http://localhost:8282}"
    service: "weather_forecast"
    protocol: "${MCP_WEATHER_PROTOCOL:http}"
    timeout: "${MCP_WEATHER_TIMEOUT:5000}"  # Configurable timeout
    auth:
      type: "${MCP_WEATHER_AUTH_TYPE:none}"  # none, basic, oauth2, api-key, jwt
      apiKey: "${MCP_WEATHER_API_KEY:}"
      apiKeyHeader: "${MCP_WEATHER_API_KEY_HEADER:X-API-Key}"
    enabled: "${MCP_WEATHER_ENABLED:true}"

  - name: "flight-services-api"
    endpoint: "${MCP_FLIGHT_ENDPOINT:http://localhost:8282}"
    service: "search_flights"
    protocol: "${MCP_FLIGHT_PROTOCOL:http}"
    timeout: "${MCP_FLIGHT_TIMEOUT:5000}"   # Configurable timeout
    auth:
      type: "${MCP_FLIGHT_AUTH_TYPE:none}"
    enabled: "${MCP_FLIGHT_ENABLED:true}"

模型配置

# models.yml
config:
  defaultMaxTokens: 1000
  promptTruncateLength: 50
  descriptionTruncateLength: 30
  autoRegisterForPlugins: true

models:
  - alias: "default"
    provider: "ollama"
    modelName: "qwen3-coder:480b-cloud"
    baseUrl: "http://localhost:11434"
    temperature: 0.7
    maxTokens: 2000
    enabled: true

  - alias: "openai"
    provider: "openai"
    modelName: "gpt-4o-mini"
    apiKey: "${OPENAI_API_KEY}"
    temperature: 0.7
    maxTokens: 4000
    enabled: true

  - alias: "planner"
    provider: "ollama"
    modelName: "qwen2.5-coder:14b-instruct-q3_K_L"
    baseUrl: "http://localhost:11434"
    temperature: 0.3
    maxTokens: 1500
    enabled: true

  - alias: "transformer"
    provider: "ollama"
    modelName: "qwen3-coder:480b-cloud"
    baseUrl: "http://localhost:11434"
    temperature: 0.1
    maxTokens: 1000
    enabled: true

🧪 命令行接口命令模式

启用交互式CLI执行：

export CLI_MODE=true
mvn spring-boot:run
  or
CLI_MODE=true mvn spring-boot:run
  or
java -DCLI_MODE=true -jar ai-travel-workflow-1.0-SNAPSHOT.jar

可用命令

# List workflows
lw

# Interactive workflow selection
interactive
i
run-interactive

# Run specific workflow
run --workflow-id travel-planner --prompt "Plan weekend trip to Paris"
run-workflow --workflow-id resume-builder --prompt "Create resume for DevOps engineer"

# Quick run by number
quick --number 1
q --number 2

# Show help
help
h
?

# Logging info
log-info
logs
debug-help

# Exit CLI
exit
quit
bye

🧰 日志记录配置

该框架使用log4j2.xml进行日志配置。日志记录通过以下方式配置：

logging:
  config: classpath:log4j2.xml

日志文件被写入 logs/ 应用程序根目录中的目录。

可配置超时

# Planner Configuration (All Configurable)
ai:
  orchestrator:
    planner:
      max-iterations: 5        # Maximum planning iterations
      target-rank: 10          # Target plan quality rank
      fallback-enabled: true   # Enable fallback when planning fails

# MCP Client Timeouts (Per Client)
clients:
  - name: "weather-services-api"
    timeout: "5000"           # 5 seconds (configurable)
  - name: "flight-services-api"
    timeout: "5000"           # 5 seconds (configurable)

硬编码超时-改进范围（基于配置）

LLM计划超时：120秒
计划会话超时：60秒
LLM客户端超时：5分钟请求，30秒连接
架构缓存：自动使用ConcurrentHashMap
HTTP客户端：带连接池的Java 21 HttpClient

🔧 环境变量引用

核心应用程序

export SERVER_PORT=8282
export CLI_MODE=false
export APP_NAME="ai-orchestrator"

LLM API密钥

export OPENAI_API_KEY="sk-your-openai-key"
export ANTHROPIC_API_KEY="sk-ant-your-anthropic-key"
export OLLAMA_BASE_URL="http://localhost:11434"

计划器配置

export PLANNER_FALLBACK=true
export PLANNER_MAX_ITERATIONS=5
export PLANNER_TARGET_RANK=10
export STEP_SEPARATOR=","
export PLANNER_PROMPT_PATH=""
export TRANSFORMER_PROMPT_PATH=""

文件路径

export WORKFLOWS_PATH="classpath*:workflows/*-workflow.yaml"
export MODELS_PATH="/models.yml"
export MCP_CLIENTS_PATH="/mcp-clients.yml"

日志记录级别

export PLANNER_LOG_LEVEL=INFO
export ENGINE_LOG_LEVEL=INFO
export WORKFLOW_LOG_LEVEL=INFO
export MCP_SERVICE_LOG_LEVEL=INFO
export SCHEMA_LOG_LEVEL=INFO

🆘 故障排除

常见问题及解决方案

问题	解决方案
`Schema not found`	验证架构文件是否存在于 `resources/schemas/`
`LLM client not available`	检查API密钥和网络连接
`Workflow not found`	确保工作流YAML在 `resources/workflows/`
`Tool execution failed`	验证工具参数和实施
`MCP service timeout`	检查MCP客户端配置和端点
`Planning failed`	启用计划回退： `PLANNER_FALLBACK=true`

健康检查

# Check workflow status
curl -X GET "http://localhost:8282/api/workflows/list"

# Verify environment variables
echo $OPENAI_API_KEY
echo $ANTHROPIC_API_KEY
echo $OLLAMA_BASE_URL

调试步骤

启用调试日志记录

export PLANNER_LOG_LEVEL=DEBUG
export ENGINE_LOG_LEVEL=DEBUG
export WORKFLOW_LOG_LEVEL=DEBUG

请参阅log4j2.xml -针对不同的组件日志记录级别


2. **Check Log Files**
```bash
tail -f logs/ai-orchestrator-**.log

验证配置

# Check YAML syntax
cat src/main/resources/models.yml
cat src/main/resources/mcp-clients.yml

🤝 贡献

我们❤️ 贡献！

分叉回购
创建要素分支
添加Javadoc和测试
提交PR🚀

📄 许可证

该项目根据 MIT许可证。请参阅许可证文件以获取详细信息。

👨‍💻 作者

Ravinderjeet Singh Nagpal
构建下一代人工智能编排系统。

📊 性能特点

🪶 轻量级架构

无外部AI框架 -自定义HTTP客户端，而不是LangChain4j
较小的JAR大小 -减少约15-20MB，无严重依赖
更快的启动 -无自动配置开销
API直接控制 -优化请求/响应处理

支持资源

🔑 验证环境变量配置
📜 验证YAML和模式语法
📖 看用法.md 详细示例
🐛 启用调试日志记录以进行详细跟踪

🔗 相关项目

Spring Boot Java后端框架
模型上下文协议 –MCP规范

⭐ 标记此回购 如果你觉得有帮助的话！您的支持使此项目不断发展🚀