2026/9/15 15:50:53
FEATURED · 精选文章 
txtai Embeddings 深度指南语义搜索索引的构建、查询与持久化【免费下载链接】txtai All-in-one AI framework for semantic search, LLM orchestration and language model workflows项目地址: https://gitcode.com/GitHub_Trending/tx/txtai本文以 txtai 的 Embeddings 模块docs/embeddings/index.md为骨架系统讲解语义搜索数据库的核心概念、构建流程、索引与查询 API、配置驱动机制以及资源管理方式。读完本文你将掌握如何用几行代码完成从向量化、建索引、语义查询到索引持久化的完整闭环并了解其底层组件ANN 索引、内容数据库、稀疏索引、图网络如何协同工作。什么是 Embeddings 数据库Embeddings 数据库是 txtai 中驱动语义搜索的核心引擎。其核心思想是把数据转换成 embeddings 向量语义相近的概念会产生相近的向量随后基于这些向量构建可大可小的索引检索时返回的是语义相同而非仅仅关键词相同的结果。从源码看Embeddings类src/python/txtai/embeddings/base.py的类注释直接定义了这一概念Embeddings databases are the engine that delivers semantic search. Data is transformed into embeddings vectors where similar concepts will produce similar vectors. Indexes both large and small are built with these vectors. The indexes are used to find results that have the same meaning, not necessarily the same keywords.一个Embeddings实例内部会按需装配多个组件见 构造函数 的初始化字段稠密向量模型model、近似最近邻索引ann、文档数据库database、稀疏向量索引scoring、图网络graph、子索引indexes等它们共同构成一个可查询的语义索引。快速上手构建并搜索一个索引下面是 docs/embeddings/index.md 中完整的入门示例——先索引一批新闻标题再用自然语言查询from txtai import Embeddings # Create embeddings model, backed by 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 ] # Index the list of text embeddings.index(data) print(f{Query:20} Best Match) print(- * 50) # Run an embeddings search for each query for query in (feel good story, climate change, public health story, war, wildlife, asia, lucky, dishonest junk): # Extract uid of first result # search result format: (uid, score) uid embeddings.search(query, 1)[0][0] # Print text print(f{query:20} {data[uid]})注意search返回的是(uid, score)二元组列表uid是数据在原始列表中的下标score是相似度得分。通过data[uid]即可还原出原始文本。即便查询词如 dishonest junk与原文Make huge profits without work...没有共同关键词也能命中语义相近的文档——这正是 embeddings 搜索区别于关键词检索的本质。配置驱动从零配置到精细调优Embeddings实例是配置驱动的configuration-driven构造函数接收配置字典或关键字参数。完整的配置体系见 docs/embeddings/configuration/index.md分为以下几大类配置域文档默认行为ANN向量索引后端configuration/ann.md默认使用 FaissCloud云同步configuration/cloud.md可选将索引同步到云存储Database内容存储configuration/database.md默认关闭开启时默认用 SQLiteGeneral通用配置configuration/general.md关键词索引、混合搜索、子索引、自增 id 等Graph图网络configuration/graph.md默认关闭开启时默认用 NetworkXScoring稀疏索引configuration/scoring.md稀疏关键词索引与词向量词项加权Vectors向量模型configuration/vectors.md向量模型可选未提供时使用默认模型配置设计为按需设置开箱即用时自动选择合理默认值from txtai import Embeddings embeddings Embeddings()这行代码创建了一个使用默认配置的实例向量模型为 all-MiniLM-L6-v2见 configuration/index.mdANN 后端为 Faiss内容存储关闭。如果希望开启内容存储embeddings Embeddings(contentTrue)即在上述配置基础上额外启用 SQLite 保存文档内容从而支持字段过滤与内容回取。配置可通过构造函数中的config参数传入也可直接作为关键字参数传入在 Embeddings.init中两者会被合并为一个字典config {**config, **kwargs} ...再交给configure处理。向量模型配置path上文示例通过path参数指定了向量模型path: string它可以是 Hugging Face Hub 上的任意 transformers/sentence-transformers 模型也可以是本地文件路径详见 configuration/vectors.md。未指定path时创建的空实例会在加载与搜索数据时自动使用默认 transformers 向量模型 all-MiniLM-L6-v2 完成向量化。当前模型的推荐清单可参考 models.md。除了path向量模型配置还包含methodtransformers、sentence-transformers、llama.cpp、litellm、model2vec、external、words 等未设置时依据 path 自动推断、gpu设备选择支持true/false/设备号/设备字符串sentence-transformers方法下设为all可多 GPU 编码、batch流式分块大小与encodebatch底层模型编码批次大小通常对应 GPU 批次、直接影响显存占用等参数具体见 configuration/vectors.md。ANN 后端配置backend计算出的向量存放在 ANNApproximate Nearest Neighbor近似最近邻索引中。backend支持faiss|hnsw|annoy|ggml|milvus|numpy|torch|turbovec|zvec|pgvector|sqlite|custom默认faiss详见 configuration/ann.md。各后端可用同名配置对象做专属调优例如 Faiss 支持components默认小索引用IDMap,Flat大索引自动用IVFx,Flat并自动计算 IVF 单元数、nprobe搜索探针数、quantize以 x-bit 精度存储向量、mmap磁盘映射加载降低内存占用等。这些参数均省略时自动取默认值保证最小的上手成本。Build构建一个 Embeddings 实例构建实例的两种典型方式已在上文演示# 指定向量模型 embeddings Embeddings(pathsentence-transformers/nli-mpnet-base-v2) # 完全不配置 embeddings Embeddings()向量仅负责将数据转为向量并存入 ANN开启 content 内容存储 后还可获得额外的过滤与数据检索能力。相关源码入口见 Embeddings.init。Index向索引添加数据创建实例后下一步就是写入数据embeddings.index(rows)index方法接收一个可迭代对象支持以下三种元素格式(id, data, tags)—— 默认处理格式元素说明id唯一记录 iddata待索引的输入数据可以是文本、字典或对象tags可选的标签字符串用于在索引时给数据打标记/标签(id, data)—— 同上但不含 tags。data—— 仅单个元素。此时会自动生成唯一 id。需要注意对自动生成的 id 执行 upsert 与 delete 时需要先通过一次搜索拿到目标 id。当data是字典时文本通过text键传入二进制对象通过object键传入id与tags键若存在也会被自动提取。注意存储元数据需要开启 content存储二进制对象需要额外开启 objects。输入可迭代对象可以是列表或生成器。从源码看 index 的内部流程从源码看src/python/txtai/embeddings/base.pyindex的典型调用链是initindex初始化索引新建或复用内容数据库Transform与Stream协作把文档写入数据库并批量转换为向量向量临时缓冲到临时文件tempfile.NamedTemporaryFile因为 768 维 float32 向量每条就占 768×43072 字节若配置了pca则构建 LSA 降维模型并作用于向量保存dimensions并创建 ANN 索引把向量写入 ANN无数据库时保存 indexids→ids 映射self.ids依次索引稀疏打分索引scoring、子索引indexes与图网络graph。upsertbase.py与index的区别在于索引不存在时等价于普通index索引存在时追加新数据、更新已有数据且不需要全量重建。deletebase.py则接收 id 列表同步从数据库、ANN、scoring、子索引与图网络中删除对应记录。Search语义检索数据索引完成后即可查询embeddings.search(query, limit)search接收两个参数查询语句与结果数量上限。返回格式取决于是否开启了 content 内容存储未存储内容返回(id, score)二元组列表存储内容返回{**query columns}字典列表包含查询涉及的字段。search同时支持自然语言查询与 SQL 查询详细说明见 query.md。从源码签名看base.py它实际委托给batchsearch并额外支持weights混合搜索权重、index子索引名、parametersSQL 绑定参数与graph返回图结果等参数。自然语言查询最简单的情形查询是文本返回与查询文本最相似的索引文本embeddings.search(feel good story) embeddings.search(wildlife)SQL 查询开启内容存储后txtai 支持更复杂的 SQL 查询。其翻译层会分析输入的 SQL 语句把相似度检索结果与关系数据库中的内容结合。embeddings.search(SQL query)similar 子句是 txtai 提供的 SQL 函数用于在 SQL 中执行相似度检索SELECT id, text, score FROM txtai WHERE similar(feel good story)similar子句的完整参数形式为similar(query, number of candidates, index, weights)参数说明query要执行的自然语言查询number of candidates返回的候选结果数量index目标子索引名称weights混合搜索得分权重txtai 查询层会把相似度检索得到的 id 注入到底层数据库查询中。候选数量应大于期望结果数——当附加了额外过滤条件时保证过滤后仍能返回limit条结果候选数未指定时的默认规则为单个过滤子句时取查询 limit多个过滤子句时取 10 倍查询 limit。index参数仅在启用 子索引 时适用weights用于同时存在稀疏与稠密索引时设置混合得分权重。动态列开启内容存储后若data是字典字典中所有字段都会被存储并可通过 SQL 使用其中text字段或 columns 配置 指定的字段用于similar()检索embeddings.index([{text: text to index, flag: True, actiondate: 2022-01-01}])SELECT text, flag, actiondate FROM txtai WHERE similar(query) AND flag 1 AND actiondate 2022-01-01嵌套字典/JSON 同样支持可用方括号语句转义如含空格的嵌套列名embeddings.index([{text: text to index, parent: {child element: abc}}])SELECT text FROM txtai WHERE [parent.child element] abc绑定参数SQL 支持命名绑定参数# Query with a bind parameter for similar clause query SELECT id, text, score FROM txtai WHERE similar(:x) results embeddings.search(query, parameters{x: feel good story}) # Query with a bind parameter for column filter query SELECT text, flag, actiondate FROM txtai WHERE flag :x results embeddings.search(query, parameters{x: 1})聚合查询txtai 查询语言的目标是尽量贴近底层数据库引擎的全部函数核心难点在于把动态列正确转义进引擎原生查询函数SELECT count(*) FROM txtai WHERE similar(feel good story) AND score 0.15 SELECT max(length(text)) FROM txtai WHERE similar(feel good story) AND score 0.15 SELECT count(*), flag FROM txtai GROUP BY flag ORDER BY count(*) DESC二进制对象开启content与objects后可存取二进制对象# Create embeddings index with content and object storage enabled embeddings Embeddings(contentTrue, objectsTrue) # Get an image request open(demo.gif, rb) # Insert record embeddings.index([( txtai, {text: txtai executes machine-learning workflows., object: request.read()} )]) # Query txtai and get associated object query SELECT object FROM txtai WHERE similar(machine learning) LIMIT 1 result embeddings.search(query)[0][object] # Query binary content with a bind parameter query SELECT object FROM txtai WHERE similar(:x) LIMIT 1 results embeddings.search(query, parameters{x: request.read()})自定义 SQL 函数用户自定义函数可扩展选择、过滤与排序子句。例如用翻译 pipeline 定义 SQL 函数# Translation pipeline translate Translation() # Create embeddings index embeddings Embeddings(pathsentence-transformers/nli-mpnet-base-v2, contentTrue, functions[translate]}) # Run a search using a custom SQL function embeddings.search( SELECT text, translation(text, de, null) text (DE), translation(text, es, null) text (ES), translation(text, fr, null) text (FR) FROM txtai WHERE similar(feel good story) LIMIT 1 )表达式Expressions表达式快捷方式可展开为更复杂的 SQL 片段还支持在索引期建表达式索引以提升性能# Create embeddings index embeddings Embeddings( pathsentence-transformers/nli-mpnet-base-v2, contentTrue, expressions[ {name: filepath, index: True}, {name: textlength, expression: length(text), index: True} ] ) embeddings.search(SELECT textlength, filepath FROM txtai LIMIT 1)查询翻译带过滤条件的自然语言查询可自动翻译为 txtai 兼容 SQLembeddings.search(feel good story since yesterday)等价于select id, text, score from txtai where similar(feel good story) and entry date(now, -1 day)这需要在 database 配置 中设置查询翻译模型query.path。默认模型为t5-small-txtsql可按需微调以适配不同场景。混合搜索Hybrid search当索引同时含稀疏与稠密索引时默认两者等权合并结果也可显式指定权重embeddings.search(query, weights0.5) embeddings.search( SELECT id, text, score FROM txtai WHERE similar(query, 0.5) )图搜索Graph search启用图网络后可用 openCypher 语法做图检索也可把标准检索结果以图形式返回# Find all paths between id: 0 and id: 5 between 1 and 3 hops away embeddings.search( MATCH P({id: 0})-[*1..3]-({id: 5}) RETURN P ) # Find related nodes for query matches embeddings.search( MATCH P(A)-[]-(B) WHERE SIMILAR(A, query) RETURN B ORDER BY A.score DESC LIMIT 10 ) # Standard embeddings search as graph embeddings.search(query, graphTrue)子索引Subindexes可针对额外字段、不同向量模型建立子索引并定向查询# Build index with subindexes embeddings Embeddings( contentTrue, defaultsFalse, indexes{ keyword: { keyword: True }, dense:{ dense: True } } ) embeddings.index(stream()) # Query with index parameter embeddings.search(query, indexkeyword) # Specify with SQL embeddings.search( SELECT id, text, score FROM txtai WHERE similar(query, keyword) )组合索引架构txtai 的索引由多个存储与检索组件组合而成详见 query.md 的组合索引架构内容存放在底层数据库同时配合 ANN 索引、关键词索引与图网络。ANN 索引保存每个输入元素的 id 与向量自然语言查询先转为向量、在 ANN 中找出最佳 id开启数据库后这些 id 会被注入底层数据库查询关键词索引则通过词频索引找最佳 id。动态列由底层引擎支撑——SQLite 下数据以 JSON 存储、动态列转成json_extract子句客户端-服务器数据库通过 SQLAlchemy 支持动态列要求引擎具备 JSON 支持。资源管理上下文管理器与 save/loadEmbeddings 数据库实现了上下文管理器协议代码块结束时自动调用 close 释放资源# Create a new Embeddings database, index data and save with Embeddings() as embeddings: embeddings.index(rows) embeddings.save(path) # Search a saved Embeddings database with Embeddings().load(path) as embeddings: embeddings.search(query)虽然不显式调用close也通常可行资源会被垃圾回收但尽早释放共享资源如数据库连接是最佳实践。源码中__enter__返回自身、__exit__调用closebase.pyclose会依次关闭并置空 ANN、数据库、scoring、图网络、子索引等组件base.py。索引的持久化结构从save的实现base.py可以清晰看到索引在磁盘上的组织方式每次save都会写入config配置并视组件启用情况分别落盘embeddingsANN 向量、lsa降维模型、idsid 映射、documents文档数据库、scoring稀疏索引、indexes子索引与graph图网络。loadbase.py则按相反顺序恢复这些组件。换句话说图网络、稀疏索引等内容都与索引一同持久化每次 save/load 都会同步保存与恢复。除了保存到目录索引还支持压缩归档路径以.tar.gz、.tar.bz2、.tar.xz、.zip结尾时自动压缩并可同步到 云存储云存储仅支持压缩索引适合 serverless 等临时计算场景。更完整的索引生命周期说明参见 indexing.md。更多示例完整的 embeddings 示例清单见 examples.md语义搜索章节其中包含从入门到图网络、混合检索、外部数据库集成等一系列可运行的 Notebook见 examples/ 目录下的01_Introducing_txtai.ipynb、48_Benefits_of_hybrid_search.ipynb、49_External_database_integration.ipynb等仓库测试用例 test/python/testembeddings.py 也覆盖了构建、索引、搜索与持久化的完整验证路径可作为深入学习的参考。【免费下载链接】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 深度指南：语义搜索索引的构建、查询与持久化
txtai Embeddings 深度指南语义搜索索引的构建、查询与持久化【免费下载链接】txtai All-in-one AI framework for semantic search, LLM orchestration and language model workflows项目地址: https://gitcode.com/GitHub_Trending/tx/txtai本文以 txtai 的 Embeddings 模块docs/embeddings/index.md为骨架系统讲解语义搜索数据库的核心概念、构建流程、索引与查询 API、配置驱动机制以及资源管理方式。读完本文你将掌握如何用几行代码完成从向量化、建索引、语义查询到索引持久化的完整闭环并了解其底层组件ANN 索引、内容数据库、稀疏索引、图网络如何协同工作。什么是 Embeddings 数据库Embeddings 数据库是 txtai 中驱动语义搜索的核心引擎。其核心思想是把数据转换成 embeddings 向量语义相近的概念会产生相近的向量随后基于这些向量构建可大可小的索引检索时返回的是语义相同而非仅仅关键词相同的结果。从源码看Embeddings类src/python/txtai/embeddings/base.py的类注释直接定义了这一概念Embeddings databases are the engine that delivers semantic search. Data is transformed into embeddings vectors where similar concepts will produce similar vectors. Indexes both large and small are built with these vectors. The indexes are used to find results that have the same meaning, not necessarily the same keywords.一个Embeddings实例内部会按需装配多个组件见 构造函数 的初始化字段稠密向量模型model、近似最近邻索引ann、文档数据库database、稀疏向量索引scoring、图网络graph、子索引indexes等它们共同构成一个可查询的语义索引。快速上手构建并搜索一个索引下面是 docs/embeddings/index.md 中完整的入门示例——先索引一批新闻标题再用自然语言查询from txtai import Embeddings # Create embeddings model, backed by 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 ] # Index the list of text embeddings.index(data) print(f{Query:20} Best Match) print(- * 50) # Run an embeddings search for each query for query in (feel good story, climate change, public health story, war, wildlife, asia, lucky, dishonest junk): # Extract uid of first result # search result format: (uid, score) uid embeddings.search(query, 1)[0][0] # Print text print(f{query:20} {data[uid]})注意search返回的是(uid, score)二元组列表uid是数据在原始列表中的下标score是相似度得分。通过data[uid]即可还原出原始文本。即便查询词如 dishonest junk与原文Make huge profits without work...没有共同关键词也能命中语义相近的文档——这正是 embeddings 搜索区别于关键词检索的本质。配置驱动从零配置到精细调优Embeddings实例是配置驱动的configuration-driven构造函数接收配置字典或关键字参数。完整的配置体系见 docs/embeddings/configuration/index.md分为以下几大类配置域文档默认行为ANN向量索引后端configuration/ann.md默认使用 FaissCloud云同步configuration/cloud.md可选将索引同步到云存储Database内容存储configuration/database.md默认关闭开启时默认用 SQLiteGeneral通用配置configuration/general.md关键词索引、混合搜索、子索引、自增 id 等Graph图网络configuration/graph.md默认关闭开启时默认用 NetworkXScoring稀疏索引configuration/scoring.md稀疏关键词索引与词向量词项加权Vectors向量模型configuration/vectors.md向量模型可选未提供时使用默认模型配置设计为按需设置开箱即用时自动选择合理默认值from txtai import Embeddings embeddings Embeddings()这行代码创建了一个使用默认配置的实例向量模型为 all-MiniLM-L6-v2见 configuration/index.mdANN 后端为 Faiss内容存储关闭。如果希望开启内容存储embeddings Embeddings(contentTrue)即在上述配置基础上额外启用 SQLite 保存文档内容从而支持字段过滤与内容回取。配置可通过构造函数中的config参数传入也可直接作为关键字参数传入在 Embeddings.init中两者会被合并为一个字典config {**config, **kwargs} ...再交给configure处理。向量模型配置path上文示例通过path参数指定了向量模型path: string它可以是 Hugging Face Hub 上的任意 transformers/sentence-transformers 模型也可以是本地文件路径详见 configuration/vectors.md。未指定path时创建的空实例会在加载与搜索数据时自动使用默认 transformers 向量模型 all-MiniLM-L6-v2 完成向量化。当前模型的推荐清单可参考 models.md。除了path向量模型配置还包含methodtransformers、sentence-transformers、llama.cpp、litellm、model2vec、external、words 等未设置时依据 path 自动推断、gpu设备选择支持true/false/设备号/设备字符串sentence-transformers方法下设为all可多 GPU 编码、batch流式分块大小与encodebatch底层模型编码批次大小通常对应 GPU 批次、直接影响显存占用等参数具体见 configuration/vectors.md。ANN 后端配置backend计算出的向量存放在 ANNApproximate Nearest Neighbor近似最近邻索引中。backend支持faiss|hnsw|annoy|ggml|milvus|numpy|torch|turbovec|zvec|pgvector|sqlite|custom默认faiss详见 configuration/ann.md。各后端可用同名配置对象做专属调优例如 Faiss 支持components默认小索引用IDMap,Flat大索引自动用IVFx,Flat并自动计算 IVF 单元数、nprobe搜索探针数、quantize以 x-bit 精度存储向量、mmap磁盘映射加载降低内存占用等。这些参数均省略时自动取默认值保证最小的上手成本。Build构建一个 Embeddings 实例构建实例的两种典型方式已在上文演示# 指定向量模型 embeddings Embeddings(pathsentence-transformers/nli-mpnet-base-v2) # 完全不配置 embeddings Embeddings()向量仅负责将数据转为向量并存入 ANN开启 content 内容存储 后还可获得额外的过滤与数据检索能力。相关源码入口见 Embeddings.init。Index向索引添加数据创建实例后下一步就是写入数据embeddings.index(rows)index方法接收一个可迭代对象支持以下三种元素格式(id, data, tags)—— 默认处理格式元素说明id唯一记录 iddata待索引的输入数据可以是文本、字典或对象tags可选的标签字符串用于在索引时给数据打标记/标签(id, data)—— 同上但不含 tags。data—— 仅单个元素。此时会自动生成唯一 id。需要注意对自动生成的 id 执行 upsert 与 delete 时需要先通过一次搜索拿到目标 id。当data是字典时文本通过text键传入二进制对象通过object键传入id与tags键若存在也会被自动提取。注意存储元数据需要开启 content存储二进制对象需要额外开启 objects。输入可迭代对象可以是列表或生成器。从源码看 index 的内部流程从源码看src/python/txtai/embeddings/base.pyindex的典型调用链是initindex初始化索引新建或复用内容数据库Transform与Stream协作把文档写入数据库并批量转换为向量向量临时缓冲到临时文件tempfile.NamedTemporaryFile因为 768 维 float32 向量每条就占 768×43072 字节若配置了pca则构建 LSA 降维模型并作用于向量保存dimensions并创建 ANN 索引把向量写入 ANN无数据库时保存 indexids→ids 映射self.ids依次索引稀疏打分索引scoring、子索引indexes与图网络graph。upsertbase.py与index的区别在于索引不存在时等价于普通index索引存在时追加新数据、更新已有数据且不需要全量重建。deletebase.py则接收 id 列表同步从数据库、ANN、scoring、子索引与图网络中删除对应记录。Search语义检索数据索引完成后即可查询embeddings.search(query, limit)search接收两个参数查询语句与结果数量上限。返回格式取决于是否开启了 content 内容存储未存储内容返回(id, score)二元组列表存储内容返回{**query columns}字典列表包含查询涉及的字段。search同时支持自然语言查询与 SQL 查询详细说明见 query.md。从源码签名看base.py它实际委托给batchsearch并额外支持weights混合搜索权重、index子索引名、parametersSQL 绑定参数与graph返回图结果等参数。自然语言查询最简单的情形查询是文本返回与查询文本最相似的索引文本embeddings.search(feel good story) embeddings.search(wildlife)SQL 查询开启内容存储后txtai 支持更复杂的 SQL 查询。其翻译层会分析输入的 SQL 语句把相似度检索结果与关系数据库中的内容结合。embeddings.search(SQL query)similar 子句是 txtai 提供的 SQL 函数用于在 SQL 中执行相似度检索SELECT id, text, score FROM txtai WHERE similar(feel good story)similar子句的完整参数形式为similar(query, number of candidates, index, weights)参数说明query要执行的自然语言查询number of candidates返回的候选结果数量index目标子索引名称weights混合搜索得分权重txtai 查询层会把相似度检索得到的 id 注入到底层数据库查询中。候选数量应大于期望结果数——当附加了额外过滤条件时保证过滤后仍能返回limit条结果候选数未指定时的默认规则为单个过滤子句时取查询 limit多个过滤子句时取 10 倍查询 limit。index参数仅在启用 子索引 时适用weights用于同时存在稀疏与稠密索引时设置混合得分权重。动态列开启内容存储后若data是字典字典中所有字段都会被存储并可通过 SQL 使用其中text字段或 columns 配置 指定的字段用于similar()检索embeddings.index([{text: text to index, flag: True, actiondate: 2022-01-01}])SELECT text, flag, actiondate FROM txtai WHERE similar(query) AND flag 1 AND actiondate 2022-01-01嵌套字典/JSON 同样支持可用方括号语句转义如含空格的嵌套列名embeddings.index([{text: text to index, parent: {child element: abc}}])SELECT text FROM txtai WHERE [parent.child element] abc绑定参数SQL 支持命名绑定参数# Query with a bind parameter for similar clause query SELECT id, text, score FROM txtai WHERE similar(:x) results embeddings.search(query, parameters{x: feel good story}) # Query with a bind parameter for column filter query SELECT text, flag, actiondate FROM txtai WHERE flag :x results embeddings.search(query, parameters{x: 1})聚合查询txtai 查询语言的目标是尽量贴近底层数据库引擎的全部函数核心难点在于把动态列正确转义进引擎原生查询函数SELECT count(*) FROM txtai WHERE similar(feel good story) AND score 0.15 SELECT max(length(text)) FROM txtai WHERE similar(feel good story) AND score 0.15 SELECT count(*), flag FROM txtai GROUP BY flag ORDER BY count(*) DESC二进制对象开启content与objects后可存取二进制对象# Create embeddings index with content and object storage enabled embeddings Embeddings(contentTrue, objectsTrue) # Get an image request open(demo.gif, rb) # Insert record embeddings.index([( txtai, {text: txtai executes machine-learning workflows., object: request.read()} )]) # Query txtai and get associated object query SELECT object FROM txtai WHERE similar(machine learning) LIMIT 1 result embeddings.search(query)[0][object] # Query binary content with a bind parameter query SELECT object FROM txtai WHERE similar(:x) LIMIT 1 results embeddings.search(query, parameters{x: request.read()})自定义 SQL 函数用户自定义函数可扩展选择、过滤与排序子句。例如用翻译 pipeline 定义 SQL 函数# Translation pipeline translate Translation() # Create embeddings index embeddings Embeddings(pathsentence-transformers/nli-mpnet-base-v2, contentTrue, functions[translate]}) # Run a search using a custom SQL function embeddings.search( SELECT text, translation(text, de, null) text (DE), translation(text, es, null) text (ES), translation(text, fr, null) text (FR) FROM txtai WHERE similar(feel good story) LIMIT 1 )表达式Expressions表达式快捷方式可展开为更复杂的 SQL 片段还支持在索引期建表达式索引以提升性能# Create embeddings index embeddings Embeddings( pathsentence-transformers/nli-mpnet-base-v2, contentTrue, expressions[ {name: filepath, index: True}, {name: textlength, expression: length(text), index: True} ] ) embeddings.search(SELECT textlength, filepath FROM txtai LIMIT 1)查询翻译带过滤条件的自然语言查询可自动翻译为 txtai 兼容 SQLembeddings.search(feel good story since yesterday)等价于select id, text, score from txtai where similar(feel good story) and entry date(now, -1 day)这需要在 database 配置 中设置查询翻译模型query.path。默认模型为t5-small-txtsql可按需微调以适配不同场景。混合搜索Hybrid search当索引同时含稀疏与稠密索引时默认两者等权合并结果也可显式指定权重embeddings.search(query, weights0.5) embeddings.search( SELECT id, text, score FROM txtai WHERE similar(query, 0.5) )图搜索Graph search启用图网络后可用 openCypher 语法做图检索也可把标准检索结果以图形式返回# Find all paths between id: 0 and id: 5 between 1 and 3 hops away embeddings.search( MATCH P({id: 0})-[*1..3]-({id: 5}) RETURN P ) # Find related nodes for query matches embeddings.search( MATCH P(A)-[]-(B) WHERE SIMILAR(A, query) RETURN B ORDER BY A.score DESC LIMIT 10 ) # Standard embeddings search as graph embeddings.search(query, graphTrue)子索引Subindexes可针对额外字段、不同向量模型建立子索引并定向查询# Build index with subindexes embeddings Embeddings( contentTrue, defaultsFalse, indexes{ keyword: { keyword: True }, dense:{ dense: True } } ) embeddings.index(stream()) # Query with index parameter embeddings.search(query, indexkeyword) # Specify with SQL embeddings.search( SELECT id, text, score FROM txtai WHERE similar(query, keyword) )组合索引架构txtai 的索引由多个存储与检索组件组合而成详见 query.md 的组合索引架构内容存放在底层数据库同时配合 ANN 索引、关键词索引与图网络。ANN 索引保存每个输入元素的 id 与向量自然语言查询先转为向量、在 ANN 中找出最佳 id开启数据库后这些 id 会被注入底层数据库查询关键词索引则通过词频索引找最佳 id。动态列由底层引擎支撑——SQLite 下数据以 JSON 存储、动态列转成json_extract子句客户端-服务器数据库通过 SQLAlchemy 支持动态列要求引擎具备 JSON 支持。资源管理上下文管理器与 save/loadEmbeddings 数据库实现了上下文管理器协议代码块结束时自动调用 close 释放资源# Create a new Embeddings database, index data and save with Embeddings() as embeddings: embeddings.index(rows) embeddings.save(path) # Search a saved Embeddings database with Embeddings().load(path) as embeddings: embeddings.search(query)虽然不显式调用close也通常可行资源会被垃圾回收但尽早释放共享资源如数据库连接是最佳实践。源码中__enter__返回自身、__exit__调用closebase.pyclose会依次关闭并置空 ANN、数据库、scoring、图网络、子索引等组件base.py。索引的持久化结构从save的实现base.py可以清晰看到索引在磁盘上的组织方式每次save都会写入config配置并视组件启用情况分别落盘embeddingsANN 向量、lsa降维模型、idsid 映射、documents文档数据库、scoring稀疏索引、indexes子索引与graph图网络。loadbase.py则按相反顺序恢复这些组件。换句话说图网络、稀疏索引等内容都与索引一同持久化每次 save/load 都会同步保存与恢复。除了保存到目录索引还支持压缩归档路径以.tar.gz、.tar.bz2、.tar.xz、.zip结尾时自动压缩并可同步到 云存储云存储仅支持压缩索引适合 serverless 等临时计算场景。更完整的索引生命周期说明参见 indexing.md。更多示例完整的 embeddings 示例清单见 examples.md语义搜索章节其中包含从入门到图网络、混合检索、外部数据库集成等一系列可运行的 Notebook见 examples/ 目录下的01_Introducing_txtai.ipynb、48_Benefits_of_hybrid_search.ipynb、49_External_database_integration.ipynb等仓库测试用例 test/python/testembeddings.py 也覆盖了构建、索引、搜索与持久化的完整验证路径可作为深入学习的参考。【免费下载链接】txtai All-in-one AI framework for semantic search, LLM orchestration and language model workflows项目地址: https://gitcode.com/GitHub_Trending/tx/txtai创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
