feat(match): add image-to-image matching API with L2 distance metric

Author: Sky-Runner-Z

spx-algorithm/README.md

@@ -13,7 +13,8 @@
 
 ## 主要特性
 
-- ✅ **智能图像搜索**：基于语义理解的图像检索
+- ✅ **智能图像搜索**：基于语义理解的文本搜索图片
+- ✅ **图像相似度匹配**：基于视觉特征的图片匹配图片
 - ✅ **资源管理**：统一的资源添加、查询、删除接口
 - ✅ **SVG 图片支持**：专门优化的 SVG 图片处理流程
 - ✅ **批量操作**：支持批量添加和处理资源
@@ -168,7 +169,7 @@ Content-Type: application/json
 }
 ```
 
-#### 搜索资源
+#### 搜索资源（文本搜索图片）
 ```http
 POST /v1/resource/search
 Content-Type: application/json
@@ -180,6 +181,18 @@ Content-Type: application/json
 }
 ```
 
+#### 匹配资源（图片匹配图片）
+```http
+POST /v1/resource/match
+Content-Type: application/json
+
+{
+  "svg_content": "<svg><circle cx=\"50\" cy=\"50\" r=\"40\" fill=\"red\" /></svg>",
+  "top_k": 10,
+  "threshold": 1.0
+}
+```
+
 ### 用户反馈和模型训练
 
 #### 提交用户反馈
@@ -394,7 +407,8 @@ gunicorn -w 4 -b 0.0.0.0:5000 \
 ### 对外接口（`/v1/resource/`）
 - **添加资源**：`POST /v1/resource/add` - 添加单个资源
 - **批量添加**：`POST /v1/resource/batch` - 批量添加资源
-- **搜索资源**：`POST /v1/resource/search` - 基于语义的资源搜索
+- **搜索资源**：`POST /v1/resource/search` - 基于语义的文本搜索图片
+- **匹配资源**：`POST /v1/resource/match` - 基于视觉相似度的图片匹配图片
 
 ### 内部接口（`/v1/internal/`）
 - **系统调试**：向量数据查看、详细搜索调试
@@ -408,8 +422,9 @@ gunicorn -w 4 -b 0.0.0.0:5000 \
 
 ### 设计原则
 - **统一性**：所有资源相关操作都在 `/v1/resource/` 下，避免接口分散
-- **简洁性**：对外只暴露核心的添加和搜索功能，隐藏复杂的管理操作
+- **简洁性**：对外只暴露核心的添加、搜索和匹配功能，隐藏复杂的管理操作
 - **职责分离**：业务功能与调试维护功能严格分离
+- **算法多样性**：支持文本搜索（语义匹配）和图片匹配（视觉相似度）两种不同的检索模式
 - **用户驱动**：通过用户反馈持续优化搜索体验
 
 ## 故障排除

spx-algorithm/api/routes/resource_routes.py

@@ -240,3 +240,70 @@ def search_resources(data: dict):
             'details': str(e)
         }), 500
 
+
+@resource_bp.route('/match', methods=['POST'])
+@validate_json_request(['svg_content'], {
+    'svg_content': lambda x: isinstance(x, str) and len(x.strip()) > 0,
+    'top_k': lambda x: isinstance(x, int) and x > 0,
+    'threshold': lambda x: isinstance(x, (int, float)) and x >= 0  # 距离阈值无上限
+})
+@ensure_coordinator_initialized
+def match_resources(data: dict):
+    """
+    图片匹配图片（基于向量距离）
+    
+    接受JSON数据：
+    {
+        "svg_content": "<svg>...</svg>",  // 输入的SVG图片内容
+        "top_k": 10,  // 可选，返回结果数量，默认10
+        "threshold": 0.0  // 可选，最大距离阈值，默认0.0（距离越小越相似）
+    }
+    
+    注意：与文本搜索不同，此接口使用L2距离度量图片相似度
+    - threshold表示最大允许距离（0表示不过滤）
+    - 返回结果按距离排序，距离越小表示越相似
+    """
+    try:
+        svg_content = data['svg_content'].strip()
+        top_k = data.get('top_k', 10)
+        threshold = data.get('threshold', 0.0)
+        
+        logger.info(f"收到图片匹配请求: top_k={top_k}, threshold={threshold}, svg_length={len(svg_content)}")
+        
+        # 执行图片匹配
+        result = coordinator.match_by_image(
+            svg_content=svg_content,
+            top_k=top_k,
+            threshold=threshold
+        )
+        
+        if result['success']:
+            return jsonify({
+                'success': True,
+                'top_k': top_k,
+                'threshold': threshold,
+                'results_count': result['results_count'],
+                'results': result['results']
+            })
+        else:
+            return jsonify({
+                'success': False,
+                'error': result.get('error', '图片匹配失败'),
+                'code': 'MATCH_FAILED'
+            }), 500
+    
+    except ValueError as e:
+        logger.error(f"图片匹配参数异常: {e}")
+        return jsonify({
+            'error': str(e),
+            'code': 'INVALID_PARAMETER'
+        }), 400
+    
+    except Exception as e:
+        logger.error(f"图片匹配系统异常: {e}")
+        return jsonify({
+            'error': '内部服务器错误',
+            'code': 'INTERNAL_ERROR',
+            'details': str(e)
+        }), 500
+

spx-algorithm/app.py

@@ -61,6 +61,7 @@ def index():
                 "add_resource": "/v1/resource/add (POST)",
                 "batch_add_resources": "/v1/resource/batch (POST)",
                 "search_resources": "/v1/resource/search (POST)",
+                "match_resources": "/v1/resource/match (POST)",
                 "submit_feedback": "/v1/feedback/submit (POST)",
                 "train_ltr_model": "/v1/feedback/train (POST)",
                 "internal_debug": "/v1/internal/* (仅用于调试和管理)"

spx-algorithm/coordinator/search_coordinator.py

@@ -321,6 +321,63 @@ def get_rerank_service(self) -> RerankService:
         """获取重排序服务实例（用于API层调用）"""
         return self.rerank_service
 
+    def match_by_image(self, svg_content: str, 
+                       top_k: int = 10, 
+                       threshold: float = 0.0,
+                       **kwargs) -> Dict[str, Any]:
+        """
+        执行图片匹配图片：使用SVG内容匹配相似图片（基于L2距离）
+        
+        Args:
+            svg_content: 输入的SVG图片内容
+            top_k: 返回结果数量
+            threshold: 最大距离阈值（距离越小越相似，0表示不过滤）
+            **kwargs: 其他参数
+            
+        Returns:
+            匹配结果（包含distance和similarity字段）
+        """
+        try:
+            logger.info(f"开始图片匹配流程: top_k={top_k}, threshold={threshold}")
+            
+            # 通过图文匹配服务执行图片匹配（跳过重排序）
+            matching_results = self.image_matching_service.search_by_image(
+                svg_content, top_k, threshold
+            )
+            
+            if not matching_results:
+                logger.info("图片匹配没有返回结果")
+                return {
+                    'success': True,
+                    'top_k': top_k,
+                    'threshold': threshold,
+                    'results_count': 0,
+                    'results': [],
+                    'pipeline_stages': ['image_matching']
+                }
+            
+            logger.info(f"图片匹配完成，返回 {len(matching_results)} 个结果")
+            
+            return {
+                'success': True,
+                'top_k': top_k,
+                'threshold': threshold,
+                'results_count': len(matching_results),
+                'results': matching_results,
+                'pipeline_stages': ['image_matching']
+            }
+            
+        except Exception as e:
+            logger.error(f"图片匹配流程异常: {e}")
+            return {
+                'success': False,
+                'error': str(e),
+                'top_k': top_k,
+                'threshold': threshold,
+                'results_count': 0,
+                'results': []
+            }
+
     def health_check(self) -> Dict[str, Any]:
         """健康检查"""
         if not self.image_matching_service:

spx-algorithm/database/resource_vector/operations.py

@@ -252,6 +252,57 @@ def search_by_vector(self, query_vector: List[float], limit: int = 10) -> List[D
             logger.error(f"向量搜索失败: {e}")
             return []
 
+    def search_by_vector_distance(self, query_vector: List[float], limit: int = 10) -> List[Dict[str, Any]]:
+        """
+        通过向量距离搜索相似数据（用于图片匹配图片）
+        
+        Args:
+            query_vector: 查询向量
+            limit: 返回结果数量
+            
+        Returns:
+            搜索结果列表，按距离排序（距离越小越相似）
+        """
+        try:
+            # 使用L2距离进行图片相似度计算
+            search_params = {
+                "metric_type": "L2",  # 使用欧氏距离而不是余弦相似度
+                "params": {"nprobe": 10}  # 可以根据需要调整
+            }
+            
+            search_result = self.collection.search(
+                data=[query_vector],
+                anns_field="vector",
+                param=search_params,
+                limit=limit,
+                output_fields=["id", "url", "added_at", "updated_at"]
+            )
+            
+            results = []
+            for i, hit in enumerate(search_result[0]):
+                result = {
+                    'rank': i + 1,
+                    'distance': float(hit.score),  # L2距离，越小越相似
+                    'similarity': 1.0 / (1.0 + float(hit.score)),  # 转换为相似度分数
+                    'id': hit.entity.get('id'),
+                    'url': hit.entity.get('url'),
+                    'added_at': hit.entity.get('added_at')
+                }
+                
+                # 添加更新时间（如果存在且不同于添加时间）
+                updated_at = hit.entity.get('updated_at')
+                if updated_at and updated_at != result['added_at']:
+                    result['updated_at'] = updated_at
+                
+                results.append(result)
+            
+            logger.info(f"向量距离搜索完成，返回 {len(results)} 个结果")
+            return results
+            
+        except Exception as e:
+            logger.error(f"向量距离搜索失败: {e}")
+            return []
+    
     def get_all_data(self, include_vectors: bool = False, limit: Optional[int] = None, 
                     offset: int = 0) -> List[Dict[str, Any]]:
         """

spx-algorithm/services/image_matching/matching_service.py

@@ -235,6 +235,52 @@ def search_by_text(self, query_text: str, top_k: int = 10,
             logger.error(f"文本搜索异常: {e}")
             return []
 
+    def search_by_image(self, svg_content: str, top_k: int = 10, 
+                       threshold: float = 0.0) -> List[Dict[str, Any]]:
+        """
+        基于图片内容搜索相似图片
+        
+        Args:
+            svg_content: SVG图片内容
+            top_k: 返回结果数量
+            threshold: 相似度阈值
+            
+        Returns:
+            搜索结果列表
+        """
+        try:
+            if not svg_content.strip():
+                logger.error("SVG内容不能为空")
+                return []
+            
+            logger.info(f"开始图片搜索: top_k={top_k}, threshold={threshold}, svg_length={len(svg_content)}")
+            
+            # 向量化SVG图片内容
+            query_vector = self.vector_service.vectorize_image_from_svg_content(svg_content)
+            if query_vector is None:
+                logger.error("SVG图片向量化失败")
+                return []
+            
+            # 在向量数据库中搜索（使用距离度量）
+            search_results = self.milvus_ops.search_by_vector_distance(
+                query_vector.tolist(), 
+                limit=top_k
+            )
+            
+            # 应用距离阈值过滤（注意：距离越小越相似，所以是小于等于阈值）
+            if threshold > 0:
+                before_count = len(search_results)
+                # 对于距离度量，threshold表示最大允许距离
+                search_results = [r for r in search_results if r['distance'] <= threshold]
+                logger.info(f"距离阈值过滤: {before_count} -> {len(search_results)} 个结果（最大距离: {threshold}）")
+            
+            logger.info(f"图片搜索完成: 找到 {len(search_results)} 个结果")
+            return search_results
+            
+        except Exception as e:
+            logger.error(f"图片搜索异常: {e}")
+            return []
+    
     def delete_image(self, id: int) -> bool:
         """
         删除图片