Azure-Search-OpenAI-Demo项目中向量维度不匹配问题的分析与解决

在Azure-Search-OpenAI-Demo项目中，当使用较新的text-embedding-3-large模型时，开发者可能会遇到向量维度不匹配的问题。本文将深入分析该问题的成因，并提供完整的解决方案。

问题现象

当配置使用text-embedding-3-large模型（支持1536或3072维度）时，索引器运行时会出现错误提示："向量维度不匹配。向量字段'embedding'期望维度为'1536'，但提供的向量长度为'3072'"。

根本原因分析

1. SDK版本过旧：项目默认使用的azure-search-documents SDK版本较旧，其AzureOpenAIEmbeddingSkill类不支持dimensions和model_name参数。

2. 技能集配置缺失：自动生成的技能集配置中缺少必要的modelName和dimensions参数。

3. 向量化器参数不全：AzureOpenAIVectorizer在较新的API版本中需要明确指定model_name参数。

完整解决方案

1. 升级SDK版本

修改requirements.txt文件，将azure-search-documents升级至支持新特性的版本：

azure-search-documents==11.6.0b4

2. 修改技能集配置

在integratedvectorizerstrategy.py中更新AzureOpenAIEmbeddingSkill的初始化代码：

embedding_skill = AzureOpenAIEmbeddingSkill(
    description="Skill to generate embeddings via Azure OpenAI",
    context="/document/pages/*",
    resource_uri=f"https://{self.embeddings.open_ai_service}.openai.azure.com",
    deployment_id=self.embeddings.open_ai_deployment,
    dimensions=int(os.getenv('AZURE_OPENAI_EMB_DIMENSIONS')),
    model_name=os.getenv('AZURE_OPENAI_EMB_MODEL_NAME'),
    inputs=[InputFieldMappingEntry(name="text", source="/document/pages/*")],
    outputs=[OutputFieldMappingEntry(name="embedding", target_name="vector")],
)

3. 更新向量化器配置

在创建索引时，确保AzureOpenAIVectorizer包含model_name参数：

await search_manager.create_index(
    vectorizers=[
        AzureOpenAIVectorizer(
            name=f"{self.search_info.index_name}-vectorizer",
            kind="azureOpenAI",
            azure_open_ai_parameters=AzureOpenAIParameters(
                resource_uri=f"https://{self.embeddings.open_ai_service}.openai.azure.com",
                deployment_id=self.embeddings.open_ai_deployment,
                model_name=os.getenv('AZURE_OPENAI_EMB_MODEL_NAME'),
            ),
        ),
    ]
)

4. 更新API版本

确保SearchIndexerClient使用最新的API版本：

def create_search_indexer_client(self) -> SearchIndexerClient:
    return SearchIndexerClient(
        endpoint=self.endpoint,
        credential=self.credential,
        api_version="2024-05-01-preview"
    )

环境变量配置

确保.env文件中包含以下配置：

AZURE_OPENAI_EMB_DEPLOYMENT="text-embedding-3-large"
AZURE_OPENAI_EMB_DIMENSIONS=1536  # 或3076，根据需求选择
AZURE_OPENAI_EMB_MODEL_NAME="text-embedding-3-large"
USE_FEATURE_INT_VECTORIZATION="true"

验证与测试

完成上述修改后，重新部署应用并运行索引器。可以通过以下方式验证是否生效：

1. 在Azure门户中检查技能集配置，确认modelName和dimensions参数已正确设置
2. 检查索引器运行历史，确认没有维度不匹配的错误
3. 查询索引中的文档，确认向量字段已正确填充

总结

通过升级SDK、完善技能集和向量化器配置，以及正确设置环境变量，可以解决Azure-Search-OpenAI-Demo项目中与新版嵌入模型相关的向量维度问题。这一解决方案不仅适用于text-embedding-3-large模型，也为将来支持其他新模型提供了参考模式。