Vanna-AI 项目中 Ollama 嵌入函数接口适配问题解析

问题背景

在使用 Vanna-AI 项目进行自然语言到 SQL 查询的转换时，开发者遇到了一个关于 Ollama 嵌入函数接口的问题。具体表现为：虽然训练数据已经成功添加，但在 Flask 前端界面中却无法正常显示这些数据。

技术细节分析

问题的根源在于 ChromaDB 的 Ollama 嵌入函数实现与最新 Ollama API 版本不兼容。原代码中的嵌入函数实现存在以下关键问题：

1. API 接口变更：Ollama 服务已经废弃了 /api/embeddings 接口，但代码中仍然使用这个旧接口路径
2. 响应解析错误：新版本 API 的响应格式与代码中的解析逻辑不匹配
3. 类型转换问题：返回的嵌入向量格式与 ChromaDB 期望的格式不一致

解决方案实现

针对上述问题，开发者提供了修正方案，主要修改了 __call__ 方法的实现：

def __call__(self, input: Union[Documents, str]) -> Embeddings:
    texts = input if isinstance(input, list) else [input]
    embeddings = [
        self._session.post(
            self._api_url, json={"model": self._model_name, "input": text}
        ).json()
        for text in texts
    ]
    return cast(Embeddings, embeddings[0]['embeddings'])

这个修正方案具有以下改进点：

1. 移除了对废弃接口路径的依赖
2. 直接使用 Ollama 服务返回的 embeddings 字段
3. 简化了类型转换逻辑，确保返回格式符合 ChromaDB 的期望

技术影响评估

这个问题的解决对于 Vanna-AI 项目的正常运行至关重要，因为：

1. 嵌入函数是向量数据库存储和检索的核心组件
2. 训练数据的正确嵌入直接影响后续的 SQL 生成质量
3. 前端展示依赖于后端正确处理和返回的嵌入数据

最佳实践建议

对于使用类似技术的开发者，建议：

1. 定期检查依赖库的 API 变更情况
2. 实现更健壮的错误处理和日志记录
3. 考虑为嵌入函数添加单元测试
4. 在项目文档中明确标注依赖的 API 版本

总结

这个案例展示了开源项目中常见的接口兼容性问题。通过深入分析 API 变更和响应格式，开发者能够快速定位并解决问题，确保了 Vanna-AI 项目的正常运行。这也提醒我们在使用第三方服务时，需要密切关注其 API 的演进和变化。