# langchain4j-functioncall-demo

**Repository Path**: mbqx/langchain4j-functioncall-demo

## Basic Information

- **Project Name**: langchain4j-functioncall-demo
- **Description**: 基于 LangChain4j + Spring Boot 的最小化 Function Call 演示项目


- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-21
- **Last Updated**: 2026-04-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# LangChain4j Function Call Demo

基于 **LangChain4j** + **Spring Boot** 的最小化 Function Call 演示项目，接入阿里云百炼（通义千问）大模型。

项目同时展示了两种工具暴露方式：
- **方式A**：LangChain4j 原生 `@Tool` 注解（生产推荐，自动集成）
- **方式B**：自定义 `@FunctionTool` + 反射扫描注册（与你方案一致，完全可控）

---

## 项目结构

```
├── pom.xml
├── README.md
└── src/main/java/com/example/demo/
    ├── DemoApplication.java
    ├── annotation/
    │   ├── FunctionTool.java          # 自定义工具注解
    │   └── Param.java                  # 自定义参数注解
    ├── config/
    │   ├── Assistant.java              # LangChain4j AI 助手接口
    │   └── LangChainConfig.java        # ChatModel 与 Assistant 配置
    ├── controller/
    │   └── ChatController.java         # REST API 入口
    ├── model/
    │   ├── City.java                   # 城市信息实体
    │   └── Resume.java                 # 简历实体
    ├── service/
    │   ├── CityService.java            # 城市查询服务（@Tool 方式）
    │   ├── ResumeService.java          # 简历搜索服务（@Tool 方式）
    │   └── CustomToolRegistry.java     # 自定义注解扫描注册中心
    └── tool/
        └── ResumeSearchTool.java       # 简历搜索工具（@FunctionTool 方式）
```

---

## 前置准备

### 1. 获取阿里云百炼 API Key

访问 [阿里云百炼控制台](https://bailian.console.aliyun.com/)，创建 API Key。

### 2. 配置环境变量

```bash
export BAILIAN_API_KEY=sk-your-api-key-here
```

---

## 运行项目

```bash
cd /Users/bqx/gongzuo/ideaSpace/langchain4j-functioncall-demo

# 编译运行
mvn spring-boot:run
```

---

## API 使用示例

### 方式A：LangChain4j 原生 @Tool（自动 Function Calling）

大模型会自动判断是否需要调用工具，并返回自然语言结果。

```bash
curl -X POST http://localhost:8080/api/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "帮我找一个会 Java 和 Spring 的候选人"}'
```

预期行为：
1. 大模型识别意图 → 决定调用 `searchResumeBySkills`
2. LangChain4j 自动执行 `ResumeService.searchResumeBySkills(...)`
3. 将工具返回结果回传给大模型
4. 大模型生成最终自然语言回复

**城市查询示例**：

```bash
curl -X POST http://localhost:8080/api/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "北京的工作机会和生活成本怎么样？"}'
```

预期行为：
1. 大模型识别意图 → 决定调用 `queryWorkCity`
2. LangChain4j 自动执行 `CityService.queryWorkCity("北京")`
3. 大模型基于返回数据生成回复

---

### 方式B：自定义 @FunctionTool + 反射扫描

#### 查看已注册的自定义工具

```bash
curl http://localhost:8080/api/tools
```

返回示例：

```json
{
  "success": true,
  "count": 1,
  "tools": {
    "searchResumeBySkillCustom": {
      "name": "searchResumeBySkillCustom",
      "description": "【自定义注解方式】根据技能关键词列表搜索候选人简历",
      "schemaJson": "{ ... }"
    }
  }
}
```

#### 手动执行自定义工具

```bash
curl -X POST http://localhost:8080/api/tools/execute \
  -H "Content-Type: application/json" \
  -d '{
    "toolName": "searchResumeBySkillCustom",
    "arguments": {
      "skills": ["Java", "Spring"],
      "minWorkYears": 3
    }
  }'
```

返回示例：

```json
{
  "success": true,
  "toolName": "searchResumeBySkillCustom",
  "result": [
    {
      "id": "R001",
      "name": "张三",
      "skills": ["Java", "Spring", "Spring Boot", "MySQL", "Redis", "Kafka"],
      "city": "北京",
      "workYears": 5,
      "summary": "5年后端开发经验，熟悉高并发架构设计..."
    }
  ]
}
```

---

## 两种方式的对比

| 维度 | 方式A：`@Tool`（LangChain4j 原生） | 方式B：`@FunctionTool`（自定义） |
|------|-----------------------------------|--------------------------------|
| **代码侵入** | 极小，加注解即可 | 需要自建扫描注册与执行逻辑 |
| **Schema 生成** | 框架自动生成 | 需手写反射解析 + JSON Schema 构建 |
| **LLM 集成** | 与 AiServices 无缝集成 | 需自行实现与大模型的交互链路 |
| **适用场景** | 快速开发、生产环境 | 需要完全控制元数据、多框架适配 |
| **工具发现** | 运行时自动绑定到 Assistant | 独立注册中心，可外部暴露 |
| **灵活性** | 受限于 LangChain4j 规范 | 完全自定义，可扩展任意协议（如 MCP） |

---

## 扩展建议

1. **接入更多模型**：修改 `LangChainConfig` 中的 `modelName`，如 `qwen-max`、`qwen-turbo`
2. **添加更多工具**：在 `CityService` / `ResumeService` 中添加新的 `@Tool` 方法即可自动暴露
3. **自定义注解增强**：可在 `CustomToolRegistry` 中添加权限校验、调用日志、限流等能力
4. **向 MCP 演进**：将 `CustomToolRegistry` 的元数据通过 HTTP/SSE 暴露，即可升级为 MCP Server

---

## 依赖版本

| 组件 | 版本 |
|------|------|
| Java | 17 |
| Spring Boot | 3.2.5 |
| LangChain4j | 0.36.2 |

---

## 许可证

MIT