# text2vec-java

**Repository Path**: championwang/text2vec-java

## Basic Information

- **Project Name**: text2vec-java
- **Description**: 使用 Deep Java Library (DJL) 和 PyTorch 引擎操作 `shibing624/text2vec-base-chinese` 模型，实现中文文本的向量化表示、文本相似度计算和相关应用。
功能特性：语义相似度计算、最相似句子、候选句子相似度、文本去重、文本聚类、信息检索、问答匹配
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-28
- **Last Updated**: 2025-12-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Text2Vec Java 项目

本项目演示如何使用 Deep Java Library (DJL) 和 PyTorch 引擎操作 `shibing624/text2vec-base-chinese` 模型，实现中文文本的向量化表示和相关应用。

## 功能特性

- ✅ **文本向量化**：将中文文本转换为向量表示
- ✅ **语义相似度计算**：计算两个文本之间的语义相似度
- ✅ **句子匹配**：从候选句子中找出与目标句子最相似的句子，候选句子相似度
- ✅ **文本去重**：移除相似度高的重复文本
- ✅ **文本聚类**：使用K-means算法对文本进行聚类
- ✅ **特征提取**：为分类任务提取文本特征
- ✅ **信息检索**：根据查询找出最相关的文档
- ✅ **问答匹配**：找出与查询最相关的问答对

## 技术栈

- Java 8+
- Maven 3.6+
- Deep Java Library (DJL) 0.28.0
- PyTorch 2.2.2

## 项目结构

```
text2vec-java/
├── pom.xml
├── README.md
├── model_cache/
│   └── cache/
│       └── repo/
│           └── model/
│               └── nlp/
│                   └── text_embedding/
│                       └── ai/djl/huggingface/pytorch/
│                           └── shibing624/text2vec-base-chinese/
└── src/
    └── main/
        └── java/
            └── com/nlp/text2vec/
                ├── Text2VecDemo.java          # 演示程序主类
                ├── service/
                │   └── TextVectorizationService.java  # 核心服务类
                └── entity/
                    ├── DocumentScore.java     # 文档评分实体类
                    └── SentenceSimilarity.java # 句子相似度实体类
```

## 快速开始

### 1. 环境准备

- 安装 JDK 8 或更高版本
- 安装 Maven 3.6 或更高版本
- 确保有足够的磁盘空间（首次运行会下载模型文件，约390MB）

### 2. 编译项目

```bash
cd text2vec-java
mvn clean package
```

### 3. 运行示例

```bash
java -cp target/text2vec-java-1.0-SNAPSHOT.jar com.nlp.text2vec.Text2VecDemo
```

首次运行会自动下载模型文件到 `./model_cache` 目录，请确保网络连接正常。

## 使用示例

### 基本用法

```java
// 创建服务实例
try (TextVectorizationService service = new TextVectorizationService()) {
    
    // 获取文本向量
    float[] embedding = service.getEmbedding("这是一段中文文本");
    
    // 计算文本相似度
    double similarity = service.calculateSimilarity("文本1", "文本2");
    
    // 批量处理
    List<String> texts = Arrays.asList("文本1", "文本2", "文本3");
    List<float[]> embeddings = service.getEmbeddings(texts);
    
} catch (Exception e) {
    e.printStackTrace();
}
```

### 语义相似度计算

```java
String text1 = "这是一个中文文本向量模型";
String text2 = "这个模型用于计算文本向量";
double similarity = service.calculateSimilarity(text1, text2);
System.out.printf("文本1: %s\n文本2: %s\n相似度: %.4f\n", text1, text2, similarity);
```

### 寻找与目标句子最相似的句子

```java
// 定义目标句子
String targetSentence = "吉姆在公园里踢足球";

// 定义候选句子列表
List<String> candidateSentences = Arrays.asList(
    "这只猫正在睡觉",
    "孩子们在操场上踢球",
    "昨天下雨了",
    "他在公园踢足球",
    "她正在写作业",
    "他们一起去看电影",
    "小明在花园里踢球"
);

// 寻找与目标句子最相似的句子
String mostSimilarSentence = service.findMostSimilarSentence(targetSentence, candidateSentences);
System.out.println("目标句子: " + targetSentence);
System.out.println("最相似句子: " + mostSimilarSentence);

// 显示所有句子与目标句子的相似度排序
List<SentenceSimilarity> similarities = service.calculateSentenceSimilarities(targetSentence, candidateSentences);
similarities.forEach(sim -> System.out.printf("  %.4f - %s\n", sim.getSimilarity(), sim.getSentence()));
```

### 文本去重示例

```java
List<String> texts = Arrays.asList(
    "这是第一个文本",
    "这是第一个文本内容",
    "这是第二个文本",
    "这是第二个文本内容",
    "这是第三个完全不同的文本"
);

List<String> uniqueTexts = service.removeDuplicates(texts, 0.8);
```

### 问答匹配示例

```java
Map<String, String> qaPairs = new HashMap<>();
qaPairs.put("什么是人工智能？", "人工智能是模拟人类智能的计算机科学分支。");
qaPairs.put("如何学习编程？", "学习编程需要多实践，多阅读代码。");
qaPairs.put("Java有什么特点？", "Java是一种面向对象的编程语言，具有跨平台特性。");

String query = "人工智能的定义是什么？";
Map<String, String> relevantPairs = service.findRelevantQAPairs(query, qaPairs, 0.7);
```

### 文本聚类示例

```java
List<String> texts = Arrays.asList(
    "Java是一种编程语言",
    "Python也是一种流行的编程语言",
    "苹果是一种水果",
    "香蕉也是一种水果",
    "篮球是一项运动",
    "足球也是一项运动"
);

Map<Integer, List<String>> clusters = service.clusterTexts(texts, 3, 100);
```

### 信息检索示例

```java
List<String> documents = Arrays.asList(
    "Java是一种面向对象的编程语言，具有跨平台特性。",
    "Python是一种解释型、高级和通用的编程语言。",
    "JavaScript是一种编程语言，主要用于Web开发。",
    "C++是一种通用的编程语言，支持多种编程范式。"
);

String query = "编程语言 Web开发";
List<String> results = service.searchDocuments(query, documents, 2);
```

## 配置说明

### 模型缓存目录

默认模型缓存目录为 `./model_cache`，可以在 [TextVectorizationService.java](src/main/java/com/nlp/text2vec/service/TextVectorizationService.java) 类中修改 `CACHE_DIR` 常量来更改缓存位置。

### 相似度阈值

在问答匹配和文本去重功能中，可以调整相似度阈值来控制结果的精确度：
- 阈值越高，结果越精确但可能召回率较低
- 阈值越低，结果覆盖面越广但可能包含不相关内容

建议根据具体应用场景进行调优，一般推荐值为 0.7-0.85。

## GPU支持配置

本示例默认使用CPU版本的PyTorch，如果需要GPU支持，请按以下步骤修改依赖：

### 1. 修改pom.xml依赖

将原有的CPU依赖：
```xml
<!-- PyTorch Native Library -->
<dependency>
    <groupId>ai.djl.pytorch</groupId>
    <artifactId>pytorch-native-cpu</artifactId>
    <classifier>win-x86_64</classifier>
    <scope>runtime</scope>
    <version>2.2.2</version>
</dependency>
<dependency>
    <groupId>ai.djl.pytorch</groupId>
    <artifactId>pytorch-native-cpu</artifactId>
    <classifier>linux-x86_64</classifier>
    <scope>runtime</scope>
    <version>2.2.2</version>
</dependency>
<dependency>
    <groupId>ai.djl.pytorch</groupId>
    <artifactId>pytorch-native-cpu</artifactId>
    <classifier>osx-x86_64</classifier>
    <scope>runtime</scope>
    <version>2.0.1</version>
</dependency>
```

替换为GPU依赖：
```xml
<!-- PyTorch Native Library with CUDA support -->
<dependency>
    <groupId>ai.djl.pytorch</groupId>
    <artifactId>pytorch-native-cu118</artifactId>
    <classifier>win-x86_64</classifier>
    <scope>runtime</scope>
    <version>2.2.2</version>
</dependency>
<dependency>
    <groupId>ai.djl.pytorch</groupId>
    <artifactId>pytorch-native-cu118</artifactId>
    <classifier>linux-x86_64</classifier>
    <scope>runtime</scope>
    <version>2.2.2</version>
</dependency>
```

注意：CUDA版本需要与您的显卡驱动支持的版本匹配。上述示例使用的是CUDA 11.8版本。

### 2. 环境要求

- NVIDIA显卡，支持CUDA 11.8
- 正确安装的显卡驱动程序
- 确保系统PATH环境变量包含CUDA相关路径

### 3. GPU使用说明

DJL会自动检测可用的GPU设备，默认使用单GPU进行推理加速。如果您有多个GPU并希望指定使用特定的GPU，可以在代码中添加如下配置：

```java
// 设置使用特定GPU设备
System.setProperty("CUDA_VISIBLE_DEVICES", "0"); // 使用第一个GPU
```

或者在运行Java程序时通过JVM参数指定：
```bash
java -DCUDA_VISIBLE_DEVICES=0 -cp target/text2vec-java-1.0-SNAPSHOT.jar com.nlp.text2vec.Text2VecDemo
```

## 性能优化

1. **批量处理**：对于大量文本，使用批量方法（如 [getEmbeddings](src/main/java/com/nlp/text2vec/service/TextVectorizationService.java#L107-L113)）而不是逐个处理
2. **缓存机制**：在生产环境中，建议添加向量缓存机制，避免重复计算
3. **模型量化**：可以考虑使用模型量化技术减小模型体积和提高推理速度
4. **GPU加速**：配置GPU支持以获得更好的性能

## 常见问题

### Q: 首次运行时下载模型失败怎么办？
A: 请检查网络连接，确保能够访问 Hugging Face 模型仓库。也可以手动下载模型文件放到缓存目录中。

### Q: 如何处理长文本？
A: 对于过长的文本，建议先进行分段处理，然后将各段的向量进行平均或池化操作。

### Q: 如何提高计算速度？
A: 可以考虑：
- 使用批量处理
- 添加向量缓存
- 配置GPU支持
- 调整模型参数（如降低向量维度）

## 依赖说明

本项目主要依赖：
- `ai.djl:api` - DJL核心API
- `ai.djl.pytorch:pytorch-engine` - PyTorch引擎
- `ai.djl.pytorch:pytorch-native-cu118` - PyTorch原生库(CUDA 11.8版本)
- `ai.djl.huggingface:tokenizers` - Hugging Face分词器

详细依赖配置请查看 [pom.xml](pom.xml) 文件。

## 注意事项

1. 首次运行会下载约390MB的模型文件，请确保网络连接和磁盘空间
2. 模型加载需要一定时间，请耐心等待
3. 在生产环境中，建议添加适当的错误处理和日志记录

## 许可证

本项目采用 MIT 许可证。

## 参考资料

- [Deep Java Library (DJL) 官方文档](https://docs.djl.ai/)
- [Hugging Face Models](https://huggingface.co/models)
- [text2vec-base-chinese 模型](https://huggingface.co/shibing624/text2vec-base-chinese)