125 lines
3.7 KiB
Markdown
125 lines
3.7 KiB
Markdown
# 循环匹配功能优化文档
|
||
|
||
## 概述
|
||
|
||
本文档描述了一键匹配功能的循环优化实现，该功能能够循环匹配模板直到失败（无法完整匹配模板 -- 素材不够用）。
|
||
|
||
## 功能特性
|
||
|
||
### 核心改进
|
||
|
||
1. **循环匹配算法**: 不再只执行一轮匹配，而是持续循环直到无法找到足够的素材完成任何模板的完整匹配
|
||
2. **全局素材使用跟踪**: 在整个循环过程中维护全局的已使用素材列表，确保素材不会被重复使用
|
||
3. **智能终止条件**: 当连续一轮中所有模板都无法完整匹配时，自动停止循环
|
||
4. **性能优化**: 包含多项性能优化措施，确保大量模板和素材时的响应速度
|
||
|
||
### 新增数据字段
|
||
|
||
#### BatchMatchingResult
|
||
- `total_rounds`: 总循环轮数
|
||
- `successful_rounds`: 成功匹配的轮数
|
||
- `termination_reason`: 循环终止原因
|
||
- `materials_exhausted`: 是否因素材耗尽而终止
|
||
|
||
#### BatchMatchingItemResult
|
||
- `round_number`: 匹配成功的轮次
|
||
- `attempts_count`: 尝试匹配的次数
|
||
- `failure_reason`: 详细失败原因
|
||
|
||
## 算法流程
|
||
|
||
```
|
||
1. 初始化全局已使用素材集合
|
||
2. 开始循环匹配轮次
|
||
3. 对每个活跃模板绑定：
|
||
- 尝试匹配所有非固定素材片段
|
||
- 如果完全匹配成功：保存结果，更新全局已使用素材
|
||
- 如果匹配失败：记录失败原因
|
||
4. 检查本轮是否有任何成功匹配
|
||
5. 如果本轮无任何成功匹配：终止循环
|
||
6. 否则：继续下一轮
|
||
```
|
||
|
||
## 失败判断逻辑
|
||
|
||
- **模板级失败**: 模板中任何一个非固定片段无法找到可用素材
|
||
- **轮次级失败**: 一轮中所有模板都失败
|
||
- **全局终止**: 连续一轮无任何成功匹配
|
||
|
||
## 性能优化
|
||
|
||
### 1. 日志优化
|
||
- 只在前5轮或每10轮打印详细日志
|
||
- 减少不必要的控制台输出
|
||
|
||
### 2. 预检查优化
|
||
- 每5轮执行一次预检查，判断是否还有模板可以匹配
|
||
- 如果没有任何模板可以匹配，提前终止循环
|
||
|
||
### 3. 最大轮数限制
|
||
- 设置最大轮数限制（100轮），防止无限循环
|
||
- 在达到限制时自动终止
|
||
|
||
## 使用方式
|
||
|
||
### 后端调用
|
||
```rust
|
||
let request = BatchMatchingRequest {
|
||
project_id: "project_id".to_string(),
|
||
overwrite_existing: false,
|
||
result_name_prefix: Some("循环匹配".to_string()),
|
||
};
|
||
|
||
let result = material_matching_service
|
||
.batch_match_all_templates_optimized(request, database)
|
||
.await?;
|
||
```
|
||
|
||
### 前端调用
|
||
```typescript
|
||
const request: BatchMatchingRequest = {
|
||
project_id: project.id,
|
||
overwrite_existing: false,
|
||
result_name_prefix: '循环匹配',
|
||
};
|
||
|
||
const result = await BatchMatchingService.executeBatchMatching(request);
|
||
```
|
||
|
||
## 结果解读
|
||
|
||
### 成功场景
|
||
- `total_rounds > 1`: 执行了多轮匹配
|
||
- `successful_rounds > 0`: 有成功的匹配轮次
|
||
- `materials_exhausted = true`: 素材已被充分利用
|
||
|
||
### 失败场景
|
||
- `total_rounds = 1, successful_matches = 0`: 第一轮就没有任何匹配成功
|
||
- `termination_reason`: 包含具体的失败原因
|
||
|
||
## 测试覆盖
|
||
|
||
### 单元测试
|
||
- 循环终止条件测试
|
||
- 全局素材使用跟踪测试
|
||
- 性能优化逻辑测试
|
||
- 数据结构完整性测试
|
||
|
||
### 集成测试
|
||
- 端到端循环匹配流程测试
|
||
- 大量数据性能测试
|
||
- 边界条件测试
|
||
|
||
## 注意事项
|
||
|
||
1. **素材消耗**: 循环匹配会消耗更多素材，请确保项目有足够的素材
|
||
2. **执行时间**: 循环匹配可能需要更长时间，特别是在素材丰富的项目中
|
||
3. **内存使用**: 全局素材跟踪会增加内存使用，但在合理范围内
|
||
4. **日志监控**: 建议监控日志输出，了解匹配进度和终止原因
|
||
|
||
## 兼容性
|
||
|
||
- 完全向后兼容原有的一键匹配功能
|
||
- 前端界面自动显示新的循环匹配信息
|
||
- 现有的匹配记录和导出功能正常工作
|