使用 LlamaIndex 的 AlibabaCloudMySQLVectorStore 构建 MySQL 向量检索应用【免费下载链接】llama_indexLlamaIndex is the leading document agent and OCR platform项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index本篇技术指南聚焦于 LlamaIndex 生态中的AlibabaCloudMySQLVectorStore阿里云 RDS MySQL 向量存储集成系统讲解其环境前提、安装方式、核心参数、建表结构、增删查改与元数据过滤的完整用法并结合仓库源码剖析其底层实现原理。读者学完后能够直接用阿里云 RDS MySQL 8.0 作为 LlamaIndex 的向量数据库完成文档向量化写入、相似度检索与异步调用等实战任务。背景为什么需要 Alibaba Cloud MySQL 向量存储在 RAG检索增强生成应用中向量数据库负责存储文本块的嵌入向量并执行相似度检索。阿里云 RDS MySQL 在 8.0.36 版本中引入了原生向量类型VECTOR与向量函数如VEC_FromText、VEC_DISTANCE_COSINE使开发者无需额外部署独立的向量数据库即可在已有 MySQL 实例上获得向量检索能力。AlibabaCloudMySQLVectorStore正是这一能力的 LlamaIndex 接入层。它实现了 LlamaIndex 核心库中 BasePydanticVectorStore 抽象基类定义的标准接口add、query、delete、get_nodes、count等并针对阿里云 MySQL 的向量语法做了专门适配。其 API 参考文档位于 alibabacloud_mysql.md类实现位于 base.py。环境前提RDS MySQL 版本与向量能力检查在开始之前请确认你的数据库实例满足以下条件这些约束由源码 base.py 中的_check_vector_support()严格校验必须是阿里云 RDS MySQL 实例初始化时会执行SHOW VARIABLES LIKE rds_release_date检查该变量是否存在非 RDS 实例无法读取该变量会直接报错版本要求 RDS MySQL 8.0.36只有该版本起才提供向量函数支持rds_release_date必须 ≥ 20251031源码中通过int(rds_release_date) 20251031判定低于该发布日期的实例会抛出ValueError向量函数可用初始化时会执行SELECT VEC_FromText([1,2,3]) IS NOT NULL探测VEC_FromText函数是否存在。从源码结构看这套校验被设计为初始化即验证当perform_setupTrue默认值时构造函数会依次执行_connect()、_check_vector_support()与_create_table_if_not_exists()提前暴露环境不兼容问题而不是等到写入数据时才报错。安装通过 pip 安装集成包详见集成包 README.mdpip install llama-index-vector-stores-alibabacloud-mysql该包的依赖声明在 pyproject.toml 中包括llama-index-core0.13.0,0.15sqlalchemy1.4.0,3.0.0pymysql1.0.0同步驱动aiomysql0.2.0异步驱动其中pymysql与aiomysql分别支撑同步与异步两条连接路径SQLAlchemy 负责统一的 ORM 层封装。快速开始创建向量存储实例直接实例化from llama_index.vector_stores.alibabacloud_mysql import ( AlibabaCloudMySQLVectorStore, ) vector_store AlibabaCloudMySQLVectorStore( table_namellama_index_vectorstore, hostyour-instance-endpoint.mysql.rds.aliyuncs.com, port3306, userllamaindex, passwordpassword, databasevectordb, embed_dim1536, # OpenAI 等模型的 embedding 维度 default_m6, # 向量索引的 M 参数HNSW 类索引的每节点连接数 distance_methodCOSINE, # 距离度量COSINE 或 EUCLIDEAN )使用 from_params 类方法from_params与直接构造完全等价仅参数传递方式不同源码 base.pyvector_store AlibabaCloudMySQLVectorStore.from_params( hostyour-instance-endpoint.mysql.rds.aliyuncs.com, port3306, userllamaindex, passwordpassword, databasevectordb, )构造参数详解参数类型默认值说明hoststr必填RDS MySQL 实例连接地址portint必填端口通常为 3306userstr必填数据库用户名passwordstr必填数据库密码构造连接串时经quote_plus转义databasestr必填数据库名table_namestrllama_index_table向量存储表名需符合 SQL 标识符规范见下文参数校验embed_dimint1536嵌入向量维度需为正整数default_mint6向量索引的 M 值需为正整数distance_methodLiteralCOSINE距离度量仅支持COSINE或EUCLIDEAN非法值由 Pydantic 校验拦截perform_setupboolTrue是否自动执行向量能力检查与建表debugboolFalse是否开启 SQLAlchemy 的 SQL 回显echo日志密码安全细节源码在拼装连接串时使用了quote_plus(password)base.py自动转义密码中的特殊字符避免密码包含、:等字符时破坏 URL 连接串的解析。构造参数校验构造函数会对三个关键入参做防御性校验base.pytable_name通过正则^[a-zA-Z_][a-zA-Z0-9_]*$校验只允许字母、数字、下划线且不能以数字开头防止 SQL 注入与非法标识符embed_dim/default_m必须是大于 0 的整数。对应的单元测试见 test_alibabacloud_mysql.py覆盖了合法标识符、数字开头、含连字符/空格/点号等非法场景以及 0、负数、浮点数等非法数值场景。连接机制SQLAlchemy 双引擎架构_connect()方法base.py同时创建两套连接同步引擎使用pymysql驱动create_engine(connection_string, echoself.debug)异步引擎将连接串中的mysqlpymysql://替换为mysqlaiomysql://后用aiomysql驱动创建create_async_engine。这种双引擎设计使得add、query、delete等同步方法与async_add、aquery、adelete等异步方法各自拥有独立的连接池与 session同步/异步场景互不干扰。client属性则暴露底层的同步 SQLAlchemy 引擎未初始化时为None。所有公开方法在调用时都会先执行self._initialize()确保连接与表结构就绪perform_setupFalse时跳过向量检查与建表适用于表已由外部如 DBA预先创建好的场景。自动建表向量表 DDL 结构当perform_setupTrue时初始化阶段会自动执行CREATE TABLE IF NOT EXISTSbase.py生成的表结构如下CREATE TABLE IF NOT EXISTS {table_name} ( id VARCHAR(36) PRIMARY KEY, node_id VARCHAR(255) NOT NULL, text LONGTEXT, metadata JSON, embedding VECTOR({embed_dim}) NOT NULL, INDEX node_id_index (node_id), VECTOR INDEX (embedding) M{default_m} DISTANCE{distance_method} ) ENGINEInnoDB DEFAULT CHARSETutf8mb4 COLLATEutf8mb4_unicode_ci;各字段与索引的含义id自增主键由 MySQL 的UUID()函数在写入时生成node_idLlamaIndex 节点的唯一 ID建有普通索引便于按节点查询/删除textLONGTEXT保存节点原始文本内容metadataJSON类型保存节点元数据含序列化的_node_contentembeddingVECTOR({embed_dim})阿里云 MySQL 原生向量列维度与embed_dim一致VECTOR INDEX ... M{default_m} DISTANCE{distance_method}向量索引M控制索引质量与召回精度DISTANCE与构造参数distance_method保持一致字符集统一为utf8mb4 / utf8mb4_unicode_ci兼容中文等多语言文本。核心操作一写入文档节点add / async_addadd(nodes)将 LlamaIndex 的BaseNode列表写入 MySQLbase.py通过_node_to_table_row()将节点转换为行数据node_id取节点 IDtext取MetadataMode.NONE模式下的纯文本内容embedding取节点向量metadata由node_to_metadata_dict(node, remove_textTrue, flat_metadataFalse)序列化写入时去除冗余文本避免 JSON 膨胀执行INSERT ... VALUES (UUID(), :node_id, :text, VEC_FromText(:embedding), :metadata)其中 embedding 以 JSON 字符串形式传给VEC_FromText解析为向量使用ON DUPLICATE KEY UPDATE实现幂等写入同一node_id重复写入时自动更新text、embedding、metadata适用于索引刷新与增量更新场景返回所有节点的node_id列表。async_add(nodes)与add逻辑一致仅切换为async_session执行base.py。核心操作二相似度检索query / aqueryquery(VectorStoreQuery)执行向量相似度搜索base.pySELECT node_id, text, embedding, metadata, {distance_func}(embedding, VEC_FromText(:query_embedding)) AS distance FROM {table_name} {where_clause} ORDER BY distance LIMIT :limit关键实现点距离函数选择distance_methodCOSINE时使用VEC_DISTANCE_COSINE否则使用VEC_DISTANCE_EUCLIDEAN与建表时的DISTANCE参数保持一致相似度换算底层返回的是距离distance越小越相似代码通过similarity 1 - distance换算为相似度分值base.py并填充进VectorStoreQueryResult结果还原_db_rows_to_query_result()用metadata_dict_to_node()从元数据还原节点对象再set_content()回填文本保证返回的节点可直接用于下游合成base.pyTop-K 限制LIMIT :limit使用query.similarity_top_k控制返回条数。查询模式限制从源码可见query与aquery仅支持VectorStoreQueryMode.DEFAULT传入其他模式如TEXT_SEARCH、HYBRID、MMR等完整枚举见 types.py会抛出NotImplementedError。对应测试见 test_alibabacloud_mysql.py。核心操作三元数据过滤查询时可通过VectorStoreQuery.filters传入MetadataFilters实现结构化过滤源码将其编译为基于 JSON 路径的 SQL 条件from llama_index.core.vector_stores.types import ( MetadataFilter, MetadataFilters, FilterOperator, VectorStoreQuery, ) filters MetadataFilters( filters[ MetadataFilter(keycategory, value技术, operatorFilterOperator.EQ), MetadataFilter(keypriority, value1, operatorFilterOperator.GT), ], conditionand, ) query VectorStoreQuery( query_embedding[0.1, 0.2, ...], similarity_top_k10, filtersfilters, ) result vector_store.query(query)实现细节操作符映射_to_mysql_operator()将 LlamaIndex 的FilterOperator枚举映射为 SQL 操作符——EQ→、GT→、LT→、NE→!、GTE→、LTE→、IN→IN、NIN→NOT IN不支持的操作符记录 warning 后回退为base.pyJSON 字段取值每个过滤条件编译为JSON_VALUE(metadata, $.key) op :param直接对metadataJSON 列取值比较参数化查询所有过滤值均通过 SQLAlchemy 命名占位符:param_N绑定IN/NIN 会展开为多个占位符并用全局计数器保证参数名唯一从机制上杜绝 SQL 注入base.py嵌套组合MetadataFilters支持AND/OR组合且过滤列表中可以嵌套子MetadataFilters自动加括号实现复杂布尔表达式base.py。过滤相关的单测覆盖了操作符映射、IN 展开、AND/OR 组合及 SQL 文本断言见 test_alibabacloud_mysql.py。核心操作四读取、删除与生命周期管理方法同步异步行为说明读取节点get_nodes(node_idsNone, filtersNone)—按node_id IN (...)参数化查询并还原节点不传node_ids时返回全表节点base.py按文档删除delete(ref_doc_id)adelete(ref_doc_id)通过JSON_EXTRACT(metadata, $.ref_doc_id) :doc_id删除某来源文档的全部节点base.py按节点删除delete_nodes(node_ids)adelete_nodes(node_ids)按node_id IN (...)参数化批量删除base.py统计数量count()—执行SELECT COUNT(*)返回表内节点总数base.py清空数据clear()aclear()DELETE FROM清空全部行base.py删除表drop()—DROP TABLE IF EXISTS随后自动close()释放资源base.py关闭连接close()aclose()释放同步与异步引擎close()针对运行中事件循环做了特殊处理base.py上述方法的同步/异步配对与 LlamaIndexBasePydanticVectorStore的接口约定一致异步版本是对同步逻辑的完整封装。与 LlamaIndex 索引无缝集成将AlibabaCloudMySQLVectorStore接入标准 RAG 流程只需在构建索引时通过StorageContext注入向量存储from llama_index.core import VectorStoreIndex, StorageContext from llama_index.core.node_parser import SentenceSplitter from llama_index.core import SimpleDirectoryReader # 1. 加载并切分文档 documents SimpleDirectoryReader(data).load_data() nodes SentenceSplitter(chunk_size512).get_nodes_from_documents(documents) # 2. 构建向量存储 vector_store AlibabaCloudMySQLVectorStore( hostyour-instance-endpoint.mysql.rds.aliyuncs.com, port3306, userllamaindex, passwordpassword, databasevectordb, table_namellama_index_vectorstore, embed_dim1536, ) # 3. 创建索引并写入 storage_context StorageContext.from_defaults(vector_storevector_store) index VectorStoreIndex(nodes, storage_contextstorage_context) # 4. 查询 query_engine index.as_query_engine(similarity_top_k5) response query_engine.query(你的问题)该集成包遵循 LlamaIndex 的标准 Vector Store 协议stores_textTrue、is_embedding_queryTrue见 base.py 与 types.py因此VectorStoreIndex、RetrieverQueryEngine等上层组件可以直接使用无需任何适配代码。测试文件 test_vector_stores_alibabacloud_mysql.py 亦验证了该类的 MRO 继承自BasePydanticVectorStore。质量保障测试与验证集成包附带两套测试单元测试test_alibabacloud_mysql.py1180 行通过 mock 会话隔离数据库依赖覆盖参数校验、向量支持检查含 4 种失败分支、操作符映射、过滤子句构建、查询结果还原、SQL 文本断言等集成测试test_vector_stores_alibabacloud_mysql.py验证类的继承关系。README 说明集成测试需要真实可用的、支持向量检索的阿里云 MySQL 实例环境不满足时测试会自动跳过pytest -v即可运行。使用建议与注意事项版本先行务必确认实例满足 RDS MySQL 8.0.36 且rds_release_date 20251031否则初始化即抛错可在阿里云控制台或通过SHOW VARIABLES LIKE rds_release_date提前核验向量维度一致性embed_dim必须与所选 embedding 模型的输出维度严格一致如 OpenAItext-embedding-3-small为 1536 维建表后维度不可变更需要重建表才可调整距离度量选择COSINE适合绝大多数语义检索场景且对向量归一化不敏感EUCLIDEAN适合距离含义明确的场景需在初始化时与建表 DDL 一并确定过滤走 JSON 路径元数据过滤通过JSON_VALUE提取字段嵌套 JSON 的键路径为$.key键名中若含特殊字符需注意转义查询模式受限当前仅支持DEFAULT向量检索模式混合检索hybrid、MMR 等高级模式需等待后续版本或自行扩展幂等写入add依赖ON DUPLICATE KEY UPDATE重复索引同一文档会覆盖旧数据而非报错适合增量刷新场景生产环境关闭 debugdebugTrue会开启 SQLAlchemy 的 SQL 回显仅用于本地排障生产环境应保持默认的False。通过本指南你已经可以在不引入额外向量数据库的前提下利用阿里云 RDS MySQL 的能力支撑起完整的 LlamaIndex RAG 应用并理解其背后从连接建立、向量建表到相似度检索的完整实现链路。【免费下载链接】llama_indexLlamaIndex is the leading document agent and OCR platform项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考