★ FEATURED ARTICLE 人工智能RAG大模型【免费下载链接】llama_indexLlamaIndex is the document processing platform for AI项目地址https://gitcode.com/GitHub_Trending/ll/llama_index点击查看免费下载本篇技术指南以 LlamaIndex API 参考文档 中定义的TencentVectorDB向量存储为核心系统讲解如何在 LlamaIndex 中接入腾讯云向量数据库Tencent Cloud VectorDB从环境准备、Collection 配置参数详解到文档写入、相似度检索、元数据过滤与删除的完整实战流程并深入源码剖析其底层实现原理。读完本文你将掌握用TencentVectorDB作为持久化向量存储、构建可检索 RAG 知识库的完整技术方案。一、TencentVectorDB 集成概览腾讯云向量数据库Tencent Cloud VectorDB是腾讯云提供的全托管分布式向量数据库服务专为多维向量数据的存储、检索与分析设计支持多种索引类型与相似度计算方法。在 LlamaIndex 的生态中llama-index-vector-stores-tencentvectordb是其官方集成包将 TencentVectorDB 封装为标准的BasePydanticVectorStore使它可以无缝融入 LlamaIndex 的索引、检索与查询引擎体系。从官方 Vector Stores 特性对照表 可以看到TencentVectorDB被标记为cloud类型托管向量库并完整支持Metadata Filtering元数据过滤、Hybrid Search混合检索、Delete删除与Store Documents文档存储四项核心能力。该集成包位于仓库llama-index-integrations/vector_stores/llama-index-vector-stores-tencentvectordb/目录下核心实现只有一个文件base.py公开的顶层 API 为TencentVectorDB、CollectionParams、FilterField三个类见init.py。二、环境准备与安装1. 前置条件一个可访问的腾讯云向量数据库实例官方文档地址https://cloud.tencent.com/document/product/1709/94951。用于接入的url数据库访问地址与keyAPI Key。Python 3.10 环境由pyproject.toml的requires-python 3.10,4.0约束。2. 安装依赖pip install llama-index-vector-stores-tencentvectordb该包会自动拉取核心依赖。根据pyproject.toml的声明其依赖为llama-index-core0.13.0,0.15—— LlamaIndex 核心框架tcvectordb1.3.13,2—— 腾讯云向量数据库官方 Python SDK。3. 引入方式from llama_index.vector_stores.tencentvectordb import ( TencentVectorDB, CollectionParams, FilterField, )如果tcvectordb未安装源码中的_try_import()会抛出明确提示见 base.py请先执行pip install tcvectordb。三、核心概念Collection 与参数配置TencentVectorDB 的数据组织单位是Collection集合所有嵌入向量与文档都存放在 Collection 中。TencentVectorDB在初始化时会自动创建数据库与 Collection如果它们不存在。1. CollectionParams集合配置CollectionParams是创建/连接 Collection 时的参数载体源码定义见 base.py。参数说明如下参数默认值说明dimension必填向量维度需与 Embedding 模型输出维度一致如 OpenAI text-embedding-ada-002 为 1536collection_namellama_default_collection集合名称collection_descriptionCollection for llama index集合描述shard1集合的分片数replicas2集合的副本数index_typeHNSW索引类型HNSW、IVF_FLAT、IVF_PQ、IVF_SQ8等metric_typeCOSINE距离度量L2、COSINE、IPdrop_existsFalse若为True删除已存在的同名 Collection 后重建vector_paramsNone索引专属参数见下文filter_fields[]过滤字段列表List[FilterField]用于查询时的元数据过滤vector_params 的取值规则对应源码_get_index_params方法见 base.pyHNSW{M: 16, efConstruction: 200}M默认 16efConstruction默认 200IVF_FLAT / IVF_SQ8{nlist: 128}IVF_PQ{M: 16, nlist: 128}M默认 16IVF_SQ4 / IVF_SQ16同样使用nlist默认 128。2. FilterField过滤字段FilterField用于声明集合中的标量过滤字段构造参数为name字段名与data_type字段类型string或uint64默认string见 base.py。filter_fields [ FilterField(namesource_type), FilterField(nameage, data_typeuint64), ]声明为过滤字段后写入文档时会将该元数据单独落为集合中的独立标量列从而在查询时可以使用范围、in等复杂条件过滤。典型应用方式源码 docstring 中的示例store.add([TextNode(..., metadata{age: 23, name: name1})]) ... query VectorStoreQuery(...) store.query(query, filterage 20 and age 40 and name in (\name1\, \name2\))四、快速上手创建索引并查询以下是官方示例 TencentVectorDBIndexDemo.ipynb 的完整最小流程。1. 加载文档from llama_index.core import ( VectorStoreIndex, SimpleDirectoryReader, StorageContext, ) documents SimpleDirectoryReader(./data/paul_graham).load_data() print(fTotal documents: {len(documents)})2. 初始化 TencentVectorDBfrom llama_index.vector_stores.tencentvectordb import TencentVectorDB from llama_index.vector_stores.tencentvectordb import CollectionParams vector_store TencentVectorDB( urlhttp://10.0.X.X, # 你的数据库访问地址 keyeC4bLRy2va******************************, # 你的 API Key collection_paramsCollectionParams(dimension1536, drop_existsTrue), )注意url与key是必填参数见 base.py 的构造函数签名。示例中的地址与密钥均为占位演示值请替换为你自己的实例信息。3. 构建索引并写入数据storage_context StorageContext.from_defaults(vector_storevector_store) index VectorStoreIndex.from_documents(documents, storage_contextstorage_context)这一步在底层完成了三件事将文档切分为 chunk即 Node、为每个 Node 计算嵌入向量、并把嵌入与文本批量 upsert 进腾讯云向量数据库。4. 查询query_engine index.as_query_engine() response query_engine.query(Why did the author choose to work on AI?) print(response)5. MMR 模式查询腾讯云向量数据库还支持以 MMR最大边际相关性模式检索在保证相关性的同时让返回的多个 chunk 之间差异尽可能大从而为答案生成提供更广的上下文query_engine index.as_query_engine(vector_store_query_modemmr) response query_engine.query(Why did the author choose to work on AI?) print(response)五、源码级解析写入、检索与删除的底层实现TencentVectorDB继承自BasePydanticVectorStore见 llama-index-core 的 vector_stores/types.py声明了stores_text: bool True表示该存储会保留文档原文。1. add()节点写入add()方法base.py将List[BaseNode]转换为腾讯云 SDK 的Document对象主键node.node_id→ 集合的id字段来源文档node.ref_doc_id→ 写入doc_id字段对应 LlamaIndex 的DEFAULT_DOC_ID_KEY元数据整体json.dumps序列化后存入metadata字段同时声明的filter_fields会被提取为独立的标量字段文本内容TextNode.text写入text字段DEFAULT_TEXT_KEY。写入按batch_size默认512分批调用collection.upsert(documents..., build_indexTrue, timeout30)。build_indexTrue表示写入时同步构建索引。2. query()相似度检索query()方法base.py接收核心类型VectorStoreQuery定义于 types.py其关键字段包括query_embedding查询向量similarity_top_k返回 Top K 结果doc_ids按 doc_id 过滤filtersMetadataFilters元数据过滤output_fields返回字段。底层调用collection.search()返回结果被还原为TextNode对象含id_、text、embedding、metadata并通过NodeRelationship.SOURCE关联回来源文档最终组装成VectorStoreQueryResult(nodes, similarities, ids)。相似度分数取自返回结果的score字段。3. delete()按来源文档删除delete()方法base.py以ref_doc_id为删除单位支持传入单个字符串或字符串列表内部通过Filter(Filter.In(doc_id, delete_ids))构造过滤条件一次性删除同一来源文档的所有节点。这在语义上非常合理应当以文档而非单个节点作为删除单元。4. 其他管理方法query_by_ids(ids)按节点 id 批量查询原始文档truncate()清空当前 Collectiondescribe_collection()查看集合元信息client属性直接暴露底层的VectorDBClient便于做高级操作。六、元数据过滤实战腾讯云向量数据库的过滤能力在 LlamaIndex 中通过两种方式暴露1. 使用 LlamaIndex 标准 MetadataFilters创建带过滤字段的集合并在写数据时给文档附加元数据from llama_index.core.vector_stores import MetadataFilters, ExactMatchFilter filter_fields [FilterField(namesource_type)] md_storage_context StorageContext.from_defaults( vector_storeTencentVectorDB( urlhttp://10.0.X.X, keyeC4bLRy2va******************************, collection_paramsCollectionParams( dimension1536, drop_existsTrue, filter_fieldsfilter_fields ), ) ) md_index VectorStoreIndex.from_documents( md_documents, storage_contextmd_storage_context ) md_query_engine md_index.as_query_engine( filtersMetadataFilters( filters[ExactMatchFilter(keysource_type, valueessay)] ) ) response md_query_engine.query(How long it took the author to write his thesis?) print(response.response)2. 底层实现过滤条件的三种来源从源码_to_vdb_filter()base.py可以看出过滤条件的优先级kwargs[filter]直接传入腾讯云 SDK 的Filter对象或过滤表达式字符串表达能力最强例如age 20 and age 40 and name in (\name1\, \name2\)query.filters将 LlamaIndex 的MetadataFilters转换为key value形式的等值条件并用and连接query.doc_ids退化为doc_id in (...)过滤。需要说明的是query.filters路径legacy_filters()见 types.py目前仅支持等值匹配FilterOperator.EQ类过滤更复杂的范围、in等条件需走kwargs[filter]传入原生过滤表达式。七、连接已有集合与删除文档由于腾讯云向量数据库本身是持久化服务重启进程后数据依然存在。要连接一个此前创建并填充过的集合只需将drop_exists设为False默认值再从现有向量构建索引即可new_vector_store TencentVectorDB( urlhttp://10.0.X.X, keyeC4bLRy2va******************************, collection_paramsCollectionParams(dimension1536, drop_existsFalse), ) # 从已有向量构建索引不重新写入数据 new_index_instance VectorStoreIndex.from_vector_store(vector_storenew_vector_store) query_engine index.as_query_engine(similarity_top_k5) response query_engine.query(What did the author study prior to working on AI?)删除文档时先通过 Retriever 拿到节点再以ref_doc_id为单位删除retriever new_index_instance.as_retriever( vector_store_query_modemmr, similarity_top_k3, vector_store_kwargs{mmr_prefetch_factor: 4}, ) nodes_with_scores retriever.retrieve(What did the author study prior to working on AI?) # 删除整个来源文档所有节点共享同一个 ref_doc_id new_vector_store.delete(nodes_with_scores[0].node.ref_doc_id)删除后再次检索同一问题返回节点数为 0证明数据已从集合中移除。八、进阶配置初始化参数与一致性控制TencentVectorDB的构造函数还提供了几个实用参数base.py参数默认值说明url必填数据库实例访问地址key必填API Keyusernameroot数据库用户名database_namellama_default_database数据库名不存在则自动创建read_consistencyeventualConsistency读一致性级别可选strongConsistency/eventualConsistencybatch_size512批量写入的每批文档数collection_paramsCollectionParams(dimension1536)集合配置几点实现细节值得注意读一致性校验_init_client()会对read_consistency做严格枚举校验传入非法值会抛出ValueError并提示合法取值集合见 base.py。集合命名规则当使用自定义database_name但未自定义collection_name时集合名会自动生成为{database_name}_llama_default_collection避免与默认库中的集合冲突见_compute_collection_namebase.py。索引类型/度量类型校验index_type与metric_type都会映射到 SDK 枚举并做非法值检查metric_type会自动转大写处理。统一超时所有客户端操作使用统一的timeout30秒DEFAULT_TIMEOUT。类工厂方法from_params()提供与构造函数完全一致的参数入口并预先执行_try_import()依赖检查推荐在延迟导入场景下使用。九、测试与验证集成包的测试位于 test_vector_stores_tencentvectordb.py覆盖了两个关键点类型体系正确性TencentVectorDB的 MRO 中必须包含BasePydanticVectorStore确保其作为标准向量存储可被 LlamaIndex 索引体系直接使用filter_fields 属性可访问性验证CollectionParams的filter_fields属性可正常访问、可迭代该测试对应修复了 Issue #19675 中 filter_fields 无法访问的问题并验证空 filter_fields 场景不会引发AttributeError。可以通过以下命令在集成包目录下运行测试pytest llama-index-integrations/vector_stores/llama-index-vector-stores-tencentvectordb/tests/十、最佳实践小结维度务必匹配CollectionParams(dimension...)必须与 Embedding 模型的输出维度一致如 OpenAI 1536、部分中文模型 1024/768否则写入会失败。drop_exists 的取舍开发调试阶段可用drop_existsTrue快速重建集合生产环境应保持False避免误删数据。删除以文档为单位始终通过ref_doc_id删除不要逐个删节点。复杂过滤走原生表达式范围比较、多值in等条件优先通过query(..., filter...)传入简单等值过滤可直接用MetadataFilters。关注批量写入默认batch_size512大批量写入时可通过调整该值平衡吞吐与单次请求耗时。结合官方示例 TencentVectorDBIndexDemo.ipynb 与核心实现 base.py你可以快速将腾讯云向量数据库打造为自己的 RAG 知识库持久层享受云端托管、高吞吐与毫秒级检索的完整能力。赞分享人工智能RAG大模型【免费下载链接】llama_indexLlamaIndex is the document processing platform for AI项目地址https://gitcode.com/GitHub_Trending/ll/llama_index点击查看免费下载相关推荐LlamaIndex 集成 Bagel 向量数据库BagelVectorStore 实战指南LlamaIndex 集成 Bagel 向量数据库BagelVectorStore 实战指南 导读 本文围绕 LlamaIndex 官方集成包 llama i人工智能RAG大模型Chroma 与 LangChain、LlamaIndex 集成实战AI-Research-SKILLs 中的向量数据库接入指南Chroma 与 LangChain、LlamaIndex 集成实战AI Research SKILLs 中的向量数据库接入指南 本指南以 Chroma 集成AI 技能人工智能大模型深度学习LlamaIndex 集成 TiDB 向量存储TiDBVectorStore 实战指南LlamaIndex 集成 TiDB 向量存储TiDBVectorStore 实战指南 导读 本文围绕 LlamaIndex 的 TiDBVectorStor人工智能RAG大模型上一篇如何彻底解决ComfyUI-SUPIR内存访问冲突3种高效优化方案下一篇幻兽帕鲁存档编辑终极指南如何安全修改游戏数据而不损坏存档创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
