LlamaIndex 存储层实战使用 Azure Cosmos DB NoSQL KVStore 管理文档与索引元数据【免费下载链接】llama_indexLlamaIndex is the leading document agent and OCR platform项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index导读本文围绕 llama_index 存储层中基于 Azure Cosmos DB NoSQL 实现的AzureCosmosNoSqlKVStore系统讲解其类方法、初始化参数、核心读写 API、异步方法支持边界、容器属性配置以及在BaseKVStore抽象体系中的定位。阅读完成后你将能够在 LlamaIndex 应用中用连接字符串、账号密钥或 Azure AD 令牌三种方式接入 Cosmos DB NoSQL并正确选择同步/异步方法完成 KV 数据的持久化读写同时了解它与 DocStore、IndexStore 等其他存储组件的协作方式。一、AzureCosmosNoSqlKVStore 在 LlamaIndex 存储体系中的定位LlamaIndex 的 KVStore 层承担着键值数据的持久化职责其抽象基类BaseKVStore定义在 types.py 中要求所有实现提供put、get、get_all、delete及对应的异步版本aput、aget、aget_all、adelete并约定默认 collection 名为data。AzureCosmosNoSqlKVStore位于 base.py它继承自BaseKVStore将 Azure Cosmos DB NoSQL API 作为底层持久化介质用 Cosmos 的 Database 对应 LlamaIndex 的数据库实例、Container 承载 KV 数据。从仓库结构看Cosmos NoSQL 集成同时提供了同系列的 DocStore 与 IndexStore 实现KVStore 是其中被 ChatStore、Memory 等上层模块复用的基础组件。该集成的包信息可在 pyproject.toml 中确认包名为llama-index-storage-kv-store-azurecosmosnosql版本 1.3.0依赖azure-cosmos4.7.0,5、azure-identity1.7.1,2以及llama-index-core0.13.0,0.15。二、安装与导入安装该集成包后即可从llama_index.storage.kvstore.azurecosmosnosql导入AzureCosmosNoSqlKVStore导出声明见init.pyfrom llama_index.storage.kvstore.azurecosmosnosql import AzureCosmosNoSqlKVStore注意本文仓库为源码形态实际使用时需按常规 Python 包方式安装该集成包及其依赖azure-cosmos、azure-identity等并确保 Cosmos DB NoSQL 账号可访问。三、核心类方法与初始化参数AzureCosmosNoSqlKVStore在构造时会将传入的CosmosClient保存在PrivateAttr中并自动完成数据库与容器的“不存在则创建”逻辑通过create_database_if_not_exists创建数据库默认名KVStoreDB通过create_container_if_not_exists创建容器默认名KVStoreContainer其中partition_key 是必填项源码中直接通过cosmos_container_properties[partition_key]访问。3.1 构造器参数详解参数类型默认值说明cosmos_clientCosmosClient无azure-cosmos 的客户端实例通常由下面三个类方法之一创建chat_db_namestrKVStoreDBCosmos 数据库名称不存在时自动创建chat_container_namestrKVStoreContainerCosmos 容器名称不存在时自动创建cosmos_container_propertiesDict[str, Any]None容器创建属性至少需含partition_keycosmos_database_propertiesDict[str, Any]None数据库创建属性如offer_throughput等cosmos_container_properties支持键包括partition_key必填、indexing_policy、default_ttl、offer_throughput、unique_key_policy、conflict_resolution_policy、analytical_storage_ttl、computed_properties、etag、match_condition、session_token、initial_headers。其中default_ttl可设置数据自动过期时间offer_throughput用于配置吞吐量RU/sunique_key_policy用于保证键唯一性这些参数都会原样透传给 azure-cosmos SDK 的容器创建方法。cosmos_database_properties支持offer_throughput、session_token、initial_headers、etag、match_condition。3.2 三种客户端创建方式方式一连接字符串kv_store AzureCosmosNoSqlKVStore.from_connection_string( connection_stringAccountEndpoint...;AccountKey...;, )方式二账号 Endpoint Keykv_store AzureCosmosNoSqlKVStore.from_account_and_key( endpointhttps://account-name.documents.azure.com:443/, keyprimary-key, )方式三Azure AD 令牌AADkv_store AzureCosmosNoSqlKVStore.from_aad_token( endpointhttps://account-name.documents.azure.com:443/, )第三种方式内部使用azure.identity.DefaultAzureCredential()获取凭据适合在 Azure 托管环境如 VM、Functions、AKS中以托管身份免密钥接入三种方式均支持传入chat_db_name、chat_container_name、cosmos_container_properties、cosmos_database_properties四个可选参数。四、核心 APIKV 数据读写全流程AzureCosmosNoSqlKVStore将 KV 数据映射为 Cosmos 容器内的文档写入时以{id: key, messages: val}结构创建条目读取时返回文档中的messages字段。4.1 写入 putkv_store.put(keysession-1, val{user: alice, history: [...]})4.2 读取 get / get_allvalue kv_store.get(session-1) # 返回 dict键不存在时返回 {} all_items kv_store.get_all() # 返回 {id: 文档} 的映射get_all通过read_all_items()遍历容器返回以文档id为键的完整字典。4.3 删除 deletedeleted kv_store.delete(session-1) # 成功返回 True失败记录日志并返回 False4.4 异步方法的边界该类目前未实现异步方法aput、aget、aget_all、adelete均直接抛出NotImplementedError见 base.py。因此在异步代码路径中请使用同步方法配合线程池或等待该集成后续版本补齐异步实现。同理BaseKVStore的put_all默认仅支持batch_size1逐条调用put。五、作为 KVStore 的验证与组合使用仓库测试 test_storage_azurecosmosnosql_kv_store.py 验证了AzureCosmosNoSqlKVStore确实继承自BaseKVStore确认其符合 LlamaIndex 存储抽象契约。由于 ChatStore、Memory 等模块依赖 KVStore 的put/get接口可将本实现注入这些上层组件以复用 Cosmos 持久化同目录下的 docstore 与 index_store 也基于同一 Cosmos 账号体系可用于完整落地文档与索引元数据的云原生存储方案。六、使用注意事项partition_key 必填创建容器时必须提供否则构造阶段即抛 KeyError默认库/容器名KVStoreDB/KVStoreContainer多环境隔离时建议显式指定不同名称数据过期需要自动清理时设置cosmos_container_properties[default_ttl]异步支持缺失当前版本异步方法不可用编程时避免在 async 场景直接调用依赖版本约束azure-cosmos4.7.0,5、azure-identity1.7.1,2、llama-index-core0.13.0,0.15升级依赖前请核对兼容性。七、总结AzureCosmosNoSqlKVStore是 LlamaIndex 存储层中面向 Azure 云原生的 KV 持久化实现继承 BaseKVStore 统一契约支持连接字符串、账号密钥、AAD 三种认证方式通过put/get/get_all/delete完成文档级 KV 操作。其数据库、容器自动创建机制与容器属性透传设计使其可灵活适配吞吐、TTL、分区键等生产级需求配合同系列 DocStore、IndexStore 可实现完整的数据持久化闭环。使用前请重点确认容器分区键配置与异步方法边界以获得稳定可控的存储体验。【免费下载链接】llama_indexLlamaIndex is the leading document agent and OCR platform项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
LlamaIndex 存储层实战使用 Azure Cosmos DB NoSQL KVStore 管理文档与索引元数据【免费下载链接】llama_indexLlamaIndex is the leading document agent and OCR platform项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index导读本文围绕 llama_index 存储层中基于 Azure Cosmos DB NoSQL 实现的AzureCosmosNoSqlKVStore系统讲解其类方法、初始化参数、核心读写 API、异步方法支持边界、容器属性配置以及在BaseKVStore抽象体系中的定位。阅读完成后你将能够在 LlamaIndex 应用中用连接字符串、账号密钥或 Azure AD 令牌三种方式接入 Cosmos DB NoSQL并正确选择同步/异步方法完成 KV 数据的持久化读写同时了解它与 DocStore、IndexStore 等其他存储组件的协作方式。一、AzureCosmosNoSqlKVStore 在 LlamaIndex 存储体系中的定位LlamaIndex 的 KVStore 层承担着键值数据的持久化职责其抽象基类BaseKVStore定义在 types.py 中要求所有实现提供put、get、get_all、delete及对应的异步版本aput、aget、aget_all、adelete并约定默认 collection 名为data。AzureCosmosNoSqlKVStore位于 base.py它继承自BaseKVStore将 Azure Cosmos DB NoSQL API 作为底层持久化介质用 Cosmos 的 Database 对应 LlamaIndex 的数据库实例、Container 承载 KV 数据。从仓库结构看Cosmos NoSQL 集成同时提供了同系列的 DocStore 与 IndexStore 实现KVStore 是其中被 ChatStore、Memory 等上层模块复用的基础组件。该集成的包信息可在 pyproject.toml 中确认包名为llama-index-storage-kv-store-azurecosmosnosql版本 1.3.0依赖azure-cosmos4.7.0,5、azure-identity1.7.1,2以及llama-index-core0.13.0,0.15。二、安装与导入安装该集成包后即可从llama_index.storage.kvstore.azurecosmosnosql导入AzureCosmosNoSqlKVStore导出声明见init.pyfrom llama_index.storage.kvstore.azurecosmosnosql import AzureCosmosNoSqlKVStore注意本文仓库为源码形态实际使用时需按常规 Python 包方式安装该集成包及其依赖azure-cosmos、azure-identity等并确保 Cosmos DB NoSQL 账号可访问。三、核心类方法与初始化参数AzureCosmosNoSqlKVStore在构造时会将传入的CosmosClient保存在PrivateAttr中并自动完成数据库与容器的“不存在则创建”逻辑通过create_database_if_not_exists创建数据库默认名KVStoreDB通过create_container_if_not_exists创建容器默认名KVStoreContainer其中partition_key 是必填项源码中直接通过cosmos_container_properties[partition_key]访问。3.1 构造器参数详解参数类型默认值说明cosmos_clientCosmosClient无azure-cosmos 的客户端实例通常由下面三个类方法之一创建chat_db_namestrKVStoreDBCosmos 数据库名称不存在时自动创建chat_container_namestrKVStoreContainerCosmos 容器名称不存在时自动创建cosmos_container_propertiesDict[str, Any]None容器创建属性至少需含partition_keycosmos_database_propertiesDict[str, Any]None数据库创建属性如offer_throughput等cosmos_container_properties支持键包括partition_key必填、indexing_policy、default_ttl、offer_throughput、unique_key_policy、conflict_resolution_policy、analytical_storage_ttl、computed_properties、etag、match_condition、session_token、initial_headers。其中default_ttl可设置数据自动过期时间offer_throughput用于配置吞吐量RU/sunique_key_policy用于保证键唯一性这些参数都会原样透传给 azure-cosmos SDK 的容器创建方法。cosmos_database_properties支持offer_throughput、session_token、initial_headers、etag、match_condition。3.2 三种客户端创建方式方式一连接字符串kv_store AzureCosmosNoSqlKVStore.from_connection_string( connection_stringAccountEndpoint...;AccountKey...;, )方式二账号 Endpoint Keykv_store AzureCosmosNoSqlKVStore.from_account_and_key( endpointhttps://account-name.documents.azure.com:443/, keyprimary-key, )方式三Azure AD 令牌AADkv_store AzureCosmosNoSqlKVStore.from_aad_token( endpointhttps://account-name.documents.azure.com:443/, )第三种方式内部使用azure.identity.DefaultAzureCredential()获取凭据适合在 Azure 托管环境如 VM、Functions、AKS中以托管身份免密钥接入三种方式均支持传入chat_db_name、chat_container_name、cosmos_container_properties、cosmos_database_properties四个可选参数。四、核心 APIKV 数据读写全流程AzureCosmosNoSqlKVStore将 KV 数据映射为 Cosmos 容器内的文档写入时以{id: key, messages: val}结构创建条目读取时返回文档中的messages字段。4.1 写入 putkv_store.put(keysession-1, val{user: alice, history: [...]})4.2 读取 get / get_allvalue kv_store.get(session-1) # 返回 dict键不存在时返回 {} all_items kv_store.get_all() # 返回 {id: 文档} 的映射get_all通过read_all_items()遍历容器返回以文档id为键的完整字典。4.3 删除 deletedeleted kv_store.delete(session-1) # 成功返回 True失败记录日志并返回 False4.4 异步方法的边界该类目前未实现异步方法aput、aget、aget_all、adelete均直接抛出NotImplementedError见 base.py。因此在异步代码路径中请使用同步方法配合线程池或等待该集成后续版本补齐异步实现。同理BaseKVStore的put_all默认仅支持batch_size1逐条调用put。五、作为 KVStore 的验证与组合使用仓库测试 test_storage_azurecosmosnosql_kv_store.py 验证了AzureCosmosNoSqlKVStore确实继承自BaseKVStore确认其符合 LlamaIndex 存储抽象契约。由于 ChatStore、Memory 等模块依赖 KVStore 的put/get接口可将本实现注入这些上层组件以复用 Cosmos 持久化同目录下的 docstore 与 index_store 也基于同一 Cosmos 账号体系可用于完整落地文档与索引元数据的云原生存储方案。六、使用注意事项partition_key 必填创建容器时必须提供否则构造阶段即抛 KeyError默认库/容器名KVStoreDB/KVStoreContainer多环境隔离时建议显式指定不同名称数据过期需要自动清理时设置cosmos_container_properties[default_ttl]异步支持缺失当前版本异步方法不可用编程时避免在 async 场景直接调用依赖版本约束azure-cosmos4.7.0,5、azure-identity1.7.1,2、llama-index-core0.13.0,0.15升级依赖前请核对兼容性。七、总结AzureCosmosNoSqlKVStore是 LlamaIndex 存储层中面向 Azure 云原生的 KV 持久化实现继承 BaseKVStore 统一契约支持连接字符串、账号密钥、AAD 三种认证方式通过put/get/get_all/delete完成文档级 KV 操作。其数据库、容器自动创建机制与容器属性透传设计使其可灵活适配吞吐、TTL、分区键等生产级需求配合同系列 DocStore、IndexStore 可实现完整的数据持久化闭环。使用前请重点确认容器分区键配置与异步方法边界以获得稳定可控的存储体验。【免费下载链接】llama_indexLlamaIndex is the leading document agent and OCR platform项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
