
LlamaIndex Azure CosmosDB MongoDB vCore 向量存储集成实战AzureCosmosDBMongoDBVectorSearch 完全指南【免费下载链接】llama_indexLlamaIndex is the leading document agent and OCR platform项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index本篇技术指南围绕 LlamaIndex 官方集成包llama-index-vector-stores-azurecosmosmongo的核心类AzureCosmosDBMongoDBVectorSearch展开系统讲解如何将 Azure CosmosDB MongoDB vCore 集群作为 LlamaIndex 的向量存储后端覆盖安装配置、连接初始化、三类向量索引IVF / HNSW / DiskANN的创建参数、节点写入与删除、聚合管道查询以及测试验证。读完本文你将掌握在 LlamaIndex 应用中以 Azure CosmosDB MongoDB vCore 实现端到端向量检索的完整方案。集成概述为什么选择 CosmosDB MongoDB vCore 作为向量存储Azure CosmosDB MongoDB vCore 是微软 Azure 提供的完全托管的 MongoDB 兼容数据库服务内置原生的cosmosSearch向量检索能力。在 LlamaIndex 生态中AzureCosmosDBMongoDBVectorSearch通过实现核心层定义的BasePydanticVectorStore抽象接口见 llama-index-core/llama_index/core/vector_stores/types.py把 CosmosDB 的向量索引与检索能力无缝接入 LlamaIndex 的索引、检索、查询链路使文档可以直接写入 MongoDB 集合并通过$search聚合管道执行近似最近邻ANN检索。本集成包在仓库中的完整位置为 llama-index-integrations/vector_stores/llama-index-vector-stores-azurecosmosmongo其公开 API 参考页面即 azurecosmosmongo.md页面指向的唯一核心成员就是AzureCosmosDBMongoDBVectorSearch。安装与依赖集成包的 pyproject.toml 声明了运行时依赖pymongo4.6.1,5MongoDB 官方 Python 驱动负责与 CosmosDB 集群建立连接llama-index-core0.13.0,0.15LlamaIndex 核心库提供BaseNode、VectorStoreQuery、VectorStoreQueryResult等基础类型运行环境要求Python 3.10,4.0。安装命令pip install llama-index-vector-stores-azurecosmosmongo安装后即可从llama_index.vector_stores.azurecosmosmongo导入核心类导出定义见init.pyfrom llama_index.vector_stores.azurecosmosmongo import AzureCosmosDBMongoDBVectorSearch连接与初始化两种凭据传入方式类的构造函数定义在 base.py支持两种方式提供连接凭据方式一显式传入pymongo.MongoClientimport pymongo from llama_index.vector_stores.azurecosmosmongo import AzureCosmosDBMongoDBVectorSearch # Set up the connection string with your Azure CosmosDB MongoDB URI connection_string YOUR_AZURE_COSMOSDB_MONGODB_URI mongodb_client pymongo.MongoClient(connection_string) # Create an instance of AzureCosmosDBMongoDBVectorSearch vector_store AzureCosmosDBMongoDBVectorSearch( mongodb_clientmongodb_client, db_namedemo_vectordb, collection_namepaul_graham_essay, )方式二依赖环境变量不传mongodb_client时构造逻辑会读取环境变量AZURE_COSMOSDB_MONGODB_URI若该变量也不存在则抛出ValueError。从源码看通过环境变量创建客户端时会额外附加appnameLLAMAINDEX_PYTHON便于在 CosmosDB 侧识别来自 LlamaIndex 的连接vector_store AzureCosmosDBMongoDBVectorSearch( db_namedemo_vectordb, collection_namepaul_graham_essay, )注意无论采用哪种方式实例化时都会立即执行_create_vector_search_index()即自动在集合上创建向量索引因此请确保连接串对应的账号具备建索引权限。构造参数详解构造函数参数及默认值如下表所示默认值均取自 base.py参数默认值说明mongodb_clientNonepymongo.MongoClient实例为空时回退到AZURE_COSMOSDB_MONGODB_URI环境变量db_namedefault_dbCosmosDB 数据库名称collection_namedefault_collection集合名称index_namedefault_vector_search_index向量搜索索引名称id_keyid文档中用作节点 ID 的字段名embedding_keycontent_vector文档中存放向量的字段名text_keytext文档中存放文本内容的字段名metadata_keymetadata文档中存放元数据的字段名cosmos_search_kwargsNone等价{}索引与检索选项字典详见下文insert_kwargsNone等价{}调用insert_many时透传给 PyMongo 的额外关键字参数其中cosmos_search_kwargs是关键配置入口同时影响索引创建kind、numLists、similarity、dimensions等与查询行为kind决定走哪条聚合管道。类还声明了两个实例级属性stores_text: bool True表示该存储保存原始文本与flat_metadata: bool True表示以扁平结构存储元数据后者会在写入节点时影响元数据的序列化方式。向量索引创建三类 ANN 算法与完整参数表初始化时构造函数会调用 _create_vector_search_index根据cosmos_search_kwargs[kind]的值分发到三个不同的索引构建函数并通过db.command(...)下发createIndexes命令。默认kind为vector-hnsw支持以下三种取值1.vector-ivf倒排文件索引对应 _get_vector_index_ivf参数与默认值参数默认值说明kindvector-ivf索引类型numLists1聚类簇数量数据量大时应调大以获得更好召回similarityCOS相似度度量如余弦相似度dimensions1536向量维度需与嵌入模型输出维度一致compression不设置设为half时启用半精度压缩写入cosmosSearchOptions.compression2.vector-hnsw分层可导航小世界图默认对应 _get_vector_index_hnsw参数与默认值参数默认值说明kindvector-hnsw索引类型m2每个节点的最大连接数越大召回越好但内存占用越高efConstruction64建图时的动态列表长度越大建图质量越高similarityCOS相似度度量dimensions1536向量维度compression不设置设为half时启用半精度压缩3.vector-diskann磁盘优先的 ANN 索引对应 _get_vector_index_diskann参数与默认值参数默认值说明kindvector-diskann索引类型maxDegree32图中节点的最大度数lBuild50建图候选列表长度similarityCOS相似度度量dimensions1536向量维度compression不设置设为pq时启用乘积量化压缩并额外读取pqCompressedDims默认与dimensions相同与pqSampleSize默认1000典型初始化示例以 HNSW 为例同时显式指定维度与相似度vector_store AzureCosmosDBMongoDBVectorSearch( mongodb_clientmongodb_client, db_namedemo_vectordb, collection_namepaul_graham_essay, index_namecontent_vector_index, cosmos_search_kwargs{ kind: vector-hnsw, m: 16, efConstruction: 64, similarity: COS, dimensions: 1536, }, )此外类还提供 create_filter_index 方法为元数据中的某个字段创建普通索引createIndexes命令key: {property_to_filter: 1}用于加速后续带pre_filter的过滤检索。写入节点字段映射与批量插入add 方法接收List[BaseNode]对每个节点执行如下映射后调用 PyMongo 的insert_many批量写入MongoDB 字段数据来源id_key默认idnode.node_idembedding_key默认content_vectornode.get_embedding()text_key默认textnode.get_content(metadata_modeMetadataMode.NONE)为空时回退为空字符串metadata_key默认metadatanode_to_metadata_dict(node, remove_textTrue, flat_metadataself.flat_metadata)方法返回成功插入的节点 ID 列表。insert_many调用时会透传insert_kwargs如ordered、bypass_document_validation等 PyMongo 支持的选项。from llama_index.core.schema import TextNode nodes [ TextNode( textlorem ipsum, id_c330d77f-90bd-4c51-9ed2-57d8d693b3b0, embedding[1.0, 0.0, 0.0], metadata{author: Stephen King, theme: Friendship}, ) ] ids vector_store.add(nodes) print(ids)删除节点按源文档 ID 级联删除delete 接收ref_doc_id通过delete_one过滤metadata.ref_doc_id字段实现删除vector_store.delete(ref_doc_idtest doc id)这里的ref_doc_id对应写入时节点关系NodeRelationship.SOURCE指向的文档 ID。查询检索三类聚合管道与运行时参数query 接收核心层定义的VectorStoreQuery对象关键字段见 types.py其中query_embedding为查询向量、similarity_top_k为返回条数默认1内部 _query 会根据cosmos_search_kwargs[kind]选择对应的聚合管道然后通过collection.aggregate(pipeline)执行检索。三类管道均基于 CosmosDB 的$search阶段核心参数查询参数默认值生效索引类型oversampling1.0三种类型均生效控制采样倍率pre_filter{}三种类型均生效MongoDB 过滤条件如元数据等值过滤非空时写入params[filter]ef_search40仅vector-hnsw控制查询时动态候选列表长度lSearch40仅vector-diskann控制查询时候选列表长度以 HNSW 管道_get_pipeline_vector_hnsw为例其聚合管道结构为pipeline [ { $search: { cosmosSearch: { vector: query.query_embedding, path: content_vector, k: query.similarity_top_k, efSearch: ef_search, oversampling: oversampling, } } }, { $project: { similarityScore: {$meta: searchScore}, document: $$ROOT, } }, ]IVF 管道额外设置了returnStoredSource: TrueDiskANN 管道将efSearch替换为lSearch。查询返回后代码会从结果文档中取出text、similarityScore、id、metadata并优先通过metadata_dict_to_node反序列化为节点若失败则走legacy_metadata_dict_to_node的兼容逻辑保持旧版本元数据格式的向后兼容。最终结果封装为VectorStoreQueryResult包含nodes、similarities与ids三个字段。典型查询示例from llama_index.core.vector_stores.types import VectorStoreQuery query VectorStoreQuery( query_embedding[1.0, 0.0, 0.0], similarity_top_k1, ) result vector_store.query(query) print(result.nodes[0].get_content(), result.similarities[0])带元数据预过滤的查询result vector_store.query( query, pre_filter{author: Stephen King}, ef_search100, # 仅 HNSW 类型生效 oversampling2.0, )结合 LlamaIndex 索引与检索器使用作为BasePydanticVectorStore的合法实现AzureCosmosDBMongoDBVectorSearch可被直接注入VectorStoreIndex作为向量存储后端使整个文档构建与检索流程统一到 CosmosDB。从源码结构看这是该集成在 LlamaIndex 应用中的标准用法from llama_index.core import VectorStoreIndex from llama_index.core.node_parser import SimpleNodeParser from llama_index.core.schema import Document documents [Document(textYour document content here.)] nodes SimpleNodeParser.from_defaults(chunk_size512).get_nodes_from_documents(documents) # 将节点与向量写入 CosmosDB并在其上构建索引 index VectorStoreIndex(nodes, vector_storevector_store) # 基于同一向量存储重建索引即可查询 query_engine index.as_query_engine() response query_engine.query(Your question?)写入阶段的add与查询阶段的query均被索引链路内部调用因此连接串、数据库与集合的配置只需在vector_store初始化时完成一次。测试验证仓库自带的端到端用例仓库在 tests/test_azurecosmosmongo.py 中提供了完整的集成测试可作为接入真实集群的验证脚本参考测试通过环境变量AZURE_COSMOSDB_MONGODB_URI读取连接串命名空间为llamaindex_test_db.llamaindex_test_collection索引名为llamaindex-test-indextest_add_and_delete构造 3 维向量的向量存储后写入一个节点断言集合文档数为 1随后按ref_doc_id删除并断言集合为空test_query写入三个带embedding与元数据author、director、theme的节点用[1.0, 0.0, 0.0]查询similarity_top_k1断言命中节点的文本内容为lorem ipsum用例在写入后sleep(1)等待 CosmosDB 索引更新查询后sleep(5)等待一致反映了 CosmosDB 索引近实时生效的特性。由于测试依赖真实 Azure 集群仓库默认将其标记为跳过需手动提供有效的AZURE_COSMOSDB_MONGODB_URI。你可以在本地运行pytest并注入环境变量后执行AZURE_COSMOSDB_MONGODB_URIyour-uri pytest llama-index-integrations/vector_stores/llama-index-vector-stores-azurecosmosmongo/tests/小结AzureCosmosDBMongoDBVectorSearch为 LlamaIndex 用户提供了开箱即用的 Azure CosmosDB MongoDB vCore 向量检索能力自动建索引、三类 ANN 算法可选、$search聚合管道查询、预过滤与运行时调参以及经由VectorStoreQuery/VectorStoreQueryResult与核心层无缝对接。实践中的关键点包括确认dimensions与嵌入模型一致、根据数据规模选择vector-ivf/vector-hnsw/vector-diskann并配置numLists、m、efConstruction等参数以及查询阶段合理调节ef_search/lSearch与oversampling以平衡召回与延迟。【免费下载链接】llama_indexLlamaIndex is the leading document agent and OCR platform项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考