# schedule-embedding-api

文本向量化与向量检索服务

## 快速开始

### 1. 环境要求

- Java 17
- Elasticsearch 8.x
- MySQL 8.x (可选，用于日志记录)

### 2. 启动前配置

#### 2.1 初始化数据库

```bash
mysql -h 127.0.0.1 -P 3306 -uroot -p123456 < docs/init.sql
```

#### 2.2 修改配置

编辑 `src/main/resources/application.yml`，根据需要修改配置：

```yaml
# Elasticsearch 配置
elasticsearch:
  host: http://localhost:9200
  index:
    name: contract_chunks

# Embedding API 配置
embedding:
  api:
    url: http://localhost:18081/v1
    model: Qwen3-Embedding-8B

# MySQL 配置（日志记录用）
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/schedule_embedding
    username: root
    password: 123456
```

### 3. 启动

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

服务启动后访问：`http://localhost:8084/actuator/health`

---

## Kafka 开关说明

### 同步模式（默认，推荐开发测试）

```yaml
kafka:
  enabled: false
```

- 适用场景：单机部署、直接同步处理文档入库
- 优点：启动快，不依赖 Kafka

### 异步模式（生产环境）

```yaml
kafka:
  enabled: true
  topics:
    embedding: embedding-topic

spring:
  kafka:
    bootstrap-servers: localhost:9092
```

- 适用场景：需要消息队列解耦、异步处理大量文档
- 优点：支持高并发、削峰填谷

### 切换步骤

1. 修改 `kafka.enabled` 为 `true` 或 `false`
2. 如果启用 Kafka，需确保：
   - Kafka 服务正常运行
   - topic `embedding-topic` 已创建
3. 重启应用

---

## API 接口

| 接口 | 方法 | 路径 | 功能 |
|------|------|------|------|
| 健康检查 | GET | /actuator/health | 服务状态 |
| 文档入库 | POST | /api/v1/documents/index | 单个文档向量化入库 |
| 批量入库 | POST | /api/v1/documents/batch-index | 批量文档向量化入库 |
| 向量搜索 | POST | /api/v1/search | 基于语义的向量搜索 |
| 混合搜索 | POST | /api/v1/search/hybrid | 向量搜索+业务字段过滤 |
| 查询文档 | GET | /api/v1/documents/{docId} | 查询文档的所有chunks |
| 删除文档 | DELETE | /api/v1/documents/{docId} | 删除文档的所有chunks |

详细接口文档见：`docs/API接口文档.md`

---

## 数据库

数据库初始化脚本：`docs/init.sql`

### 表说明

| 表名 | 说明 |
|------|------|
| operation_log | 操作日志 - 记录 HTTP API 调用 |
| kafka_processing_log | Kafka 处理日志 - 记录消息处理过程 |

### 示例查询

```sql
-- 查看最近的操作日志
SELECT * FROM schedule_embedding.operation_log ORDER BY create_time DESC LIMIT 10;

-- 按操作类型统计
SELECT operation_type, COUNT(*) FROM schedule_embedding.operation_log GROUP BY operation_type;
```

---

## 验证测试

### 1. 验证服务启动

```bash
# 检查服务健康状态
curl http://localhost:8084/actuator/health
```

预期返回：
```json
{"status":"UP","components":{...}}
```

### 2. 验证 Elasticsearch 连接

```bash
# 检查 ES 集群状态
curl http://localhost:9200/_cluster/health
```

或通过服务健康检查：
```bash
curl http://localhost:8084/actuator/health | grep elasticsearch
```

### 3. 简单功能测试

#### 3.1 文档入库

```bash
curl -X POST http://localhost:8084/api/v1/documents/index \
  -H "Content-Type: application/json" \
  -d '{
    "docId": "test-001",
    "fileName": "测试文档.pdf",
    "fullText": "这是一条测试数据，用于验证文档向量化入库功能是否正常。",
    "fileType": "pdf"
  }'
```

预期返回：
```json
{"success":true,"docId":"test-001","chunkCount":1,"message":"文档入库成功","error":null}
```

#### 3.2 向量搜索

```bash
curl -X POST http://localhost:8084/api/v1/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "测试数据验证",
    "topK": 3
  }'
```

预期返回：
```json
[{"docId":"test-001","chunkId":"test-001_chunk_0","score":0.85,...}]
```

#### 3.3 查询文档

```bash
curl http://localhost:8084/api/v1/documents/test-001
```

#### 3.4 删除文档

```bash
curl -X DELETE http://localhost:8084/api/v1/documents/test-001
```

### 4. 查看 Elasticsearch 数据

```bash
# 查看索引中的文档数量
curl http://localhost:9200/contract_chunks/_count

# 查看所有文档
curl http://localhost:9200/contract_chunks/_search?size=10

# 查看指定文档
curl http://localhost:9200/contract_chunks/_search \
  -H 'Content-Type: application/json' \
  -d '{"query":{"term":{"doc_id":"test-001"}}}'
```

### 5. 查看 MySQL 日志

```bash
# 查看操作日志
mysql -h 127.0.0.1 -P 3306 -uroot -p123456 -e "
SELECT operation_type, doc_id, status, duration_ms, create_time
FROM schedule_embedding.operation_log
ORDER BY create_time DESC LIMIT 5;"
```

### 6. 完整测试脚本

也可以使用项目中的测试脚本：

```bash
# 简单测试
bash test_api.sh

# 完整测试
bash test_complete.sh
```

---

## 项目结构

```
src/main/java/cn/com/yusys/manager/
├── config/           # 配置类
├── controller/       # REST 控制器
├── service/         # 业务服务
├── repository/      # 数据访问层
├── client/          # 外部 API 客户端
├── model/           # 数据模型
│   ├── entity/      # 实体类
│   ├── dto/         # 请求/响应对象
│   └── vo/          # 视图对象
├── listener/        # Kafka 监听器
├── splitter/        # 文本分割器
└── exception/       # 异常处理
```