如何在Chroma Collection中指定Azure Embedding模型？

Question

**问题描述：** 如何在Chroma Collection中正确配置并指定使用Azure OpenAI的Embedding模型（如text-embedding-ada-002）以实现高效的向量嵌入？在使用ChromaDB时，开发者通常会遇到模型集成方式不明确、认证配置错误或API调用不匹配等问题，导致无法成功使用Azure上的Embedding服务。本文将详细介绍如何通过自定义Embedding函数，结合Azure OpenAI的API，实现在Chroma Collection中指定并使用远程Embedding模型的方法，涵盖关键代码示例与常见配置陷阱。

Answer 1

一、背景与问题引入

Chroma 是一个轻量级的开源向量数据库，广泛用于构建基于语义的搜索和推荐系统。其核心功能之一是通过 Embedding 函数将文本转换为向量表示，从而实现高效的向量相似性检索。

然而，许多开发者在尝试将 Azure OpenAI 提供的高质量 Embedding 模型（如 text-embedding-ada-002）集成到 Chroma Collection 时，常常遇到如下问题：

• Chroma 默认使用本地 Embedding 模型（如 Sentence Transformers），无法直接指定远程模型。
• Azure OpenAI 的认证方式（如 API Key 和 Endpoint）配置不当。
• Embedding 函数接口与 Azure OpenAI 的 API 调用不兼容。

二、Chroma 中 Embedding 函数的工作机制

Chroma 支持通过 embedding_function 参数来自定义 Embedding 逻辑。开发者可以实现一个符合 EmbeddingFunction 接口的类，用于将文本转换为向量。

其核心接口如下：

class EmbeddingFunction:
    def __init__(self, ...):
        pass

    def __call__(self, texts: List[str]) -> List[List[float]]:
        pass

该函数接收文本列表，返回对应的向量列表。这为调用远程服务（如 Azure OpenAI）提供了接口基础。

三、Azure OpenAI Embedding 模型的接入准备

在使用 Azure OpenAI 服务之前，开发者需完成以下准备工作：

1. 注册 Azure 账户并创建 AI 服务资源。
2. 在 Azure Portal 中部署 text-embedding-ada-002 模型。
3. 获取 API Key 和 Endpoint URL。
4. 安装必要的 Python 库：openai、chromadb、requests。

四、构建自定义 Embedding 函数

下面是一个基于 Azure OpenAI 的 Embedding 函数实现示例：

import openai
from chromadb.utils import embedding_functions

class AzureOpenAIEmbeddingFunction(embedding_functions.EmbeddingFunction):
    def __init__(self, api_key, endpoint, deployment_name):
        openai.api_key = api_key
        openai.api_base = endpoint
        openai.api_type = 'azure'
        openai.api_version = '2023-05-15'
        self.deployment_name = deployment_name

    def __call__(self, texts):
        response = openai.Embedding.create(
            input=texts,
            engine=self.deployment_name
        )
        return [item['embedding'] for item in response['data']]

# 使用示例
ef = AzureOpenAIEmbeddingFunction(
    api_key='YOUR_API_KEY',
    endpoint='https://your-resource.openai.azure.com/',
    deployment_name='text-embedding-ada-002'
)

五、在 Chroma Collection 中使用自定义 Embedding 函数

一旦构建了自定义 Embedding 函数，就可以在创建 Chroma Collection 时指定它：

import chromadb

client = chromadb.Client()
collection = client.create_collection(
    name="my_collection",
    embedding_function=ef
)

collection.add(
    documents=["这是一个测试句子。", "另一个句子用于测试。"],
    metadatas=[{"source": "test1"}, {"source": "test2"}],
    ids=["id1", "id2"]
)

此时，Chroma 会使用 Azure OpenAI 提供的 Embedding 模型进行向量编码。

六、常见问题与解决方案

问题	可能原因	解决方案
调用 Azure OpenAI API 时返回 401 错误	API Key 配置错误	检查 API Key 是否正确，是否已过期
调用时返回 404 或 400 错误	Endpoint 或 Deployment Name 错误	确认部署名称是否与 Azure 控制台一致
向量维度不一致	模型返回的 Embedding 维度与 Chroma 预期不符	确认模型输出维度是否为 1536（Ada-002）

七、性能优化与注意事项

为了提升性能并避免不必要的资源浪费，开发者应注意以下几点：

• 批量处理文本：尽量一次传入多个文本，减少 API 调用次数。
• 设置请求超时与重试策略：网络不稳定时应加入重试机制。
• 缓存 Embedding 结果：对于重复文本可缓存向量以提高效率。

此外，建议使用 async 异步方式调用 Azure OpenAI API，以提高并发性能。

八、未来展望与扩展思路

随着 Chroma 和 Azure OpenAI 的持续演进，开发者可以进一步探索以下方向：

• 使用 Azure AD 进行更安全的认证。
• 将 Embedding 服务封装为独立的微服务。
• 结合 LangChain 等框架构建完整的 RAG 系统。

通过将远程 Embedding 模型与 Chroma 无缝集成，开发者可以更灵活地构建高质量的语义检索系统。