使用azure-search-documents v11.4.0创建Azure AI Search向量索引报错求助

问题核心 #

azure-search-documents v11.4.0版本对向量索引的配置结构做了更新，旧版示例中的参数名和配置层级已失效，导致出现vectorSearchConfiguration未设置或UnknownVectorAlgorithmConfiguration错误。

修正后的完整代码 #

from azure.core.credentials import AzureKeyCredential  
from azure.search.documents.indexes import SearchIndexClient  
from azure.search.documents.indexes.models import (  
    SearchIndex,  
    SearchField,  
    SearchFieldDataType,  
    SimpleField,  
    SearchableField,  
    VectorSearch,
    HnswAlgorithmConfiguration,
    VectorSearchProfile
)  

index_name = AZURE_COGNITIVE_SEARCH_INDEX_NAME 
key = AZURE_COGNITIVE_SEARCH_KEY
service_endpoint = AZURE_COGNITIVE_SEARCH_ENDPOINT  # 补充缺失的服务端点变量
credential = AzureKeyCredential(key)


def create_index(): 
    # 初始化索引客户端
    client = SearchIndexClient(service_endpoint, credential)
    
    # 定义索引字段
    fields = [
        SimpleField(name="chunk_id", type=SearchFieldDataType.String, key=True, sortable=True, filterable=True, facetable=True),
        SimpleField(name="file_name", type=SearchFieldDataType.String),
        SimpleField(name="url_name", type=SearchFieldDataType.String),
        SimpleField(name="origin", type=SearchFieldDataType.String, sortable=True, filterable=True, facetable=True),
        SearchableField(name="content", type=SearchFieldDataType.String),
        # 关键：使用vector_search_profile_name替代旧的vector_search_configuration
        SearchField(name="content_vector", type=SearchFieldDataType.Collection(SearchFieldDataType.Single),
                    searchable=True, vector_search_dimensions=1536, vector_search_profile_name="my-vector-profile"),
    ]
    
    # 配置向量搜索：先定义算法，再通过profile关联
    vector_search = VectorSearch(
        algorithms=[
            HnswAlgorithmConfiguration(
                name="my-hnsw-algorithm",
                kind="hnsw",
                parameters={
                    "m": 4,
                    "efConstruction": 400,
                    "efSearch": 500,
                    "metric": "cosine"
                }
            )
        ],
        profiles=[
            VectorSearchProfile(
                name="my-vector-profile",
                algorithm_configuration_name="my-hnsw-algorithm"
            )
        ]
    )

    # 创建索引
    index = SearchIndex(name=index_name, fields=fields, vector_search=vector_search)
    return client, index

# 执行索引创建
search_client, search_index = create_index()
result = search_client.create_or_update_index(search_index)  
print(f"{result.name} created") 

关键变化说明 #

• 字段参数更新：SearchField中向量字段关联配置的参数从vector_search_configuration改为vector_search_profile_name，需与VectorSearch中定义的profile名称一致。
• 向量搜索结构调整：v11.4.0要求VectorSearch必须包含profiles（配置文件）和algorithms（算法配置）两个层级：
  1. 先定义具体的算法配置（如HnswAlgorithmConfiguration）
  2. 再创建VectorSearchProfile，将算法配置与profile名称绑定
  3. 最后在向量字段中通过vector_search_profile_name关联对应的profile

错误原因解析 #

1. 初始代码中使用了旧参数vector_search_configuration，与v11.4.0的vector_search_profile_name不匹配，导致系统提示未设置配置。
2. 部分示例代码未正确配置VectorSearch的profiles层级，仅定义了algorithms，导致字段关联的配置找不到，触发UnknownVectorAlgorithmConfiguration错误。

内容的提问来源于stack exchange，提问作者Daniel