使用azure-search-documents 11.4.0遇属性错误，需回退版本或LangChain吗？

问题描述 #

当前使用azure-search-documents==11.4.0，初始化LangChain的AzureSearch向量存储时触发错误：

The vector field 'content_vector' must have the property 'vectorSearchConfiguration' set.

同时伴随属性忽略警告：

vector_search_configuration is not a known attribute of class <class 'azure.search.documents.indexes.models._index.SearchField'> and will be ignored
semantic_settings is not a known attribute of class <class 'azure.search.documents.indexes.models._index.SearchIndex'> and will be ignored

疑问：是否需要回退到预发布版11.4.0b8，同时回退LangChain至更早版本？

解决方案 #

不需要回退版本。问题根源是正式版azure-search-documents>=11.4.0对向量搜索的配置逻辑做了调整，不再支持旧版的隐式配置，需要显式传入向量搜索相关参数。

代码修正示例 #

修改AzureSearch初始化代码，添加向量搜索配置参数：

from azure.search.documents.indexes.models import (
    VectorSearch,
    VectorSearchAlgorithmConfiguration,
    SearchField,
    SearchFieldDataType,
    SimpleField
)

# 定义向量搜索算法配置
vector_search = VectorSearch(
    algorithm_configurations=[
        VectorSearchAlgorithmConfiguration(
            name="my-vector-config",
            kind="hnsw",
            parameters={
                "m": 4,
                "efConstruction": 400,
                "efSearch": 500,
                "metric": "cosine"
            }
        )
    ]
)

# 自定义字段（若需覆盖默认字段）
fields = [
    SimpleField(name="id", type=SearchFieldDataType.String, key=True),
    SearchField(name="content", type=SearchFieldDataType.String, searchable=True),
    SearchField(
        name="content_vector",
        type=SearchFieldDataType.Collection(SearchFieldDataType.Single),
        vector_search_configuration="my-vector-config"  # 关联向量配置
    ),
    SimpleField(name="metadata", type=SearchFieldDataType.String, filterable=True)
]

vector_store = AzureSearch(
    azure_search_endpoint=os.getenv('AZURE_OPENAI_ENDPOINT'),
    azure_search_key=os.getenv('AZURE_OPENAI_API_KEY'),
    index_name=AISEARCH_INDEX_NAME,
    embedding_function=embeddings.embed_query,
    vector_search=vector_search,  # 传入向量搜索配置
    fields=fields  # 自定义字段（使用默认字段可省略，但需确保向量配置已传入）
)

关键说明 #

1. 向量配置关联：必须显式创建VectorSearch对象定义算法规则，并在content_vector字段中通过vector_search_configuration关联配置名称。
2. 默认字段兼容：若不自定义字段，LangChain会自动生成默认字段，但仍需传入vector_search参数，确保向量字段能关联到配置。
3. 语义设置调整：若需使用语义搜索，新版需通过semantic_settings参数传入标准SemanticSettings对象，旧版的简化配置逻辑已被移除。

为什么不用回退版本 #

正式版11.4.0的API设计更规范，预发布版的隐式配置逻辑已被废弃。回退到预发布版虽能临时解决问题，但会错过正式版的bug修复和功能更新。按照新版API要求显式配置参数，即可正常使用所有功能。

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