txtai Embeddings 方法全解析从索引构建到语义搜索的完整 API 指南【免费下载链接】txtai All-in-one AI framework for semantic search, LLM orchestration and language model workflows项目地址: https://gitcode.com/GitHub_Trending/tx/txtaitxtai 的 Embeddings 是驱动语义搜索的核心引擎数据被转换为 embeddings 向量含义相近的概念会得到相近的向量从而让检索结果“语义相关”而非仅仅“关键词相同”。本文以官方文档 docs/embeddings/methods.md 为主体结合 Embeddings 源码 与 indexing.md、query.md 等配套指南系统讲解Embeddings类的构造、索引、搜索、更新删除、持久化与资源管理等全部核心方法读完即可在自己的项目中构建、保存并检索一个可用的语义搜索引擎。快速上手构建并搜索一个 Embeddings 索引先看一个最小可运行示例它完整演示了“创建实例 → 索引数据 → 语义搜索”三步流程也是理解后续所有方法的起点。from txtai import Embeddings # 创建 embeddings 模型底层由 sentence-transformers transformers 驱动 embeddings Embeddings(pathsentence-transformers/nli-mpnet-base-v2) data [ US tops 5 million confirmed virus cases, Canadas last fully intact ice shelf has suddenly collapsed, forming a Manhattan-sized iceberg, Beijing mobilises invasion craft along coast as Taiwan tensions escalate, The National Park Service warns against sacrificing slower friends in a bear attack, Maine man wins $1M from $25 lottery ticket, Make huge profits without work, earn up to $100,000 a day ] # 索引文本列表 embeddings.index(data) print(f{Query:20} Best Match) print(- * 50) # 对每个查询执行语义搜索 for query in (feel good story, climate change, public health story, war, wildlife, asia, lucky, dishonest junk): # 取第一条结果的 uid # search 结果格式: (uid, score) uid embeddings.search(query, 1)[0][0] # 打印命中的原文 print(f{query:20} {data[uid]})这段代码演示了 txtai 语义搜索的核心价值feel good story会命中彩票中奖的新闻climate change会命中冰架坍塌的报道dishonest junk会命中诈骗广告——检索依据是语义而非字面关键词。Build配置驱动的 Embeddings 实例构造Embeddings实例是配置驱动的构造函数接受一个配置字典也可全部以关键字参数传入。从源码看构造函数会合并config与kwargs为单一字典再调用configure()加载各类模型组件def __init__(self, configNone, modelsNone, **kwargs): # 合并配置 config {**config, **kwargs} if config and kwargs else kwargs if kwargs else config # 设置初始配置并加载配置驱动的模型 self.configure(config)上面示例通过 path 参数指定了具体的向量模型。也可以创建一个不带任何配置的实例embeddings Embeddings()此时当加载和检索数据时会使用默认的 transformers 向量模型sentence-transformers/all-MiniLM-L6-v2对数据做向量化。这一点在源码 base.py 的 defaults 方法中有明确体现当没有显式模型且允许默认值时会写入self.config[path] sentence-transformers/all-MiniLM-L6-v2。向量模型的选型建议可参考模型指南。从源码结构看一个Embeddings实例会按需挂载以下组件对应 base.py 的初始化清单属性作用model稠密向量模型将数据转换为相似度向量ann近似最近邻ANN索引存储稠密向量database文档数据库存储文档原文内容scoring稀疏向量/关键词索引BM25、TF-IDF、SPLADE 等graph语义图网络indexes子索引subindexes也是 embeddings 数据库ids关闭内容存储时的 indexid→id 映射query查询翻译模型把自然语言查询转成 SQLIndex向索引添加数据创建实例后下一步就是写入数据embeddings.index(rows)index方法接受一个可迭代对象其中每个元素支持三种格式(id, data, tags)—— 默认处理格式元素说明id唯一记录 iddata待索引的输入数据可以是文本、字典或对象tags可选的标签字符串用于在索引时标记/标注数据(id, data)—— 同上但没有 tags。data—— 单一元素。此时会自动生成唯一 id。注意对于自动生成的 id后续的 upsert 和 delete 调用需要先执行一次搜索来拿到目标 id。当data是字典时文本通过text键传入二进制对象通过object键传入。需要特别注意的是必须开启 content 才能存储元数据开启 objects 才能存储二进制对象如果提供了id和tags键也会被自动提取。输入可迭代对象可以是列表或生成器generator。对于非常大的数据集生成器能显著降低内存占用因为任意时刻只有一部分数据驻留内存。索引的更多细节向量化、后端设置、稀疏向量、子索引等参见索引指南。从源码看index内部流程base.py#L103-L153大致为初始化索引 → 用Stream流式读取文档 → 用Transform将文档写入数据库并转为向量结果暂存到临时.npy文件→ 可选执行 PCA 降维 → 创建 ANN 并把向量灌入 → 再依次索引稀疏评分、子索引与图网络。因此一次index调用是“全量重建”语义它会覆盖已有索引。Search执行语义查询数据索引完成后即可检索embeddings.search(query, limit)search方法接收两个参数查询语句与结果条数限制。返回结果的格式取决于是否开启 content 存储未存储内容时返回(id, score)元组列表存储内容时返回{**query columns}字典列表包含查询中涉及的全部列自然语言查询与 SQL 查询都被支持。简单自然语言查询示例embeddings.search(feel good story) embeddings.search(wildlife)开启内容存储后还能使用带过滤条件的 SQLSELECT text, flag, actiondate FROM txtai WHERE similar(query) AND flag 1 AND actiondate 2022-01-01关于similar()子句、绑定参数、聚合查询、自定义 SQL 函数、混合检索权重、图检索与子索引查询的完整说明见查询指南。从搜索执行源码search/base.py可以看清查询分派逻辑当存在图网络且查询是图语句时走图搜索否则若未强制索引搜索且有数据库则走“索引 数据库”联合搜索先做相似度检索拿到候选 id再注入数据库查询完成过滤其余情况走纯向量索引搜索稀疏、稠密或两者加权融合的 hybrid 搜索。limit默认值为 3hybrid 权重默认值为 0.5。批量查询与index对应search也提供了批量版本batchsearch(queries, limit, weights, index, parameters, graph)一次调用可处理多条查询返回按查询分组的嵌套列表。源码中search就是batchsearch对单条查询的封装base.py#L356-L376。增删改upsert、delete 与 reindexUpsert插入或更新记录embeddings.upsert(documents)upsert在索引已存在时把新数据追加进索引、已存在的数据更新若索引尚不存在或为空则退化为标准index操作源码见 base.py#L166-L169。与index的全量重建不同upsert不需要重建整个索引。Delete删除记录embeddings.delete(ids)delete接收 id 列表并返回实际删除的 id 列表base.py#L203-L258。从源码看有数据库时先从数据库查询 indexid→id 映射再删除数据库记录没有数据库时则在ids映射中按 id 反查内部索引位置随后依次对 ANN、稀疏评分、子索引和图网络执行删除。Reindex换模型/换后端重索引开启内容存储后可以调用reindex用新配置重建索引——例如把后端从 faiss 切换为 hnsw或更换向量模型而无需回到原始数据embeddings.reindex(pathsentence-transformers/all-MiniLM-L6-v2, backendhnsw)源码base.py#L260-L290会保留原有的content与objects配置以确保数据库得以复用从已存文档重新向量化并建索引。其他常用方法除上述主流程外Embeddings还提供以下实用方法均可从 base.py 中查看实现transform(document, category, index)/batchtransform(documents, ...)把单个/多个文档转换为 embeddings 向量支持指令式嵌入的category参数与子索引的index参数。similarity(query, data)/batchsimilarity(queries, data)计算查询与一组数据的相似度返回按得分降序的(id, score)列表id 即数据在列表中的下标。实现上利用归一化向量的点积等价于余弦相似度base.py#L441-L445。explain(query, texts, limit)解释查询中每个输入 token 的重要程度分数越高越相关需要开启内容存储或显式传入texts。terms(query)/batchterms(queries)把查询缩减为关键词项常用于稀疏检索场景。count()返回索引中的元素总数按 ANN、scoring、database、ids 的顺序择一计算。info()以 JSON 打印当前索引的完整配置便于调试。资源管理上下文管理器与 closeEmbeddings数据库实现了上下文管理器协议__enter__/__exit__见 base.py#L85-L89以下代码块结束后会自动调用 close 释放资源# 创建新的 Embeddings 数据库索引数据并保存 with Embeddings() as embeddings: embeddings.index(rows) embeddings.save(path) # 加载已保存的 Embeddings 数据库并搜索 with Embeddings().load(path) as embeddings: embeddings.search(query)虽然不显式调用close也通常没问题资源会被垃圾回收但最佳实践是一旦不再需要就尽早释放数据库连接等共享资源。从源码看close会依次关闭 ANN、数据库、scoring、图网络、子索引与向量模型并把所有引用置空。持久化save、load 与 exists索引可以保存到目录或压缩文件中# 保存到目录 embeddings.save(/path/to/save) # 保存为压缩包 embeddings.save(/path/to/save/index.tar.gz) # 加载 embeddings.load(/path/to/load)从 save 实现可以看到保存会按组件分文件落盘config配置、embeddingsANN 向量、lsaPCA 降维模型、ids、documents数据库、scoring、indexes、graph路径以.tar.gz、.tar.bz2、.tar.xz或.zip结尾时自动打包为压缩文件。load则按同名规则逐一恢复base.py#L533-L604并支持传入config覆盖已有配置。此外索引还可以持久化到云存储仅支持压缩包形式适合 serverless 或临时计算环境以及通过exists(path)检查某路径下是否已存在有效索引。更多索引读写场景见索引指南的 Save 章节。方法背后的架构多组件协同Embeddings之所以能同时支持语义搜索、关键词搜索与结构化过滤是因为它把多种存储与索引组件组合在了一起内容存储在底层关系数据库中同时维护 ANN 索引、关键词索引scoring与可选的图网络。以一次带数据库的查询为例检索链路是自然语言查询 → 向量化 → ANN 相似度检索得到候选 id → 将这些 id 注入底层 SQL 查询 → 结合动态列过滤返回结构化结果。动态列在 SQLite 中会转换为json_extract子句客户端-服务器数据库则通过 SQLAlchemy 方言支持前提是底层引擎具备 JSON 类型支持。这一“相似度检索 结构化过滤”的组合架构正是 txtai 查询层的核心设计。延伸阅读Embeddings 总览语义搜索引擎的定位与入门示例索引指南向量化、后端设置、稀疏向量、图与子索引的深入讲解查询指南SQL、similar 子句、绑定参数、混合检索、图检索配置参考path、content、objects、scoring、indexes等全部配置项示例集合语义搜索相关的完整 notebook 示例列表【免费下载链接】txtai All-in-one AI framework for semantic search, LLM orchestration and language model workflows项目地址: https://gitcode.com/GitHub_Trending/tx/txtai创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 txtai Embeddings 方法全解析：从索引构建到语义搜索的完整 API 指南
txtai Embeddings 方法全解析从索引构建到语义搜索的完整 API 指南【免费下载链接】txtai All-in-one AI framework for semantic search, LLM orchestration and language model workflows项目地址: https://gitcode.com/GitHub_Trending/tx/txtaitxtai 的 Embeddings 是驱动语义搜索的核心引擎数据被转换为 embeddings 向量含义相近的概念会得到相近的向量从而让检索结果“语义相关”而非仅仅“关键词相同”。本文以官方文档 docs/embeddings/methods.md 为主体结合 Embeddings 源码 与 indexing.md、query.md 等配套指南系统讲解Embeddings类的构造、索引、搜索、更新删除、持久化与资源管理等全部核心方法读完即可在自己的项目中构建、保存并检索一个可用的语义搜索引擎。快速上手构建并搜索一个 Embeddings 索引先看一个最小可运行示例它完整演示了“创建实例 → 索引数据 → 语义搜索”三步流程也是理解后续所有方法的起点。from txtai import Embeddings # 创建 embeddings 模型底层由 sentence-transformers transformers 驱动 embeddings Embeddings(pathsentence-transformers/nli-mpnet-base-v2) data [ US tops 5 million confirmed virus cases, Canadas last fully intact ice shelf has suddenly collapsed, forming a Manhattan-sized iceberg, Beijing mobilises invasion craft along coast as Taiwan tensions escalate, The National Park Service warns against sacrificing slower friends in a bear attack, Maine man wins $1M from $25 lottery ticket, Make huge profits without work, earn up to $100,000 a day ] # 索引文本列表 embeddings.index(data) print(f{Query:20} Best Match) print(- * 50) # 对每个查询执行语义搜索 for query in (feel good story, climate change, public health story, war, wildlife, asia, lucky, dishonest junk): # 取第一条结果的 uid # search 结果格式: (uid, score) uid embeddings.search(query, 1)[0][0] # 打印命中的原文 print(f{query:20} {data[uid]})这段代码演示了 txtai 语义搜索的核心价值feel good story会命中彩票中奖的新闻climate change会命中冰架坍塌的报道dishonest junk会命中诈骗广告——检索依据是语义而非字面关键词。Build配置驱动的 Embeddings 实例构造Embeddings实例是配置驱动的构造函数接受一个配置字典也可全部以关键字参数传入。从源码看构造函数会合并config与kwargs为单一字典再调用configure()加载各类模型组件def __init__(self, configNone, modelsNone, **kwargs): # 合并配置 config {**config, **kwargs} if config and kwargs else kwargs if kwargs else config # 设置初始配置并加载配置驱动的模型 self.configure(config)上面示例通过 path 参数指定了具体的向量模型。也可以创建一个不带任何配置的实例embeddings Embeddings()此时当加载和检索数据时会使用默认的 transformers 向量模型sentence-transformers/all-MiniLM-L6-v2对数据做向量化。这一点在源码 base.py 的 defaults 方法中有明确体现当没有显式模型且允许默认值时会写入self.config[path] sentence-transformers/all-MiniLM-L6-v2。向量模型的选型建议可参考模型指南。从源码结构看一个Embeddings实例会按需挂载以下组件对应 base.py 的初始化清单属性作用model稠密向量模型将数据转换为相似度向量ann近似最近邻ANN索引存储稠密向量database文档数据库存储文档原文内容scoring稀疏向量/关键词索引BM25、TF-IDF、SPLADE 等graph语义图网络indexes子索引subindexes也是 embeddings 数据库ids关闭内容存储时的 indexid→id 映射query查询翻译模型把自然语言查询转成 SQLIndex向索引添加数据创建实例后下一步就是写入数据embeddings.index(rows)index方法接受一个可迭代对象其中每个元素支持三种格式(id, data, tags)—— 默认处理格式元素说明id唯一记录 iddata待索引的输入数据可以是文本、字典或对象tags可选的标签字符串用于在索引时标记/标注数据(id, data)—— 同上但没有 tags。data—— 单一元素。此时会自动生成唯一 id。注意对于自动生成的 id后续的 upsert 和 delete 调用需要先执行一次搜索来拿到目标 id。当data是字典时文本通过text键传入二进制对象通过object键传入。需要特别注意的是必须开启 content 才能存储元数据开启 objects 才能存储二进制对象如果提供了id和tags键也会被自动提取。输入可迭代对象可以是列表或生成器generator。对于非常大的数据集生成器能显著降低内存占用因为任意时刻只有一部分数据驻留内存。索引的更多细节向量化、后端设置、稀疏向量、子索引等参见索引指南。从源码看index内部流程base.py#L103-L153大致为初始化索引 → 用Stream流式读取文档 → 用Transform将文档写入数据库并转为向量结果暂存到临时.npy文件→ 可选执行 PCA 降维 → 创建 ANN 并把向量灌入 → 再依次索引稀疏评分、子索引与图网络。因此一次index调用是“全量重建”语义它会覆盖已有索引。Search执行语义查询数据索引完成后即可检索embeddings.search(query, limit)search方法接收两个参数查询语句与结果条数限制。返回结果的格式取决于是否开启 content 存储未存储内容时返回(id, score)元组列表存储内容时返回{**query columns}字典列表包含查询中涉及的全部列自然语言查询与 SQL 查询都被支持。简单自然语言查询示例embeddings.search(feel good story) embeddings.search(wildlife)开启内容存储后还能使用带过滤条件的 SQLSELECT text, flag, actiondate FROM txtai WHERE similar(query) AND flag 1 AND actiondate 2022-01-01关于similar()子句、绑定参数、聚合查询、自定义 SQL 函数、混合检索权重、图检索与子索引查询的完整说明见查询指南。从搜索执行源码search/base.py可以看清查询分派逻辑当存在图网络且查询是图语句时走图搜索否则若未强制索引搜索且有数据库则走“索引 数据库”联合搜索先做相似度检索拿到候选 id再注入数据库查询完成过滤其余情况走纯向量索引搜索稀疏、稠密或两者加权融合的 hybrid 搜索。limit默认值为 3hybrid 权重默认值为 0.5。批量查询与index对应search也提供了批量版本batchsearch(queries, limit, weights, index, parameters, graph)一次调用可处理多条查询返回按查询分组的嵌套列表。源码中search就是batchsearch对单条查询的封装base.py#L356-L376。增删改upsert、delete 与 reindexUpsert插入或更新记录embeddings.upsert(documents)upsert在索引已存在时把新数据追加进索引、已存在的数据更新若索引尚不存在或为空则退化为标准index操作源码见 base.py#L166-L169。与index的全量重建不同upsert不需要重建整个索引。Delete删除记录embeddings.delete(ids)delete接收 id 列表并返回实际删除的 id 列表base.py#L203-L258。从源码看有数据库时先从数据库查询 indexid→id 映射再删除数据库记录没有数据库时则在ids映射中按 id 反查内部索引位置随后依次对 ANN、稀疏评分、子索引和图网络执行删除。Reindex换模型/换后端重索引开启内容存储后可以调用reindex用新配置重建索引——例如把后端从 faiss 切换为 hnsw或更换向量模型而无需回到原始数据embeddings.reindex(pathsentence-transformers/all-MiniLM-L6-v2, backendhnsw)源码base.py#L260-L290会保留原有的content与objects配置以确保数据库得以复用从已存文档重新向量化并建索引。其他常用方法除上述主流程外Embeddings还提供以下实用方法均可从 base.py 中查看实现transform(document, category, index)/batchtransform(documents, ...)把单个/多个文档转换为 embeddings 向量支持指令式嵌入的category参数与子索引的index参数。similarity(query, data)/batchsimilarity(queries, data)计算查询与一组数据的相似度返回按得分降序的(id, score)列表id 即数据在列表中的下标。实现上利用归一化向量的点积等价于余弦相似度base.py#L441-L445。explain(query, texts, limit)解释查询中每个输入 token 的重要程度分数越高越相关需要开启内容存储或显式传入texts。terms(query)/batchterms(queries)把查询缩减为关键词项常用于稀疏检索场景。count()返回索引中的元素总数按 ANN、scoring、database、ids 的顺序择一计算。info()以 JSON 打印当前索引的完整配置便于调试。资源管理上下文管理器与 closeEmbeddings数据库实现了上下文管理器协议__enter__/__exit__见 base.py#L85-L89以下代码块结束后会自动调用 close 释放资源# 创建新的 Embeddings 数据库索引数据并保存 with Embeddings() as embeddings: embeddings.index(rows) embeddings.save(path) # 加载已保存的 Embeddings 数据库并搜索 with Embeddings().load(path) as embeddings: embeddings.search(query)虽然不显式调用close也通常没问题资源会被垃圾回收但最佳实践是一旦不再需要就尽早释放数据库连接等共享资源。从源码看close会依次关闭 ANN、数据库、scoring、图网络、子索引与向量模型并把所有引用置空。持久化save、load 与 exists索引可以保存到目录或压缩文件中# 保存到目录 embeddings.save(/path/to/save) # 保存为压缩包 embeddings.save(/path/to/save/index.tar.gz) # 加载 embeddings.load(/path/to/load)从 save 实现可以看到保存会按组件分文件落盘config配置、embeddingsANN 向量、lsaPCA 降维模型、ids、documents数据库、scoring、indexes、graph路径以.tar.gz、.tar.bz2、.tar.xz或.zip结尾时自动打包为压缩文件。load则按同名规则逐一恢复base.py#L533-L604并支持传入config覆盖已有配置。此外索引还可以持久化到云存储仅支持压缩包形式适合 serverless 或临时计算环境以及通过exists(path)检查某路径下是否已存在有效索引。更多索引读写场景见索引指南的 Save 章节。方法背后的架构多组件协同Embeddings之所以能同时支持语义搜索、关键词搜索与结构化过滤是因为它把多种存储与索引组件组合在了一起内容存储在底层关系数据库中同时维护 ANN 索引、关键词索引scoring与可选的图网络。以一次带数据库的查询为例检索链路是自然语言查询 → 向量化 → ANN 相似度检索得到候选 id → 将这些 id 注入底层 SQL 查询 → 结合动态列过滤返回结构化结果。动态列在 SQLite 中会转换为json_extract子句客户端-服务器数据库则通过 SQLAlchemy 方言支持前提是底层引擎具备 JSON 类型支持。这一“相似度检索 结构化过滤”的组合架构正是 txtai 查询层的核心设计。延伸阅读Embeddings 总览语义搜索引擎的定位与入门示例索引指南向量化、后端设置、稀疏向量、图与子索引的深入讲解查询指南SQL、similar 子句、绑定参数、混合检索、图检索配置参考path、content、objects、scoring、indexes等全部配置项示例集合语义搜索相关的完整 notebook 示例列表【免费下载链接】txtai All-in-one AI framework for semantic search, LLM orchestration and language model workflows项目地址: https://gitcode.com/GitHub_Trending/tx/txtai创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考