墨台 MUOTAI

Appearance

pigx-ai 向量化系统阶段一部署指南 ​

📋 概述 ​

Phase 1 实现了基础的向量化服务框架，包括：

  • ✅ 单文档向量化
  • ✅ 批量文档向量化
  • ✅ 数据集向量化
  • ✅ 向量删除管理
  • ✅ 任务状态追踪
  • ✅ 索引管理
  • ✅ 监控指标

🚀 部署步骤 ​

1. 数据库初始化 ​

bash
# 连接到MySQL数据库
mysql -u root -p

# 执行建表SQL
SOURCE /path/to/pigx-ai/db/vectorization_phase1.sql;

# 验证表创建
SHOW TABLES LIKE 'kb_%';
DESC kb_vectorization_task;

2. Maven编译 ​

bash
cd muotai-backend/pigx-ai
mvn clean compile

3. 启动服务 ​

bash
# 启动pigx-ai服务
mvn spring-boot:run

# 或使用IDE启动 PigxAiApplication

4. 验证部署 ​

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

# 查看Swagger文档
open http://localhost:6060/swagger-ui.html

📖 接口使用示例 ​

1. 向量化单个文档 ​

bash
curl -X POST http://localhost:6060/ai/vectorization/document/1 \
  -H "Content-Type: application/json"

响应示例：

json
{
  "code": 0,
  "msg": "success",
  "data": {
    "taskId": "550e8400-e29b-41d4-a716-446655440000",
    "documentId": 1,
    "success": true,
    "totalChunks": 45,
    "successChunks": 45,
    "failedChunks": 0,
    "durationMs": 2350
  }
}

2. 批量向量化文档 ​

bash
curl -X POST http://localhost:6060/ai/vectorization/batch \
  -H "Content-Type: application/json" \
  -d '{
    "documentIds": [1, 2, 3, 4, 5]
  }'

响应示例：

json
{
  "code": 0,
  "msg": "success",
  "data": {
    "id": 1001,
    "taskId": "660e8400-e29b-41d4-a716-446655440001",
    "name": "批量向量化-5个文档",
    "taskType": "FULL",
    "status": "RUNNING",
    "totalDocuments": 5,
    "processedDocuments": 2,
    "progress": 40.0
  }
}

3. 向量化整个数据集 ​

bash
curl -X POST http://localhost:6060/ai/vectorization/dataset/1

4. 查询任务状态 ​

bash
curl http://localhost:6060/ai/vectorization/task/660e8400-e29b-41d4-a716-446655440001

响应示例：

json
{
  "code": 0,
  "data": {
    "taskId": "660e8400-e29b-41d4-a716-446655440001",
    "status": "SUCCESS",
    "totalDocuments": 5,
    "processedDocuments": 5,
    "failedDocuments": 0,
    "totalChunks": 234,
    "processedChunks": 234,
    "progress": 100.0,
    "durationMs": 8750,
    "completedAt": "2025-12-10T15:30:45"
  }
}

5. 分页查询任务列表 ​

bash
curl "http://localhost:6060/ai/vectorization/tasks?datasetId=1&status=SUCCESS&page=1&size=10"

6. 获取数据集指标 ​

bash
curl http://localhost:6060/ai/vectorization/metrics/dataset/1

响应示例：

json
{
  "code": 0,
  "data": {
    "totalVectorized": 50,
    "totalDocuments": 50,
    "totalChunks": 2345,
    "successCount": 48,
    "failureCount": 2,
    "avgProcessTime": 2150.5
  }
}

7. 删除文档向量 ​

bash
curl -X DELETE http://localhost:6060/ai/vectorization/document/1

8. 重建数据集索引 ​

bash
curl -X POST http://localhost:6060/ai/vectorization/index/rebuild?datasetId=1

🔧 配置说明 ​

1. 默认配置 ​

java
VectorizationConfig config = VectorizationConfig.builder()
    .embeddingModel("text-embedding-ada-002")
    .chunkSize(512)
    .chunkOverlap(50)
    .batchSize(10)
    .maxConcurrency(5)
    .enableQualityCheck(true)
    .build();

2. 从数据集继承配置 ​

系统会自动从 KbDatasetEntity 继承以下配置：

  • embeddingModel
  • chunkMaxTokenSize → chunkSize
  • chunkOverlapTokenSize → chunkOverlap
  • deleteSensitiveInfo
  • deleteSpaces

3. 自定义配置 ​

bash
curl -X POST http://localhost:6060/ai/vectorization/document/1/custom \
  -H "Content-Type: application/json" \
  -d '{
    "embeddingModel": "text-embedding-3-large",
    "chunkSize": 1024,
    "chunkOverlap": 100,
    "batchSize": 20,
    "enableQualityCheck": true,
    "qualityThreshold": 0.7
  }'

🔍 服务集成 ​

在代码中使用 ​

java
@Service
public class MyService {

    @Autowired
    private VectorizationService vectorizationService;

    public void processDocument(Long documentId) {
        // 使用默认配置向量化
        VectorizationResult result = vectorizationService.vectorizeDocument(documentId);

        if (result.getSuccess()) {
            log.info("向量化成功: {} chunks", result.getTotalChunks());
        }
    }

    public void processDataset(Long datasetId) {
        // 批量向量化数据集
        VectorizationTaskEntity task = vectorizationService.vectorizeDataset(datasetId);

        // 轮询任务状态
        while (!task.isCompleted()) {
            Thread.sleep(1000);
            task = vectorizationService.getTaskStatus(task.getTaskId());
            log.info("进度: {}%", task.getProgress());
        }
    }
}

集成到现有KbDocumentService ​

系统已自动集成到 KbDocumentService.processDocument() 方法中，无需额外配置。

📊 数据模型说明 ​

VectorizationTaskEntity（任务实体） ​

字段类型说明
taskIdString任务ID（UUID）
taskTypeTaskType任务类型（FULL/INCREMENTAL/REBUILD/SINGLE_DOC）
statusTaskStatus状态（PENDING/RUNNING/SUCCESS/FAILED/CANCELLED）
totalDocumentsInteger总文档数
processedDocumentsInteger已处理数
totalChunksInteger总分段数
durationMsLong耗时（毫秒）
errorMessageString错误信息

任务状态枚举 ​

  • PENDING: 待处理
  • RUNNING: 运行中
  • SUCCESS: 成功
  • FAILED: 失败
  • CANCELLED: 已取消

任务类型枚举 ​

  • FULL: 全量向量化
  • INCREMENTAL: 增量更新（Phase 2实现）
  • REBUILD: 重建索引
  • SINGLE_DOC: 单文档处理

⚠️ 注意事项 ​

1. Milvus集合更新 ​

如果需要使用KbChunkEntity的新增字段（chunkIndex、qualityScore等），需要重建Milvus集合：

java
// 1. 备份现有数据
// 2. 删除集合
milvusClient.dropCollection("npu");

// 3. 重新创建集合（会自动包含新字段）
kbMilvusEmbeddingStore.createCollection();

// 4. 重新向量化数据
vectorizationService.vectorizeDataset(datasetId);

2. 性能优化 ​

  • 默认批处理大小为10，可根据API限制调整
  • 建议大批量处理时使用异步模式（Phase 2实现）
  • 监控Milvus内存使用，及时优化索引

3. 错误处理 ​

  • 任务失败时会记录详细错误信息
  • 可通过 getTaskStatus() 查看失败原因
  • 支持失败任务重试：retryTask(taskId)

📈 监控指标 ​

查看系统整体指标 ​

bash
curl http://localhost:6060/ai/vectorization/metrics/system

指标说明 ​

指标说明
totalVectorized成功向量化的文档数
totalChunks总分段数
successCount成功任务数
failureCount失败任务数
avgProcessTime平均处理时间（毫秒）

🐛 故障排查 ​

1. 文档向量化失败 ​

bash
# 检查文档是否存在
curl http://localhost:6060/ai/document/1

# 检查MinIO文件路径
# 查看错误堆栈
curl http://localhost:6060/ai/vectorization/task/{taskId}

2. Milvus连接失败 ​

bash
# 检查Milvus服务状态
docker ps | grep milvus

# 检查连接配置
# application.yml中的milvus配置

3. 内存溢出 ​

bash
# 减小批处理大小
# 调整JVM参数：-Xmx4g -Xms2g

🔄 下一步：阶段二 ​

Phase 2 将实现：

  • ✨ 异步任务调度
  • ✨ 批量任务队列
  • ✨ 进度实时推送（SSE）
  • ✨ 任务优先级
  • ✨ 失败自动重试

📞 技术支持 ​

如有问题，请联系开发团队或提交Issue。

最后更新: 2025-12-10 版本: Phase 1 (v1.0.0)