llama-index 集成 Alibaba Cloud OpenSearch 向量存储AlibabaCloudOpenSearchStore 配置与实战指南【免费下载链接】llama_indexLlamaIndex is the leading document agent and OCR platform项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index本篇技术指南围绕 llama-index 仓库中llama-index-vector-stores-alibabacloud-opensearch集成包的 API 参考文档所指定的核心成员AlibabaCloudOpenSearch即向量存储类AlibabaCloudOpenSearchStore与其配置类AlibabaCloudOpenSearchConfig展开讲解如何在 LlamaIndex 中接入阿里云 OpenSearch 向量检索版作为持久化向量存储包括实例与数据表前置准备、完整配置参数、文档写入、相似度查询、元数据过滤以及底层实现原理。读完本文你将能够独立完成「OpenSearch 实例 → LlamaIndex 配置 → 索引构建 → 查询与过滤」的完整链路搭建并理解该集成在源码层面的工作方式。集成概览为什么选择 OpenSearch 作为向量存储Alibaba Cloud OpenSearch 向量检索版是阿里集团自研的大规模分布式检索引擎支撑了淘宝、天猫、菜鸟、优酷等业务场景的搜索服务也是阿里云 OpenSearch 的基础引擎。在 LlamaIndex 生态中该集成包 将其包装为标准向量存储使开发者可以在 OpenSearch 数据表中持久化保存文本、向量embedding与元数据通过 LlamaIndex 统一的VectorStoreIndex接口完成索引构建与查询利用 OpenSearch 的分布式能力承载大规模向量检索。集成包对外暴露两个核心类见init.py类名职责AlibabaCloudOpenSearchConfig封装 OpenSearch 实例的连接与表配置信息AlibabaCloudOpenSearchStore继承BasePydanticVectorStore实现增、删、查等向量存储操作环境准备与安装前置条件使用该集成前你需要在阿里云控制台购买并创建OpenSearch 向量检索版实例在实例中预先配置好数据表table并确定主键字段与向量字段的映射准备好endpoint、instance_id、username、password等实例凭据均可在阿里云 OpenSearch 控制台获取。安装依赖在 Python 3.10 环境中安装集成包pip install llama-index pip install llama-index-vector-stores-alibabacloud-opensearch根据 pyproject.toml 声明的依赖安装时会自动拉取alibabacloud_ha3engine_vector1.1.8,2阿里云官方 Python SDK负责与 OpenSearch 实例通信llama-index-core0.13.0,0.15LlamaIndex 核心库提供向量存储抽象基类与索引/查询能力。需要说明的是base.py 的导入逻辑 会强制校验alibabacloud_ha3engine_vector是否已安装若缺失将直接抛出ImportError并提示执行pip install alibabacloud_ha3engine_vector。核心配置类 AlibabaCloudOpenSearchConfig 参数详解AlibabaCloudOpenSearchConfig是所有初始化步骤的入口其完整参数定义位于 base.py 的 AlibabaCloudOpenSearchConfig 实现。各参数含义与取值说明如下参数必填默认值说明endpoint是无OpenSearch 实例的访问端点可在阿里云 OpenSearch 控制台查看instance_id是无实例唯一标识例如ha-cn-******同样在控制台获取username是无购买实例时指定的用户名password是无购买实例时设置的密码实例创建后可在控制台修改table_name是无实例配置时指定的数据表名称namespace否若实例开启了 namespace 分区则必须指定该字段名否则查询无法正确执行field_mapping否NoneLlamaIndex 元数据字段名与 OpenSearch 表字段名之间的映射字典当元数据字段名违反 OpenSearch 字段命名规则时使用output_fields否None查询时希望返回的字段列表缺省时自动取field_mapping的值列表并强制追加text_fieldid_field否idOpenSearch 表的主键字段名embedding_field否DEFAULT_EMBEDDING_KEY存储向量的字段名核心默认键为embeddingtext_field否DEFAULT_TEXT_KEY存储正文文本的字段名核心默认键为textsearch_config否None查询行为配置支持order、score_threshold、search_params三个子项详见下文关于字段映射field_mappingOpenSearch 对字段命名有自身规则当 LlamaIndex 侧元数据字段名不合规时可通过field_mapping将其映射为合法的表字段名。从源码实现看该映射是双向维护的写入时async_addLlamaIndex 元数据键通过field_mapping.get(key, key)转换为表字段名读取时aquery通过反向映射inverse_field_mapping由{value: key for key, value in field_mapping.items()}构造将表字段名还原为 LlamaIndex 元数据键。查询配置search_configsearch_config接受一个字典源码中仅消费以下三个键见 _gen_query_requestsearch_config { order: ASC, # 排序方向默认 ASC score_threshold: 0.5, # 分数阈值低于该分数的结果将被过滤 search_params: {...} # 额外的搜索参数会被 JSON 序列化后传入请求 }快速开始从文档构建索引初始化向量存储以下是最小化配置示例与 README.md 及 示例 Notebook 保持一致from llama_index.vector_stores.alibabacloud_opensearch import ( AlibabaCloudOpenSearchStore, AlibabaCloudOpenSearchConfig, ) config AlibabaCloudOpenSearchConfig( endpoint***, instance_idha-cn-******, usernameyour_username, passwordyour_password, table_namellama, ) vector_store AlibabaCloudOpenSearchStore(config)AlibabaCloudOpenSearchStore.__init__内部会使用这些参数构造官方 SDK 客户端self._client client.Client( models.Config( endpointconfig.endpoint, instance_idconfig.instance_id, access_user_nameconfig.username, access_pass_wordconfig.password, ) )加载文档并构建索引from llama_index.core import SimpleDirectoryReader, StorageContext, VectorStoreIndex # 加载本地文档 documents SimpleDirectoryReader(./data/paul_graham).load_data() # 将 OpenSearch 挂载为存储上下文 storage_context StorageContext.from_defaults(vector_storevector_store) # 构建索引文档切分、embedding 与写入 OpenSearch 一气呵成 index VectorStoreIndex.from_documents(documents, storage_contextstorage_context)写入过程由async_add完成见 add 实现其关键行为包括以每批 100 条DEFAULT_BATCH_SIZE 100为单位分批推送避免单次请求体过大每条文档写入id_field主键取node.node_id、embedding_field节点向量、text_field节点文本以及全部元数据字段通过 SDK 的push_documents_async以cmdadd执行 upsert 语义幂等可重复写入任意批次失败会抛出RuntimeError并附带失败详情。连接已有实例并执行查询由于 OpenSearch 是持久化服务索引天然具备持久性。当需要连接一个已写入数据的既有实例时只需用同一份配置重建 Store 与索引from llama_index.core import VectorStoreIndex config AlibabaCloudOpenSearchConfig( endpoint***, instance_id***, usernameyour_username, passwordyour_password, table_namellama, ) vector_store AlibabaCloudOpenSearchStore(config) # 从已有向量构建索引 index VectorStoreIndex.from_vector_store(vector_store) # 构造查询引擎并提问 query_engine index.as_query_engine() response query_engine.query(What did the author study prior to working on AI?) print(response)查询链路最终落在aquery与_gen_query_request见 查询实现仅支持VectorStoreQueryMode.DEFAULT其他查询模式如稀疏、混合检索会抛出ValueError请求体包含table_name、namespace、查询向量、top_k由query.similarity_top_k决定以及output_fields结果解析时优先尝试从_node_content元数据反序列化出完整节点失败则回退为构造仅含文本与元数据的TextNode返回结果包含ids、nodes、similarities分数列表三部分供上层VectorStoreIndex组装最终答案。查询时元数据过滤OpenSearch 向量存储支持在查询时通过标准MetadataFilters进行条件过滤。以下示例取自 示例 Notebook演示了如何先为文档附加自定义元数据再按元数据限制检索范围from llama_index.core import SimpleDirectoryReader, StorageContext, VectorStoreIndex # 依据文件名附加不同的 source_type 元数据 def my_file_metadata(file_name: str): if essay in file_name: source_type essay elif dinosaur in file_name: source_type dinos else: source_type other return {source_type: source_type} md_documents SimpleDirectoryReader( ./data/paul_graham, file_metadatamy_file_metadata ).load_data() md_storage_context StorageContext.from_defaults( vector_storeAlibabaCloudOpenSearchStore(config) ) md_index VectorStoreIndex.from_documents( md_documents, storage_contextmd_storage_context ) # 查询时附加元数据过滤条件 from llama_index.core.vector_stores import MetadataFilter, MetadataFilters md_query_engine md_index.as_query_engine( filtersMetadataFilters( filters[MetadataFilter(keysource_type, valueessay)] ) ) md_response md_query_engine.query(How long it took the author to write his thesis?) print(md_response)过滤条件与算子限制过滤条件由_to_ha3_engine_filter转换为 OpenSearch 可识别的查询串见 过滤转换实现其规则为支持的算子EQ转换为以及GT、GTE、LT、LTE、NEQ等比较算子直接沿用枚举值不支持的算子IN、NIN、TEXT_MATCH、CONTAINS会直接抛出ValueError提示信息为 Alibaba Cloud OpenSearch not support filter operator:in/nin/text_match/containsyet字符串值会被自动加上双引号如source_type essay数值类型保持原样组合条件多个过滤条件通过FilterCondition.AND/FilterCondition.OR拼接分别生成AND与OR连接符。删除数据AlibabaCloudOpenSearchStore提供delete与异步版adelete见 删除实现按文档的ref_doc_id删除先用FetchRequest按doc_idref_doc_id查询命中记录若响应含errorMsg则抛出RuntimeError将命中的记录 id 以cmddelete批量推送删除。源码结构与测试佐证模块文件构成集成包源码结构如下完整目录见 llama-index-vector-stores-alibabacloud-opensearchllama-index-vector-stores-alibabacloud-opensearch/ ├── llama_index/vector_stores/alibabacloud_opensearch/ │ ├── __init__.py # 导出 AlibabaCloudOpenSearchConfig / AlibabaCloudOpenSearchStore │ └── base.py # 核心实现配置类 向量存储类 ├── tests/ │ └── test_vector_stores_alibabacloud_opensearch.py ├── README.md └── pyproject.toml测试用例仓库自带的 测试文件 验证了AlibabaCloudOpenSearchStore正确继承自BasePydanticVectorStoretest_class断言其 MRO 中包含BasePydanticVectorStore即该集成与 LlamaIndex 核心向量存储抽象完全兼容可无缝用于VectorStoreIndex、StorageContext等上层设施。注意事项与已知限制综合源码与示例文档使用该集成时需留意以下几点前置依赖较重必须先拥有可用的 OpenSearch 向量检索版实例并配置好数据表无法离线试用查询模式受限目前仅支持默认向量查询VectorStoreQueryMode.DEFAULT不支持稀疏检索等扩展模式过滤算子受限IN、NIN、TEXT_MATCH、CONTAINS等算子尚未实现涉及集合与文本匹配的过滤需在应用层先行处理namespace 约束若实例启用了 namespace 分区初始化时必须显式传入namespace字段名否则查询会失败异步兼容由于实现依赖asyncio事件循环同步方法通过run_until_complete包装在 Notebook 等已有运行中事件循环的环境里建议像示例那样先执行nest_asyncio.apply()以避免asyncio冲突字段命名合规LlamaIndex 元数据字段若不合 OpenSearch 命名规则务必通过field_mapping建立映射并保证text_field出现在最终output_fields中源码会强制追加。进阶阅读完整实战演练含下载 Paul Graham 语料、构建索引、元数据过滤、连接既有实例AlibabaCloudOpenSearchIndexDemo.ipynb集成包使用说明README.md核心实现源码base.py依赖与版本声明pyproject.toml兼容性测试test_vector_stores_alibabacloud_opensearch.py【免费下载链接】llama_indexLlamaIndex is the leading document agent and OCR platform项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
llama-index 集成 Alibaba Cloud OpenSearch 向量存储：AlibabaCloudOpenSearchStore 配置与实战指南
llama-index 集成 Alibaba Cloud OpenSearch 向量存储AlibabaCloudOpenSearchStore 配置与实战指南【免费下载链接】llama_indexLlamaIndex is the leading document agent and OCR platform项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index本篇技术指南围绕 llama-index 仓库中llama-index-vector-stores-alibabacloud-opensearch集成包的 API 参考文档所指定的核心成员AlibabaCloudOpenSearch即向量存储类AlibabaCloudOpenSearchStore与其配置类AlibabaCloudOpenSearchConfig展开讲解如何在 LlamaIndex 中接入阿里云 OpenSearch 向量检索版作为持久化向量存储包括实例与数据表前置准备、完整配置参数、文档写入、相似度查询、元数据过滤以及底层实现原理。读完本文你将能够独立完成「OpenSearch 实例 → LlamaIndex 配置 → 索引构建 → 查询与过滤」的完整链路搭建并理解该集成在源码层面的工作方式。集成概览为什么选择 OpenSearch 作为向量存储Alibaba Cloud OpenSearch 向量检索版是阿里集团自研的大规模分布式检索引擎支撑了淘宝、天猫、菜鸟、优酷等业务场景的搜索服务也是阿里云 OpenSearch 的基础引擎。在 LlamaIndex 生态中该集成包 将其包装为标准向量存储使开发者可以在 OpenSearch 数据表中持久化保存文本、向量embedding与元数据通过 LlamaIndex 统一的VectorStoreIndex接口完成索引构建与查询利用 OpenSearch 的分布式能力承载大规模向量检索。集成包对外暴露两个核心类见init.py类名职责AlibabaCloudOpenSearchConfig封装 OpenSearch 实例的连接与表配置信息AlibabaCloudOpenSearchStore继承BasePydanticVectorStore实现增、删、查等向量存储操作环境准备与安装前置条件使用该集成前你需要在阿里云控制台购买并创建OpenSearch 向量检索版实例在实例中预先配置好数据表table并确定主键字段与向量字段的映射准备好endpoint、instance_id、username、password等实例凭据均可在阿里云 OpenSearch 控制台获取。安装依赖在 Python 3.10 环境中安装集成包pip install llama-index pip install llama-index-vector-stores-alibabacloud-opensearch根据 pyproject.toml 声明的依赖安装时会自动拉取alibabacloud_ha3engine_vector1.1.8,2阿里云官方 Python SDK负责与 OpenSearch 实例通信llama-index-core0.13.0,0.15LlamaIndex 核心库提供向量存储抽象基类与索引/查询能力。需要说明的是base.py 的导入逻辑 会强制校验alibabacloud_ha3engine_vector是否已安装若缺失将直接抛出ImportError并提示执行pip install alibabacloud_ha3engine_vector。核心配置类 AlibabaCloudOpenSearchConfig 参数详解AlibabaCloudOpenSearchConfig是所有初始化步骤的入口其完整参数定义位于 base.py 的 AlibabaCloudOpenSearchConfig 实现。各参数含义与取值说明如下参数必填默认值说明endpoint是无OpenSearch 实例的访问端点可在阿里云 OpenSearch 控制台查看instance_id是无实例唯一标识例如ha-cn-******同样在控制台获取username是无购买实例时指定的用户名password是无购买实例时设置的密码实例创建后可在控制台修改table_name是无实例配置时指定的数据表名称namespace否若实例开启了 namespace 分区则必须指定该字段名否则查询无法正确执行field_mapping否NoneLlamaIndex 元数据字段名与 OpenSearch 表字段名之间的映射字典当元数据字段名违反 OpenSearch 字段命名规则时使用output_fields否None查询时希望返回的字段列表缺省时自动取field_mapping的值列表并强制追加text_fieldid_field否idOpenSearch 表的主键字段名embedding_field否DEFAULT_EMBEDDING_KEY存储向量的字段名核心默认键为embeddingtext_field否DEFAULT_TEXT_KEY存储正文文本的字段名核心默认键为textsearch_config否None查询行为配置支持order、score_threshold、search_params三个子项详见下文关于字段映射field_mappingOpenSearch 对字段命名有自身规则当 LlamaIndex 侧元数据字段名不合规时可通过field_mapping将其映射为合法的表字段名。从源码实现看该映射是双向维护的写入时async_addLlamaIndex 元数据键通过field_mapping.get(key, key)转换为表字段名读取时aquery通过反向映射inverse_field_mapping由{value: key for key, value in field_mapping.items()}构造将表字段名还原为 LlamaIndex 元数据键。查询配置search_configsearch_config接受一个字典源码中仅消费以下三个键见 _gen_query_requestsearch_config { order: ASC, # 排序方向默认 ASC score_threshold: 0.5, # 分数阈值低于该分数的结果将被过滤 search_params: {...} # 额外的搜索参数会被 JSON 序列化后传入请求 }快速开始从文档构建索引初始化向量存储以下是最小化配置示例与 README.md 及 示例 Notebook 保持一致from llama_index.vector_stores.alibabacloud_opensearch import ( AlibabaCloudOpenSearchStore, AlibabaCloudOpenSearchConfig, ) config AlibabaCloudOpenSearchConfig( endpoint***, instance_idha-cn-******, usernameyour_username, passwordyour_password, table_namellama, ) vector_store AlibabaCloudOpenSearchStore(config)AlibabaCloudOpenSearchStore.__init__内部会使用这些参数构造官方 SDK 客户端self._client client.Client( models.Config( endpointconfig.endpoint, instance_idconfig.instance_id, access_user_nameconfig.username, access_pass_wordconfig.password, ) )加载文档并构建索引from llama_index.core import SimpleDirectoryReader, StorageContext, VectorStoreIndex # 加载本地文档 documents SimpleDirectoryReader(./data/paul_graham).load_data() # 将 OpenSearch 挂载为存储上下文 storage_context StorageContext.from_defaults(vector_storevector_store) # 构建索引文档切分、embedding 与写入 OpenSearch 一气呵成 index VectorStoreIndex.from_documents(documents, storage_contextstorage_context)写入过程由async_add完成见 add 实现其关键行为包括以每批 100 条DEFAULT_BATCH_SIZE 100为单位分批推送避免单次请求体过大每条文档写入id_field主键取node.node_id、embedding_field节点向量、text_field节点文本以及全部元数据字段通过 SDK 的push_documents_async以cmdadd执行 upsert 语义幂等可重复写入任意批次失败会抛出RuntimeError并附带失败详情。连接已有实例并执行查询由于 OpenSearch 是持久化服务索引天然具备持久性。当需要连接一个已写入数据的既有实例时只需用同一份配置重建 Store 与索引from llama_index.core import VectorStoreIndex config AlibabaCloudOpenSearchConfig( endpoint***, instance_id***, usernameyour_username, passwordyour_password, table_namellama, ) vector_store AlibabaCloudOpenSearchStore(config) # 从已有向量构建索引 index VectorStoreIndex.from_vector_store(vector_store) # 构造查询引擎并提问 query_engine index.as_query_engine() response query_engine.query(What did the author study prior to working on AI?) print(response)查询链路最终落在aquery与_gen_query_request见 查询实现仅支持VectorStoreQueryMode.DEFAULT其他查询模式如稀疏、混合检索会抛出ValueError请求体包含table_name、namespace、查询向量、top_k由query.similarity_top_k决定以及output_fields结果解析时优先尝试从_node_content元数据反序列化出完整节点失败则回退为构造仅含文本与元数据的TextNode返回结果包含ids、nodes、similarities分数列表三部分供上层VectorStoreIndex组装最终答案。查询时元数据过滤OpenSearch 向量存储支持在查询时通过标准MetadataFilters进行条件过滤。以下示例取自 示例 Notebook演示了如何先为文档附加自定义元数据再按元数据限制检索范围from llama_index.core import SimpleDirectoryReader, StorageContext, VectorStoreIndex # 依据文件名附加不同的 source_type 元数据 def my_file_metadata(file_name: str): if essay in file_name: source_type essay elif dinosaur in file_name: source_type dinos else: source_type other return {source_type: source_type} md_documents SimpleDirectoryReader( ./data/paul_graham, file_metadatamy_file_metadata ).load_data() md_storage_context StorageContext.from_defaults( vector_storeAlibabaCloudOpenSearchStore(config) ) md_index VectorStoreIndex.from_documents( md_documents, storage_contextmd_storage_context ) # 查询时附加元数据过滤条件 from llama_index.core.vector_stores import MetadataFilter, MetadataFilters md_query_engine md_index.as_query_engine( filtersMetadataFilters( filters[MetadataFilter(keysource_type, valueessay)] ) ) md_response md_query_engine.query(How long it took the author to write his thesis?) print(md_response)过滤条件与算子限制过滤条件由_to_ha3_engine_filter转换为 OpenSearch 可识别的查询串见 过滤转换实现其规则为支持的算子EQ转换为以及GT、GTE、LT、LTE、NEQ等比较算子直接沿用枚举值不支持的算子IN、NIN、TEXT_MATCH、CONTAINS会直接抛出ValueError提示信息为 Alibaba Cloud OpenSearch not support filter operator:in/nin/text_match/containsyet字符串值会被自动加上双引号如source_type essay数值类型保持原样组合条件多个过滤条件通过FilterCondition.AND/FilterCondition.OR拼接分别生成AND与OR连接符。删除数据AlibabaCloudOpenSearchStore提供delete与异步版adelete见 删除实现按文档的ref_doc_id删除先用FetchRequest按doc_idref_doc_id查询命中记录若响应含errorMsg则抛出RuntimeError将命中的记录 id 以cmddelete批量推送删除。源码结构与测试佐证模块文件构成集成包源码结构如下完整目录见 llama-index-vector-stores-alibabacloud-opensearchllama-index-vector-stores-alibabacloud-opensearch/ ├── llama_index/vector_stores/alibabacloud_opensearch/ │ ├── __init__.py # 导出 AlibabaCloudOpenSearchConfig / AlibabaCloudOpenSearchStore │ └── base.py # 核心实现配置类 向量存储类 ├── tests/ │ └── test_vector_stores_alibabacloud_opensearch.py ├── README.md └── pyproject.toml测试用例仓库自带的 测试文件 验证了AlibabaCloudOpenSearchStore正确继承自BasePydanticVectorStoretest_class断言其 MRO 中包含BasePydanticVectorStore即该集成与 LlamaIndex 核心向量存储抽象完全兼容可无缝用于VectorStoreIndex、StorageContext等上层设施。注意事项与已知限制综合源码与示例文档使用该集成时需留意以下几点前置依赖较重必须先拥有可用的 OpenSearch 向量检索版实例并配置好数据表无法离线试用查询模式受限目前仅支持默认向量查询VectorStoreQueryMode.DEFAULT不支持稀疏检索等扩展模式过滤算子受限IN、NIN、TEXT_MATCH、CONTAINS等算子尚未实现涉及集合与文本匹配的过滤需在应用层先行处理namespace 约束若实例启用了 namespace 分区初始化时必须显式传入namespace字段名否则查询会失败异步兼容由于实现依赖asyncio事件循环同步方法通过run_until_complete包装在 Notebook 等已有运行中事件循环的环境里建议像示例那样先执行nest_asyncio.apply()以避免asyncio冲突字段命名合规LlamaIndex 元数据字段若不合 OpenSearch 命名规则务必通过field_mapping建立映射并保证text_field出现在最终output_fields中源码会强制追加。进阶阅读完整实战演练含下载 Paul Graham 语料、构建索引、元数据过滤、连接既有实例AlibabaCloudOpenSearchIndexDemo.ipynb集成包使用说明README.md核心实现源码base.py依赖与版本声明pyproject.toml兼容性测试test_vector_stores_alibabacloud_opensearch.py【免费下载链接】llama_indexLlamaIndex is the leading document agent and OCR platform项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
