SigCLIP embedding model compatibility issues with HippoRAG

[WS-200099]

问题描述

在集成 SigCLIP 作为 HippoRAG 的嵌入模型时，发现几个关键的兼容性问题需要解决：

1. 批处理逻辑问题

问题: 在 batch_encode 方法中，预先为所有项目创建了 None 占位符，但处理顺序可能导致索引错误。

位置: batch_encode 方法第 125-135 行

# 当前的有问题的逻辑
for item in inputs:
    # ... 缓存检查 ...
    if self._is_image_path(item):
        image_items.append((len(embeddings), item))  # 这里的索引可能不正确
        item_types.append('image')
    # ...
    embeddings.append(None)  # 预填充 None

建议修复:

def batch_encode(self, inputs: List[str], **kwargs) -> List[np.ndarray]:
    embeddings = [None] * len(inputs)  # 预分配正确大小
    text_items = []
    image_items = []
    
    for idx, item in enumerate(inputs):
        cache_key = self._get_cache_key(item)
        if cache_key in self._embedding_cache:
            embeddings[idx] = self._embedding_cache[cache_key]
        elif self._is_image_path(item):
            image_items.append((idx, item))
        else:
            text_items.append((idx, item))

2. 图像批处理中的索引混乱

问题: _batch_encode_images 方法中的索引逻辑过于复杂，容易出错。

位置: _batch_encode_images 方法第 200-220 行

# 当前复杂的索引逻辑
valid_idx = 0
for j in range(len(batch_paths)):
    if i + j in valid_indices:
        if len(embeddings) > i + j and np.array_equal(embeddings[i + j], np.zeros(self.embedding_dim)):
            embeddings[i + j] = batch_embeddings[valid_idx]
        else:
            embeddings.append(batch_embeddings[valid_idx])
        valid_idx += 1

3. 错误处理不一致

问题: 图像加载失败时使用零向量，但文本编码失败时没有类似处理。

位置: _batch_encode_images 方法第 185 行 和 encode_image 方法第 260 行

4. 设备管理可能的问题

问题: CUDA 可用性检查分散在多个地方，可能导致设备不一致。

建议: 在 __init__ 中统一设置设备属性：

def __init__(self, global_config=None, embedding_model_name: Optional[str] = None):
    # ... 现有代码 ...
    self.device = 'cuda' if torch.cuda.is_available() else 'cpu'
    self.model = self.model.to(self.device)

5. 类型注解和返回值一致性

问题: encode_multimodal 方法的返回类型注解使用了新式语法，可能不兼容旧版 Python。

位置: 第 298 行

def encode_multimodal(self, texts: List[str], images: List[Union[str, Image.Image]]) -> tuple[List[np.ndarray], List[np.ndarray]]:

建议修复:

def encode_multimodal(self, texts: List[str], images: List[Union[str, Image.Image]]) -> Tuple[List[np.ndarray], List[np.ndarray]]:

验证建议

1. 单元测试: 为每个编码方法添加单元测试
2. 批处理测试: 测试混合文本和图像的批处理
3. 错误处理测试: 测试无效图像路径和编码失败的情况
4. 性能测试: 验证缓存机制的有效性

优先级

• 🔴 高优先级: 批处理索引问题（可能导致运行时错误）
• 🟡 中优先级: 错误处理一致性、设备管理
• 🟢 低优先级: 类型注解、代码优化