尧图网站建设 
LlamaIndex 持久化索引元数据TablestoreIndexStore 使用与原理详解【免费下载链接】llama_indexLlamaIndex is the leading document agent and OCR platform项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index本文基于 LlamaIndex 开源仓库中 TablestoreIndexStore API 参考文档 展开深入讲解在 LlamaIndex 中如何借助阿里云表格存储Tablestore/OTS持久化索引结构Index Struct元数据。读完本文你将掌握TablestoreIndexStore的安装方式、两种初始化写法、完整 CRUD API、底层 KV 存储实现原理以及它与KVIndexStore、TablestoreKVStore之间的协作关系并了解如何通过测试用例验证其行为。一、TablestoreIndexStore 在 LlamaIndex 中的定位在 LlamaIndex 的存储体系中索引构建完成后生成的IndexStruct如IndexGraph、IndexDict等索引结构数据需要持久化保存以便后续加载复用。这部分元数据由 Index Store 负责管理。核心抽象BaseIndexStore定义在 llama-index-core/llama_index/core/storage/index_store/types.py而针对键值存储形态的实现是KVIndexStore位于 keyval_index_store.py。TablestoreIndexStore正是这个体系中的阿里云表格存储实现它继承自KVIndexStore将索引元数据以键值对 集合collection的形式写入 Tablestore 数据表从而让索引结构获得云端持久化、跨进程共享的能力。其核心源码位于集成包源码base.py包导出定义init.py从类继承关系TablestoreIndexStore - KVIndexStore - BaseIndexStore可以推断它天然具备索引存储的全部标准能力同时针对 Tablestore 增加了配置化构造与整表清空等特有方法。二、安装集成包TablestoreIndexStore属于独立的集成包需单独安装。其依赖声明在 pyproject.toml 中pip install llama-index-storage-index-store-tablestore该包声明了如下依赖约束依赖版本约束作用llama-index-storage-kvstore-tablestore0.2.0,0.3提供底层TablestoreKVStore键值存储实现llama-index-core0.13.0,0.15提供KVIndexStore、BaseIndexStore等核心抽象Python3.10,4.0运行时版本要求也就是说安装 index store 包时会自动带入底层的 kvstore 集成包两者共同构成完整的存储链路。三、快速开始两种初始化方式TablestoreIndexStore的构造签名定义在 base.pyTablestoreIndexStore( tablestore_kvstore: TablestoreKVStore, namespace: str llama_index_index_store_, collection_suffix: str data, )参数说明tablestore_kvstore必填一个已配置好的TablestoreKVStore实例负责与 Tablestore 服务端交互namespace命名空间前缀默认llama_index_index_store_用于与其他存储如 Docstore区分collection_suffix集合名后缀默认data。最终使用的集合名即 Tablestore 数据表名由KVIndexStore.__init__拼接生成即f{namespace}{collection_suffix}默认得到llama_index_index_store_data参见 keyval_index_store.py。方式一直接构造from llama_index.storage.kvstore.tablestore import TablestoreKVStore from llama_index.storage.index_store.tablestore import TablestoreIndexStore kv_store TablestoreKVStore( endpointhttps://your-instance.cn-hangzhou.ots.aliyuncs.com, instance_nameyour-instance, access_key_idyour-access-key-id, access_key_secretyour-access-key-secret, ) index_store TablestoreIndexStore(tablestore_kvstorekv_store)方式二from_config 一键构造推荐from llama_index.storage.index_store.tablestore import TablestoreIndexStore index_store TablestoreIndexStore.from_config( endpointhttps://your-instance.cn-hangzhou.ots.aliyuncs.com, instance_nameyour-instance, access_key_idyour-access-key-id, access_key_secretyour-access-key-secret, )from_config内部会先创建TablestoreKVStore再包装成TablestoreIndexStore并透传额外的**kwargs给底层客户端。此外TablestoreKVStore也支持直接传入外部创建好的tablestore.OTSClient实例通过tablestore_client参数此时其余连接参数会被忽略便于复用已有客户端连接。四、连接参数与底层客户端行为TablestoreKVStore构造时TablestoreKVStore 源码在未提供外部客户端时会用以下参数创建官方 SDK 客户端tablestore.OTSClient( endpoint, access_key_id, access_key_secret, instance_name, retry_policytablestore.WriteRetryPolicy(), **kwargs, )要点连接参数包括endpoint实例访问地址、instance_name实例名、access_key_id/access_key_secret阿里云访问密钥默认启用WriteRetryPolicy写重试策略提升写入可靠性其余**kwargs会透传给OTSClient可用于自定义超时、连接池等参数。在实际运行前请确保已在阿里云开通表格存储并创建实例、获取了可用的 AccessKey、实例 endpoint 格式正确并具备对该实例的读写权限。五、核心 API索引元数据的读写删查TablestoreIndexStore完整继承了KVIndexStore的 CRUD 方法同步 异步这也是BaseIndexStore抽象接口的全部实现。下表汇总了可直接调用的 API实现见 keyval_index_store.py方法说明底层 KV 操作add_index_struct(index_struct)写入一个索引结构以index_struct.index_id为 keykvstore.putget_index_struct(struct_idNone)按 ID 读取不传 ID 时要求集合中恰好只有一个结构并返回kvstore.getindex_structs()返回集合中全部索引结构列表kvstore.get_alldelete_index_struct(key)按 key 删除指定索引结构kvstore.deleteasync_add_index_struct(...)异步写入kvstore.aputaget_index_struct(...)异步读取kvstore.agetasync_index_structs()异步读取全部kvstore.aget_alladelete_index_struct(key)异步删除kvstore.adelete一个完整的使用示例from llama_index.core.data_structs import IndexGraph index_store TablestoreIndexStore.from_config( endpoint..., instance_name..., access_key_id..., access_key_secret..., ) # 写入 index_graph IndexGraph() index_store.add_index_struct(index_graph) # 读取 loaded index_store.get_index_struct(struct_idindex_graph.index_id) assert loaded index_graph # 列出全部 all_structs index_store.index_structs() # 删除 index_store.delete_index_struct(index_graph.index_id)写入时KVIndexStore会通过index_struct_to_json将IndexStruct序列化为 JSON再交给TablestoreKVStore.put落库读取时则通过json_to_index_struct反序列化还原对象参见 keyval_index_store.py。delete_all_index清空当前集合TablestoreIndexStore特有方法delete_all_index()会调用底层TablestoreKVStore.delete_all(self._collection)批量删除当前集合数据表中的全部索引记录base.py。适合在重建索引或清理测试数据时使用。六、底层原理数据如何落入 Tablestore索引元数据最终由TablestoreKVStore落库关键实现逻辑TablestoreKVStore 源码如下表不存在时自动建表写入前调用_create_collection_if_not_exist通过list_table()检查集合是否存在若不存在则以主键(pk, STRING)建表并用CapacityUnit(0, 0)创建零预留吞吐的表建表成功后等待 5 秒Tablestore 建表生效延迟再继续值序列化_flatten_dict_to_json_strings将布尔、字节、浮点、整数、字符串等原生类型直接保留其余类型如 dict、list统一json.dumps序列化为字符串写入以[(pk, key)]作为主键、值的各字段作为属性列构造tablestore.Row调用put_row写入范围读取get_all/delete_all使用get_range从INF_MIN到INF_MAX正向扫描主键单批 5000 行并通过next_start_primary_key循环翻页直至取完get_all 实现读回还原_parse_row尝试对字符串值执行json.loads成功且结果为 dict/list/tuple 时还原为结构化对象否则保留原字符串实现序列化往返。需要注意的是异步接口aput、aget、aget_all、adelete在TablestoreKVStore中当前实现为抛出NotImplementedError因此该集成现阶段以同步 API 为准。七、测试用例验证行为集成包自带的测试 test_storage_index_store_tablestore.py 验证了上述行为test_class断言TablestoreIndexStore的 MRO 中包含KVIndexStore确认继承关系fixturetablestore_index_store从环境变量tablestore_end_point、tablestore_instance_name、tablestore_access_key_id、tablestore_access_key_secret读取连接信息缺失时跳过测试随后通过from_config创建实例并调用delete_all_index()清空数据test_postgres_index_store实际测试 Tablestore 集成写入一个IndexGraph断言get_index_struct(struct_id...)能读回同一对象并确认index_structs()至少返回一条记录覆盖了写—读—列完整闭环。需要真实 Tablestore 实例环境变量才能运行这些测试可作为接入验证的参考脚本。八、与 Docstore 的关系同一套 Tablestore 存储底座在 LlamaIndex 存储体系中Index Store 与 Docstore 通常成对出现Docstore 保存文档节点Node原始数据Index Store 保存索引结构元数据。仓库中同时提供了 Tablestore 的 Docstore 实现与演示 NotebookTablestore Docstore 演示TablestoreDocstoreDemo.ipynb框架文档中对 Index Store 模块的整体说明index_stores.md两者共用同一TablestoreKVStore底座仅通过不同的namespace前缀区分数据表Index Store 默认llama_index_index_store_Docstore 使用其各自的默认命名空间因此可以在同一 Tablestore 实例中并存多类存储数据。九、小结TablestoreIndexStore为 LlamaIndex 提供了一条通往阿里云表格存储的索引元数据持久化路径开箱即用from_config一行完成连接配置能力完整继承KVIndexStore的同步/异步增删改查接口满足索引结构的完整生命周期管理自动运维集合不存在时自动建表读写时自动序列化/反序列化便于清理delete_all_index()一键清空索引集合。如果你的 LlamaIndex 应用已经运行在阿里云生态中希望索引元数据获得高可用、可扩展的云端持久化能力TablestoreIndexStore是一个直接可落地的方案。核心实现与测试均可在 index store 集成包 与 kvstore 集成包 中进一步研读。【免费下载链接】llama_indexLlamaIndex is the leading document agent and OCR platform项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 LlamaIndex 持久化索引元数据：TablestoreIndexStore 使用与原理详解
LlamaIndex 持久化索引元数据TablestoreIndexStore 使用与原理详解【免费下载链接】llama_indexLlamaIndex is the leading document agent and OCR platform项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index本文基于 LlamaIndex 开源仓库中 TablestoreIndexStore API 参考文档 展开深入讲解在 LlamaIndex 中如何借助阿里云表格存储Tablestore/OTS持久化索引结构Index Struct元数据。读完本文你将掌握TablestoreIndexStore的安装方式、两种初始化写法、完整 CRUD API、底层 KV 存储实现原理以及它与KVIndexStore、TablestoreKVStore之间的协作关系并了解如何通过测试用例验证其行为。一、TablestoreIndexStore 在 LlamaIndex 中的定位在 LlamaIndex 的存储体系中索引构建完成后生成的IndexStruct如IndexGraph、IndexDict等索引结构数据需要持久化保存以便后续加载复用。这部分元数据由 Index Store 负责管理。核心抽象BaseIndexStore定义在 llama-index-core/llama_index/core/storage/index_store/types.py而针对键值存储形态的实现是KVIndexStore位于 keyval_index_store.py。TablestoreIndexStore正是这个体系中的阿里云表格存储实现它继承自KVIndexStore将索引元数据以键值对 集合collection的形式写入 Tablestore 数据表从而让索引结构获得云端持久化、跨进程共享的能力。其核心源码位于集成包源码base.py包导出定义init.py从类继承关系TablestoreIndexStore - KVIndexStore - BaseIndexStore可以推断它天然具备索引存储的全部标准能力同时针对 Tablestore 增加了配置化构造与整表清空等特有方法。二、安装集成包TablestoreIndexStore属于独立的集成包需单独安装。其依赖声明在 pyproject.toml 中pip install llama-index-storage-index-store-tablestore该包声明了如下依赖约束依赖版本约束作用llama-index-storage-kvstore-tablestore0.2.0,0.3提供底层TablestoreKVStore键值存储实现llama-index-core0.13.0,0.15提供KVIndexStore、BaseIndexStore等核心抽象Python3.10,4.0运行时版本要求也就是说安装 index store 包时会自动带入底层的 kvstore 集成包两者共同构成完整的存储链路。三、快速开始两种初始化方式TablestoreIndexStore的构造签名定义在 base.pyTablestoreIndexStore( tablestore_kvstore: TablestoreKVStore, namespace: str llama_index_index_store_, collection_suffix: str data, )参数说明tablestore_kvstore必填一个已配置好的TablestoreKVStore实例负责与 Tablestore 服务端交互namespace命名空间前缀默认llama_index_index_store_用于与其他存储如 Docstore区分collection_suffix集合名后缀默认data。最终使用的集合名即 Tablestore 数据表名由KVIndexStore.__init__拼接生成即f{namespace}{collection_suffix}默认得到llama_index_index_store_data参见 keyval_index_store.py。方式一直接构造from llama_index.storage.kvstore.tablestore import TablestoreKVStore from llama_index.storage.index_store.tablestore import TablestoreIndexStore kv_store TablestoreKVStore( endpointhttps://your-instance.cn-hangzhou.ots.aliyuncs.com, instance_nameyour-instance, access_key_idyour-access-key-id, access_key_secretyour-access-key-secret, ) index_store TablestoreIndexStore(tablestore_kvstorekv_store)方式二from_config 一键构造推荐from llama_index.storage.index_store.tablestore import TablestoreIndexStore index_store TablestoreIndexStore.from_config( endpointhttps://your-instance.cn-hangzhou.ots.aliyuncs.com, instance_nameyour-instance, access_key_idyour-access-key-id, access_key_secretyour-access-key-secret, )from_config内部会先创建TablestoreKVStore再包装成TablestoreIndexStore并透传额外的**kwargs给底层客户端。此外TablestoreKVStore也支持直接传入外部创建好的tablestore.OTSClient实例通过tablestore_client参数此时其余连接参数会被忽略便于复用已有客户端连接。四、连接参数与底层客户端行为TablestoreKVStore构造时TablestoreKVStore 源码在未提供外部客户端时会用以下参数创建官方 SDK 客户端tablestore.OTSClient( endpoint, access_key_id, access_key_secret, instance_name, retry_policytablestore.WriteRetryPolicy(), **kwargs, )要点连接参数包括endpoint实例访问地址、instance_name实例名、access_key_id/access_key_secret阿里云访问密钥默认启用WriteRetryPolicy写重试策略提升写入可靠性其余**kwargs会透传给OTSClient可用于自定义超时、连接池等参数。在实际运行前请确保已在阿里云开通表格存储并创建实例、获取了可用的 AccessKey、实例 endpoint 格式正确并具备对该实例的读写权限。五、核心 API索引元数据的读写删查TablestoreIndexStore完整继承了KVIndexStore的 CRUD 方法同步 异步这也是BaseIndexStore抽象接口的全部实现。下表汇总了可直接调用的 API实现见 keyval_index_store.py方法说明底层 KV 操作add_index_struct(index_struct)写入一个索引结构以index_struct.index_id为 keykvstore.putget_index_struct(struct_idNone)按 ID 读取不传 ID 时要求集合中恰好只有一个结构并返回kvstore.getindex_structs()返回集合中全部索引结构列表kvstore.get_alldelete_index_struct(key)按 key 删除指定索引结构kvstore.deleteasync_add_index_struct(...)异步写入kvstore.aputaget_index_struct(...)异步读取kvstore.agetasync_index_structs()异步读取全部kvstore.aget_alladelete_index_struct(key)异步删除kvstore.adelete一个完整的使用示例from llama_index.core.data_structs import IndexGraph index_store TablestoreIndexStore.from_config( endpoint..., instance_name..., access_key_id..., access_key_secret..., ) # 写入 index_graph IndexGraph() index_store.add_index_struct(index_graph) # 读取 loaded index_store.get_index_struct(struct_idindex_graph.index_id) assert loaded index_graph # 列出全部 all_structs index_store.index_structs() # 删除 index_store.delete_index_struct(index_graph.index_id)写入时KVIndexStore会通过index_struct_to_json将IndexStruct序列化为 JSON再交给TablestoreKVStore.put落库读取时则通过json_to_index_struct反序列化还原对象参见 keyval_index_store.py。delete_all_index清空当前集合TablestoreIndexStore特有方法delete_all_index()会调用底层TablestoreKVStore.delete_all(self._collection)批量删除当前集合数据表中的全部索引记录base.py。适合在重建索引或清理测试数据时使用。六、底层原理数据如何落入 Tablestore索引元数据最终由TablestoreKVStore落库关键实现逻辑TablestoreKVStore 源码如下表不存在时自动建表写入前调用_create_collection_if_not_exist通过list_table()检查集合是否存在若不存在则以主键(pk, STRING)建表并用CapacityUnit(0, 0)创建零预留吞吐的表建表成功后等待 5 秒Tablestore 建表生效延迟再继续值序列化_flatten_dict_to_json_strings将布尔、字节、浮点、整数、字符串等原生类型直接保留其余类型如 dict、list统一json.dumps序列化为字符串写入以[(pk, key)]作为主键、值的各字段作为属性列构造tablestore.Row调用put_row写入范围读取get_all/delete_all使用get_range从INF_MIN到INF_MAX正向扫描主键单批 5000 行并通过next_start_primary_key循环翻页直至取完get_all 实现读回还原_parse_row尝试对字符串值执行json.loads成功且结果为 dict/list/tuple 时还原为结构化对象否则保留原字符串实现序列化往返。需要注意的是异步接口aput、aget、aget_all、adelete在TablestoreKVStore中当前实现为抛出NotImplementedError因此该集成现阶段以同步 API 为准。七、测试用例验证行为集成包自带的测试 test_storage_index_store_tablestore.py 验证了上述行为test_class断言TablestoreIndexStore的 MRO 中包含KVIndexStore确认继承关系fixturetablestore_index_store从环境变量tablestore_end_point、tablestore_instance_name、tablestore_access_key_id、tablestore_access_key_secret读取连接信息缺失时跳过测试随后通过from_config创建实例并调用delete_all_index()清空数据test_postgres_index_store实际测试 Tablestore 集成写入一个IndexGraph断言get_index_struct(struct_id...)能读回同一对象并确认index_structs()至少返回一条记录覆盖了写—读—列完整闭环。需要真实 Tablestore 实例环境变量才能运行这些测试可作为接入验证的参考脚本。八、与 Docstore 的关系同一套 Tablestore 存储底座在 LlamaIndex 存储体系中Index Store 与 Docstore 通常成对出现Docstore 保存文档节点Node原始数据Index Store 保存索引结构元数据。仓库中同时提供了 Tablestore 的 Docstore 实现与演示 NotebookTablestore Docstore 演示TablestoreDocstoreDemo.ipynb框架文档中对 Index Store 模块的整体说明index_stores.md两者共用同一TablestoreKVStore底座仅通过不同的namespace前缀区分数据表Index Store 默认llama_index_index_store_Docstore 使用其各自的默认命名空间因此可以在同一 Tablestore 实例中并存多类存储数据。九、小结TablestoreIndexStore为 LlamaIndex 提供了一条通往阿里云表格存储的索引元数据持久化路径开箱即用from_config一行完成连接配置能力完整继承KVIndexStore的同步/异步增删改查接口满足索引结构的完整生命周期管理自动运维集合不存在时自动建表读写时自动序列化/反序列化便于清理delete_all_index()一键清空索引集合。如果你的 LlamaIndex 应用已经运行在阿里云生态中希望索引元数据获得高可用、可扩展的云端持久化能力TablestoreIndexStore是一个直接可落地的方案。核心实现与测试均可在 index store 集成包 与 kvstore 集成包 中进一步研读。【免费下载链接】llama_indexLlamaIndex is the leading document agent and OCR platform项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考