使用 llama-index-readers-singlestore 从 SingleStore 加载向量相似文档【免费下载链接】llama_indexLlamaIndex is the leading document agent and OCR platform项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index本文聚焦 LlamaIndex 生态中的SingleStoreReader位于llama-index-readers-singlestore集成包讲解如何通过点积向量检索从 SingleStore 数据库的指定表中按语义相似度读取文档。读完本文后你将掌握该 Reader 的安装方式、全部构造参数含义、底层 SQL 检索原理以及如何将它嵌入到基于 LlamaIndex 的 RAG 数据加载链路中。概览SingleStoreReader 是什么SingleStoreReader是 LlamaIndex 面向 SingleStore原 MemSQL数据库封装的一个 Reader职责非常明确给定一个查询向量embedding从 SingleStore 的某张表中检索出与之最相似的top_k行并把每一行封装成llama_index.core.schema.Document返回。该实现的核心源码位于 llama-index-integrations/readers/llama-index-readers-singlestore/llama_index/readers/singlestore/base.py其导出入口在 llama-index-integrations/readers/llama-index-readers-singlestore/llama_index/readers/singlestore/init.py对外只暴露SingleStoreReader一个类。从类继承关系看SingleStoreReader直接继承自llama_index.core.readers.base.BaseReader这意味着它与 LlamaIndex 的索引构建、加载管线天然兼容同时它的数据加载能力实际委托给同一仓库中的DatabaseReader见 llama-index-integrations/readers/llama-index-readers-database/llama_index/readers/database/base.py因此也继承了DatabaseReader统一的查询执行与 Document 构造机制。在集成包的 pyproject.toml 中可以看到其依赖被声明为llama-index-readers-database0.5.0,0.6底层数据库 Readerpymysql1.1.0,2Python 连接 MySQL 协议SingleStore 兼容 MySQL 协议的驱动llama-index-core0.13.0,0.15LlamaIndex 核心框架Python 版本要求3.10,4.0。包的关键字为memsql与singlestore维护方为 singlestore。安装与前提条件安装在任意虚拟环境中执行pip install llama-index-readers-singlestore该命令会同时拉取上述三个依赖包。如果你需要后续构建索引通常还需要一并安装向量存储相关的包见下文“与向量存储的配合”。数据前提使用前你的 SingleStore 数据库中需要有一张已经写入文本内容与对应向量的表典型结构如下列名可通过参数自定义CREATE TABLE table_name ( id BIGINT PRIMARY KEY, text TEXT, -- 文档原文content_field embedding BLOB -- 序列化后的向量vector_field );其中embedding列存放的是向量数据。SingleStore 支持向量点积检索配合JSON_ARRAY_PACK_F64可以把 JSON 格式的浮点数组打包成二进制向量参与计算详见下文“底层 SQL 原理”。初始化构造参数详解SingleStoreReader的构造函数签名如下源码 base.pySingleStoreReader( scheme: str, host: str, port: str, user: str, password: str, dbname: str, table_name: str, content_field: str text, vector_field: str embedding, )参数类型必填默认值含义schemestr是无数据库连接 scheme方言SingleStore 走 MySQL 协议一般填mysqlhoststr是无数据库主机地址如localhost或云实例端点portstr是无数据库端口如3306注意是字符串类型userstr是无数据库用户名passwordstr是无数据库密码dbnamestr是无数据库名称table_namestr是无要检索的表名content_fieldstr否text存放文档文本内容的列名vector_fieldstr否embedding存放向量数据的列名构造时SingleStoreReader会执行两个关键步骤注册 PyMySQL 驱动别名代码中尝试import pymysql并调用pymysql.install_as_MySQLdb()见 base.py。这会让 SQLAlchemy 在使用mysqldb方言时也能走 PyMySQL确保连接层兼容若导入失败则静默跳过except ImportError: pass。创建内部 DatabaseReader将scheme/host/port/user/password/dbname透传给DatabaseReader由其在内部拼接 SQLAlchemy URI 并建立连接DatabaseReader的 URI 拼接逻辑见 llama-index-integrations/readers/llama-index-readers-database/llama_index/readers/database/base.pyuri f{scheme}://{user}:{password}{host}:{port}/{dbname} self.sql_database SQLDatabase.from_uri(uri, ...)因此在传参时scheme/host/port/user/password/dbname必须全部提供且非空否则DatabaseReader会抛出ValueError提示必须提供 SQLDatabase、Engine、URI 或完整凭据。检索文档load_data 的使用方式load_data是 Reader 对外暴露的检索接口源码 base.pydef load_data(self, search_embedding: str, top_k: int 5) - List[Document]:search_embedding查询向量的字符串表示形如[0.3, 0.3, 0.3, ...]的 JSON 数组文本top_k返回最相似的文档数量默认5返回值List[Document]每个Document对应表中的一个相似行。完整示例官方 README见 llama-index-integrations/readers/llama-index-readers-singlestore/README.md给出的用法如下from llama_index.readers.singlestore import SingleStoreReader # 使用你的 SingleStore 数据库凭据初始化 Reader reader SingleStoreReader( schememysql, hostlocalhost, port3306, userusername, passwordpassword, dbnamedatabase_name, table_nametable_name, content_fieldtext, vector_fieldembedding, ) # search_embedding 是查询文本的 embedding 表示。 # 示例 # search_embedding[0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3] search_embedding [n1, n2, n3, ...] # load_data 从 SingleStore 中取回与 search_embedding 相似的文档。 # top_k 参数指定取回的文档数量。 documents reader.load_data(search_embeddingsearch_embedding, top_k5)实际接入时search_embedding一般由 LlamaIndex 的 Embedding 模型对查询文本编码产生例如from llama_index.core import Settings query_embedding Settings.embed_model.get_query_embedding(你的查询问题) documents reader.load_data(search_embeddingquery_embedding, top_k5)documents随后可以直接作为Document列表传入索引构建或VectorStoreIndex.from_documents进入后续的检索与生成流程。返回结果说明load_data最终调用DatabaseReader.load_data(queryquery)其内部流程为执行 SQL → 逐行把结果组装成Document文本内容为各列col: value的拼接默认不额外提取 metadata具体见 database/base.py。也就是说每一行数据都会成为一个独立的Document其文本内容包含该行全部列的值包括向量列。如果你希望控制哪些列进入正文或元数据可以参考DatabaseReader提供的metadata_cols、excluded_text_cols、document_id等高级参数进行扩展。底层 SQL 原理点积检索如何工作load_data内部构造的 SQL 是理解本 Reader 的关键源码 base.pySELECT {content_field}, DOT_PRODUCT_F64({vector_field}, JSON_ARRAY_PACK_F64({search_embedding})) AS score FROM {table_name} ORDER BY score DESC LIMIT {top_k}逐一拆解JSON_ARRAY_PACK_F64([...])把 JSON 格式的浮点数组字符串打包为 SingleStore 内部的二进制向量。这是search_embedding必须传字符串形式的原因——它会被直接嵌入 SQL 的引号中DOT_PRODUCT_F64(vector_col, packed_query)计算表内每行vector_field列与查询向量之间的双精度浮点点积。点积越大表示方向越接近要求向量已归一化因此作为相似度分数ORDER BY score DESC LIMIT top_k按分数降序取前top_k行实现“Top-K 相似文档”检索。该 SQL 在 DatabaseReader 中通过 SQLAlchemytext()执行。两点使用注意向量需要归一化点积相似度严格成立的前提是向量已归一化此时点积等于余弦相似度。若你的 embedding 未归一化建议在写入前或在生成查询向量时做归一化处理top_k应为正整数它直接拼入LIMIT子句传入 0 或负数会导致 SQL 无有效返回。与 SingleStore 向量存储的配合在 LlamaIndex 的集成体系中SingleStoreReader负责“从 SingleStore 读回相似文档”而写入侧则通常由llama-index-vector-stores-singlestoredb完成源码位于 llama-index-integrations/vector_stores/llama-index-vector-stores-singlestoredb。一个典型的端到端流程是用SingleStoreVectorStore将文档的 embedding 与文本写入 SingleStore 表查询阶段用SingleStoreReader.load_data(search_embedding, top_k)按相似度召回文档将召回结果交给 LlamaIndex 的 Response Synthesizer 生成最终回答。测试与代码质量验证集成包的测试文件 tests/test_readers_singlestore.py 验证了类的继承关系from llama_index.core.readers.base import BaseReader from llama_index.readers.singlestore import SingleStoreReader def test_class(): names_of_base_classes [b.__name__ for b in SingleStoreReader.__mro__] assert BaseReader.__name__ in names_of_base_classes该用例断言SingleStoreReader的 MRO 中包含BaseReader从测试层面确认了它符合 LlamaIndex 统一的 Reader 抽象可在标准加载流程中使用。运行方式cd llama-index-integrations/readers/llama-index-readers-singlestore pytest tests/使用限制与注意事项连接参数必须完整scheme/host/port/user/password/dbname六个参数缺一不可内部才会尝试拼接 URI依赖 MySQL 协议SingleStore 兼容 MySQL 协议但端口、账号权限需以你的 SingleStore 实例实际配置为准pyproject.toml声明的pymysql版本范围为1.1.0,2SQL 拼接方式table_name、content_field、vector_field直接拼入 SQL生产环境请使用可信的固定表名/列名避免将不可信的外部输入作为这些参数未内置连接池每次load_data通过DatabaseReader建立的连接执行查询高频调用场景建议在应用层做好连接复用或缓存策略。小结SingleStoreReader以极小的封装面把 SingleStore 的向量点积检索能力无缝接入了 LlamaIndex 的 Document 管线通过 6 个连接参数加 2 个列名参数完成初始化调用一次load_data(search_embedding, top_k)即可拿到排序后的相似文档列表。其底层 SQL 使用的DOT_PRODUCT_F64与JSON_ARRAY_PACK_F64是 SingleStore 向量检索的原生能力配合llama-index-vector-stores-singlestoredb即可搭建“写入—检索—生成”完整的 RAG 闭环。【免费下载链接】llama_indexLlamaIndex is the leading document agent and OCR platform项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考