# AI-Workflow-for-Java

**Repository Path**: jzwsoft/ai-workflow-for-java

## Basic Information

- **Project Name**: AI-Workflow-for-Java
- **Description**: 使用Java开发AI 的workflow
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-17
- **Last Updated**: 2026-06-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI-Workflow-for-Java

使用 Java + Spring Boot + Spring AI 构建的 AI Workflow 项目。  
首个业务场景：**客服问答 + 查订单**（当前为阶段 5：多步 Workflow / Agent）。

## 技术栈

| 组件 | 说明 |
|------|------|
| Java 21 | 运行时 |
| Spring Boot 3.4 | Web 服务 |
| Spring AI 1.0 | LLM + Embedding + 向量检索（Ollama） |
| Ollama | 本地大模型与 Embedding 推理 |
| SimpleVectorStore | 本地向量库（开发/演示） |

## 项目结构

```
src/main/java/com/aiworkflow/
├── AiWorkflowApplication.java
├── api/
│   ├── ChatController.java           # /api/chat 接口
│   └── dto/                            # 请求/响应对象
└── workflow/
    ├── Workflow.java
    ├── engine/                         # 线性链 + 条件分支
    │   ├── WorkflowChain.java
    │   ├── WorkflowRouter.java
    │   └── WorkflowState.java
    ├── agent/                          # ReAct Agent 循环
    │   └── ReActAgentLoopClient.java
    ├── approval/                       # 人工审批（可接 Temporal/Camunda）
    │   └── InMemoryHumanApprovalService.java
    ├── orchestrator/
    │   ├── InProcessWorkflowOrchestrator.java
    │   └── TemporalWorkflowOrchestratorAdapter.java
    ├── customer/
    │   ├── CustomerServiceWorkflow.java
    │   └── steps/                      # 可组合 Step
    ├── llm/
    │   ├── StructuredLlmClient.java
    │   └── ToolCallingLlmClient.java
    └── prompt/
        └── PromptTemplateService.java
└── tool/
    ├── ToolExecutionGuard.java         # 权限、超时、调用上限
    ├── order/
    │   ├── OrderQueryTool.java         # 查订单工具
    │   └── OrderService.java
    └── knowledge/
        └── KnowledgeBaseTool.java      # RAG 知识库检索工具
└── rag/
    ├── KnowledgeIngestionService.java  # 文档切块入库
    ├── RagRetrievalService.java        # Top-K 检索
    └── RagEvaluator.java               # 命中率/幻觉评估

src/main/resources/knowledge/           # 原始知识库文档
src/main/resources/prompts/
├── customer-service-system.st
├── customer-service-user.st
└── customer-service-structure.st
```

## Workflow 流程（阶段 5）

`CustomerServiceWorkflow` 采用 **线性链 + 条件分支 + Agent 循环**：

```
parse-input → classify-intent → [按意图路由]
  ├─ ORDER_QUERY  → agent-reasoning → structure → evaluate
  ├─ FAQ          → rag-retrieval → agent-reasoning → structure → evaluate
  ├─ REFUND       → human-approval-gate → agent-reasoning → structure → evaluate
  └─ GENERAL_CHAT → agent-reasoning → structure → evaluate
```

- **线性链**：`WorkflowChain` 顺序执行 Step
- **条件分支**：`WorkflowRouter` 按 `intent` 路由子流程
- **Agent 循环**：`ReActAgentLoopClient` 思考 → 调工具 → 再思考（最多 N 轮）
- **人工审批**：退款/投诉类请求挂起，审批通过后携带 `resumeApprovalId` 恢复
- **长事务编排**：默认进程内执行；可切换 `ai.workflow.orchestrator.type=TEMPORAL|CAMUNDA`（适配器占位，生产需接入真实 SDK）

API 响应新增字段：`stepsExecuted`、`branch`、`agentIterations`、`pendingApprovalId`、`executionStatus`

## 前置条件

1. **JDK 21**
2. **Maven 3.9+**
3. **Ollama** 已安装并运行

```bash
# 安装后启动 Ollama（macOS 一般会自动运行）
ollama serve

# 对话模型
ollama pull qwen3:4b-instruct

# Embedding 模型（RAG 必需）
ollama pull nomic-embed-text
```

也可通过环境变量指定模型：`OLLAMA_MODEL`、`OLLAMA_EMBEDDING_MODEL`。

## 快速开始

### 1. 编译

```bash
mvn clean package -DskipTests
```

### 2. 启动应用

```bash
mvn spring-boot:run
```

或：

```bash
java -jar target/ai-workflow-for-java-0.1.0-SNAPSHOT.jar
```

### 3. 调用对话接口

```bash
# 咨询政策（预期调用 searchKnowledge）
curl -X POST http://localhost:8080/api/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "你好，我想咨询一下退换货政策"}'

# 查订单（预期调用 queryOrder）
curl -X POST http://localhost:8080/api/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "帮我查一下订单 ORD123456789 的物流"}'
```

示例响应：

```json
{
  "reply": "我们支持 7 天无理由退换货……",
  "intent": "FAQ",
  "orderId": null,
  "nextAction": "NONE",
  "toolsUsed": ["searchKnowledge"],
  "ragSources": ["return-policy.md"],
  "ragHit": true,
  "grounded": true,
  "hallucinationRisk": 0.1,
  "stepsExecuted": ["parse-input", "classify-intent", "rag-retrieval", "agent-reasoning"],
  "branch": "FAQ",
  "agentIterations": 1,
  "executionStatus": "COMPLETED"
}
```

### 5. 人工审批（退款/投诉）

```bash
# 发起退款请求（将返回 pendingApprovalId）
curl -X POST http://localhost:8080/api/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "我要申请退款，订单有问题"}'

# 查询审批单
curl http://localhost:8080/api/workflow/approvals/{approvalId}

# 审批通过
curl -X POST http://localhost:8080/api/workflow/approvals/{approvalId}/approve \
  -H "Content-Type: application/json" \
  -d '{"comment": "同意退款"}'

# 携带 resumeApprovalId 恢复流程
curl -X POST http://localhost:8080/api/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "继续处理退款", "resumeApprovalId": "{approvalId}"}'
```

### 4. RAG 检索评估

```bash
# 查看 RAG 配置状态
curl http://localhost:8080/api/rag/status

# 单独评估检索质量（命中率、幻觉风险）
curl -X POST http://localhost:8080/api/rag/evaluate \
  -H "Content-Type: application/json" \
  -d '{"query": "退换货政策是什么", "answer": "我们支持 7 天无理由退换货"}'
```

## 配置说明

在 `src/main/resources/application.yml` 中可调整，或通过环境变量覆盖：

| 环境变量 | 默认值 | 说明 |
|----------|--------|------|
| `OLLAMA_BASE_URL` | `http://localhost:11434` | Ollama 服务地址 |
| `OLLAMA_MODEL` | `qwen3:4b-instruct` | 对话模型（需支持 Function Calling） |
| `OLLAMA_EMBEDDING_MODEL` | `nomic-embed-text` | Embedding 模型 |

RAG 配置（`application.yml` → `ai.workflow.rag`）：

| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| `enabled` | `true` | 是否启用 RAG |
| `top-k` | `3` | 检索返回文档块数量 |
| `similarity-threshold` | `0.5` | 相似度阈值 |
| `chunk-size` | `200` | 文档切块大小 |
| `vector-store-path` | `data/vector-store.json` | 向量库持久化路径 |

工具配置（`application.yml` → `ai.workflow.tools`）：

| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| `timeout` | `5s` | 单次工具调用超时 |
| `max-calls-per-request` | `3` | 单次请求最多调用工具次数 |
| `enabled` | `ORDER_QUERY, KNOWLEDGE_BASE` | 启用的工具权限 |

Agent 配置（`ai.workflow.agent`）：

| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| `max-iterations` | `5` | Agent 循环最大轮次 |
| `request-approval-on-sensitive-refund` | `true` | 敏感退款是否请求审批 |

编排器配置（`ai.workflow.orchestrator`）：

| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| `type` | `IN_PROCESS` | `IN_PROCESS` / `TEMPORAL` / `CAMUNDA` |

## 开发路线图

| 阶段 | 内容 | 状态 |
|------|------|------|
| 阶段 1 | Spring Boot + Ollama，实现 `/api/chat` | ✅ 完成 |
| 阶段 2 | Workflow 抽象，结构化客服流程 | ✅ 完成 |
| 阶段 3 | Tool Calling，查订单/知识库工具 | ✅ 完成 |
| 阶段 4 | RAG 知识库问答 | ✅ 完成 |
| 阶段 5 | 多步 Workflow / Agent | ✅ 当前 |
| 阶段 6 | 生产化（记忆、限流、监控） | 待开发 |

## 运行测试

```bash
mvn test
```

测试覆盖 Workflow、Tool 权限/超时、业务服务与 API 层，使用 Mock LLM 固定响应，无需连接 Ollama：

- `CustomerServiceWorkflowTest`：多步分支 + Agent 注入
- `RefundApprovalWorkflowTest`：退款人工审批挂起
- `WorkflowChainTest` / `WorkflowRouterTest`：编排引擎
- `IntentClassifierTest`：意图路由
- `ToolExecutionGuardTest`：权限、超时、调用上限
- `RagEvaluatorTest`：命中率与幻觉风险评估
- `KnowledgeDocumentLoaderTest`：知识库文档加载
- `DocumentChunkerTest`：文档切块
- `OrderQueryToolTest`：工具权限校验
- `ChatControllerTest`：API 返回 `toolsUsed`

## 常见问题

**Q: 启动报错连接不上 Ollama？**  
确认 `ollama serve` 已运行，且 `curl http://localhost:11434/api/tags` 能返回模型列表。

**Q: 报错 model not found？**  
执行 `ollama pull qwen2.5:3b`，或设置 `OLLAMA_MODEL` 为你已拉取的模型名。

**Q: 模型不调用工具？**  
确认模型支持 Function Calling（推荐 `qwen3:4b-instruct`、`qwen2.5:7b`、`llama3.1` 等）。

**Q: RAG 检索无结果？**  
确认已拉取 `nomic-embed-text`，并删除 `data/vector-store.json` 后重启以重新入库。

**Q: 工具调用超时？**  
可在 `application.yml` 调大 `ai.workflow.tools.timeout`。

## License

MIT