four-level-schedule/schedule-embedding-api

schedule-embedding-api

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

快速开始

1. 环境要求

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

2. 启动前配置

2.1 初始化数据库

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

2.2 修改配置

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

# 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. 启动

mvn spring-boot:run

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

---

Kafka 开关说明

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

kafka:
  enabled: false

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

异步模式（生产环境）

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 处理日志 - 记录消息处理过程

示例查询

-- 查看最近的操作日志
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. 验证服务启动

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

预期返回：

{"status":"UP","components":{...}}

2. 验证 Elasticsearch 连接

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

或通过服务健康检查：

curl http://localhost:8084/actuator/health | grep elasticsearch

3. 简单功能测试

3.1 文档入库

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

预期返回：

{"success":true,"docId":"test-001","chunkCount":1,"message":"文档入库成功","error":null}

3.2 向量搜索

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

预期返回：

[{"docId":"test-001","chunkId":"test-001_chunk_0","score":0.85,...}]

3.3 查询文档

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

3.4 删除文档

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

4. 查看 Elasticsearch 数据

# 查看索引中的文档数量
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 日志

# 查看操作日志
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 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/       # 异常处理