txtai 嵌入索引配置完全指南从 ANN、向量模型到云同步的全参数解析【免费下载链接】txtai All-in-one AI framework for semantic search, LLM orchestration and language model workflows项目地址: https://gitcode.com/GitHub_Trending/tx/txtaitxtai 的 Embeddings 索引是语义搜索的引擎数据被转换为向量相近的概念产生相近的向量从而让检索基于含义而非关键词。本指南以官方配置文档为骨架逐项讲解 Embeddings 的全部配置参数ANN 后端、向量模型、内容存储、图索引、稀疏评分、云同步等并深入源码验证每个参数的实际生效路径帮助你按需组合出生产可用的嵌入索引。配置从何而来Embeddings 构造函数所有配置参数都通过Embeddings构造函数设置。构造函数签名支持两种传入方式且两者会被合并为一份配置字典config参数传入一个配置字典**kwargs直接以关键字参数传入合并逻辑位于 embeddings/base.pydef __init__(self, configNone, modelsNone, **kwargs): # 将 config 与 kwargs 合并为单一配置字典 config {**config, **kwargs} if config and kwargs else kwargs if kwargs else config self.configure(config)因此以下两种写法等价from txtai import Embeddings # 方式一通过 config 参数 embeddings Embeddings(config{path: sentence-transformers/all-MiniLM-L6-v2, content: True}) # 方式二通过关键字参数 embeddings Embeddings(pathsentence-transformers/all-MiniLM-L6-v2, contentTrue)configure方法embeddings/base.py会把配置拆解并驱动性地加载各类模型先创建用于词向量加权评分的scoring实例再通过loadvectors()加载稠密向量模型最后通过loadquery()加载查询翻译模型。而index/upsert等建索引操作调用initindex时会先执行defaults()补齐默认参数再按需创建数据库、ANN、评分索引、子索引与图索引。开箱即用的默认配置配置被设计为全部可选、按需设置。不传任何参数时框架自动挑选合理的默认值from txtai import Embeddings embeddings Embeddings()这会创建一个使用all-MiniLM-L6-v2作为向量模型、Faiss作为 ANN 后端、内容存储关闭的嵌入索引。默认模型加载逻辑见 embeddings/base.py当允许默认模型且未指定path时自动写入path sentence-transformers/all-MiniLM-L6-v2。再对比embeddings Embeddings(contentTrue)与上面相同只是额外启用了SQLite作为内容存储引擎。各配置大类汇总如下配置域文档核心作用ANNann向量近邻索引后端默认 FaissCloudcloud索引与云存储/Hugging Face Hub 同步Databasedatabase元数据、文本与二进制内容存储默认关闭开启后默认 SQLiteGeneralgeneral关键词索引、子索引、自增 ID 等杂项配置Graphgraph图索引主题建模、路径遍历等默认 NetworkXScoringscoring稀疏关键词索引与词向量术语加权Vectorsvectors向量模型与向量化相关配置下面逐一深入。ANN近似最近邻索引后端ANN 配置用于存储嵌入向量核心参数为backendbackend: faiss|hnsw|annoy|ggml|milvus|numpy|torch|turbovec|zvec|pgvector|sqlite|custom默认值为faiss。其他后端通过 install 文档 中描述的ann扩展包安装自定义后端则将参数设为可完整解析的类名字符串。后端专属参数通过同名的配置对象设置如annoy、faiss、hnsw均为可选省略时使用默认值。faissfaiss: components: 逗号分隔的组件列表 - 小索引默认 IDMap,Flat 大索引默认 IVFx,Flat其中 x min(4 * sqrt(嵌入数量), 嵌入数量 / 39) 省略时自动计算 IVF 单元数支持 IVF,Flat nprobe: 搜索探测设置int- 大索引默认 x/16见上 nflip: 同 nprobe - 仅用于二值哈希索引 quantize: 以 x 位精度存储向量而非 32 位boolean|int true 为 8 位精度false 禁用int 为指定精度 mmap: 以磁盘索引方式加载boolean- 用查询响应时间换取更小的 内存占用默认 false sample: 用于模型训练的数据比例0.0 - 1.0 减少大索引100 万行以上的索引时间默认 1.0Faiss 同时支持浮点索引与二值索引默认使用浮点索引对标量量化数据集建索引时使用二值索引。注意macOS 用户会因上游包的既有 bug 导致处理线程数被限制为 1该限制已在库内部处理以避免系统崩溃。hnswhnsw: efconstruction: init_index 的 ef_construction 参数int- 默认 200 m: init_index 的 M 参数int- 默认 16 randomseed: init_index 的 random-seed 参数int- 默认 100 efsearch: ef 搜索参数int- 默认 None即不设置annoyannoy: ntrees: 树的数量int- 默认 10 searchk: search_k 搜索设置int- 默认 -1注意 Annoy 索引创建后不可修改不支持 upsert/delete 等变更操作。ggmlggml: gpu: 启用 GPU - 默认 True quantize: 设置张量量化 - 默认 F32 querysize: 查询缓冲区大小 - 默认 64GGML 后端是 k 近邻后端使用 GGML/GGUF 格式存储张量支持 GPU 与量化也是 llama.cpp 所使用的框架。milvusmilvus: m: 每个元素的 HNSW 链接数int- 默认 50numpynumpy: safetensors: 使用 safetensors 格式存储向量 默认为 NumPy 数组存储NumPy 后端是 k 近邻后端设计简单适合能装入内存的小数据集。torchtorch: safetensors: 使用 safetensors 格式存储向量 - 若量化被禁用 默认为 NumPy 数组存储 quantize: type: 量化类型fp4、nf4、int8 blocksize: 量化块大小参数Torch 后端与 NumPy 类似但支持 GPU 运算开启量化后向量始终以 safetensors 存储量化可将更大的数组装入 GPU 内存。注意 macOS 对量化的支持有限。turbovecturbovec: bitwidth: 每个向量维度存储的位数支持 2、3 或 4turbovec 是基于 TurboQuant 算法的 k 近邻后端。zveczvec: m: 每个元素的 HNSW 链接数int- 默认 50zvec 是嵌入式、基于路径的向量索引。pgvectorpgvector: url: 数据库连接字符串也可通过 ANN_URL 环境变量设置 schema: 存储向量的数据库 schema - 默认由数据库决定 table: 存储向量的数据库表 - 默认 vectors precision: 向量浮点精度half 或 full- 默认 full efconstruction: ef_construction 参数int- 默认 200 m: init_index 的 M 参数int- 默认 16pgvector 后端将嵌入存储在 Postgres 数据库中url连接字符串的构造方式遵循 SQLAlchemy 的数据库 URL 规范。sqlitesqlite: quantize: 以 x 位精度存储向量而非 32 位boolean|int true 为 8 位精度false 禁用int 为指定精度 table: 存储向量的数据库表 - 默认 vectorsSQLite 后端基于 sqlite-vec 在 SQLite 数据库中存储嵌入存储层支持 1 位与 8 位量化。macOS 上运行该后端需要额外处理系统默认阻止 SQLite 扩展的问题。Cloud索引与云存储同步Cloud 配置用于将索引同步到云对象存储、Hugging Face Hub 或自定义提供方。这些参数通过 embeddings.load / embeddings.save 方法生效。通用参数provider: string container: stringprovider云提供方可选云对象存储使用 libcloud 支持列表中的Provider Constant列文本小写Hugging Face Hub设为huggingface-hub自定义提供方设为自定义提供方的完整类路径container容器/桶/目录/仓库名称嵌入索引将以path配置指定的文件名存入该容器。云对象存储附加参数key: string # 提供方访问密钥也可通过 ACCESS_KEY 环境变量设置 # 使用隐式认证时设为 using-implicit-auth 之类的值 secret: string # 提供方访问秘密也可通过 ACCESS_SECRET 环境变量设置 # 隐式认证时无需设置 prefix: string # 可选对象前缀对象存储无目录概念前缀类似目录如 base/dir host: string # 可选服务器主机名使用本地云存储服务器时设置 port: int # 可选服务器端口使用本地云存储服务器时设置 token: string # 可选的临时会话令牌 region: string # 可选的存储区域参数提供方相关注意部分云提供方不需要这些参数可直接使用服务账户的隐式认证若把密钥写入配置文件务必确保配置文件本身安全。Hugging Face Hub 附加参数revision: string # 可选的 Git 修订号分支名、标签或提交哈希 cache: string # 缓存文件存储目录路径 token: string|boolean # 下载使用的令牌设为 True 时从 # Hugging Face 配置目录读取令牌Database内容存储数据库用于存储元数据、文本与二进制内容。核心参数为contentcontent: boolean|sqlite|duckdb|client|url|custom设为true时使用默认引擎sqlite保存元数据支持客户端-服务器连接设为client时须通过CLIENT_URL环境变量提供完整连接 URL或直接传入完整连接 URLurl自定义存储引擎设为可完整解析的类名字符串内容存储专属参数通过同名配置对象设置如duckdb、sqlite。client客户端-服务器数据库schema: 会话的默认数据库 schema - 默认由数据库决定该配置在contenturl时同样适用。sqlitesqlite: wal: 启用预写日志 - 允许并发读写默认 falseobjects对象二进制内容存储objects: boolean|image|pickle启用对象存储以支持二进制内容前提是必须先启用内容存储。编码方式standard布尔值时使用的默认编码器对象按字节数组编解码image图像编码器对象按图像对象编解码picklepickle 编码器支持任意对象functions自定义 SQL 函数functions: list用户自定义 SQL 函数列表每个元素必须是以下之一函数可调用对象包含name、argcount、function、deterministic字段的 dict可参考 查询文档中的自定义 SQL 函数示例。expressions表达式快捷方式expressions: list表达式快捷方式列表每个元素为包含以下字段的 dictname表达式名称expressionSQL 表达式为空时默认取nameindex该表达式是否建立数据库索引未提供时默认 False表达式可以是 JSON 数据列、SQL 函数或任何可作为 SQL 片段运行的内容。query查询翻译模型query: path: 查询模型路径 - 可以是 Hugging Face Model Hub 上的任意模型 或本地文件路径 prefix: 附加到所有输入前面的文本前缀 maxlength: 最大生成序列长度该模型将自然语言查询翻译为 txtai 兼容的 SQL 语句。General通用配置通用配置涵盖不适合归入其他分类的参数。keyword稀疏关键词索引keyword: boolean|string启用本嵌入索引的稀疏关键词索引布尔值创建 BM25 索引用于全文搜索字符串期望一个 关键词评分方法设置该参数会隐式禁用向量搜索的defaults设置。源码中defaultsparseembeddings/base.py将 keyword/hybrid 转换为{method: bm25, terms: True, normalize: True}的评分配置。sparse稀疏向量索引sparse: boolean|path启用本嵌入索引的稀疏向量索引True使用默认稀疏索引模型Splade_PP_en_v2创建稀疏向量索引字符串本地或 Hugging Face 模型路径同样会隐式禁用defaults。源码中稀疏配置会被扩展为{method: sparse, path: 模型路径}默认路径为opensearch-project/opensearch-neural-sparse-encoding-doc-v2-mini。densedense: boolean|stringpath向量模型路径的别名。设为True时使用默认 transformers 向量模型 all-MiniLM-L6-v2设为字符串时直接作为模型路径使用。hybrid混合索引hybrid: boolean启用混合稀疏 稠密索引。启用时会创建 BM25 索引用于全文搜索同时通过defaultsparse将dense置为True它不影响defaults或path设置。defaultsdefaults: boolean启用时默认 True若未提供path则使用默认向量模型路径。判定逻辑见defaultallowed()embeddings/base.py当keyword、sparse均为 False 且defaults为 True 时才允许加载默认模型。典型示例见 配置总览。indexes子索引indexes: dict定义本嵌入索引的子索引键值对。每个键为索引名称值为完整配置该配置可使用标准嵌入实例中的任意配置项。子索引场景下若未提供models缓存loadvectors会自动创建模型缓存embeddings/base.py避免同一模型被重复加载。autoid自动 ID 生成format: int|uuid function设置自动 ID 生成方式。未设置时使用自动生成的数字序列。支持 UUID 生成函数设为uuid4为每行生成随机 UUID设为uuid5为每行输入数据生成确定性 UUIDcolumns列名与存储columns: text: 文本列名称 object: 对象列名称 store: 仅存储 JSON 数据字段中这一列列表设置text与object列名未提供时默认text与object。store设置要存入 JSON 数据字段的列列表未提供存储所有列默认设为None不存储任何 JSON 列指定列表仅存储列表中的列store的典型应用场景是某字段只在索引期需要、搜索期不需要时避免其占用存储。format配置存储格式format: json|pickle设置配置存储格式默认json。注意pickle配置已弃用在默认设置下会报错仅用于读取旧索引且需设置ALLOW_PICKLE环境变量只应对本地和/或可信来源启用。底层实现见 embeddings/index/configuration.pyload优先读取config.json否则回退读取 pickle 格式的config文件并回填format字段save则默认写 JSON、兼容写 pickle。Graph图索引通过graph参数启用图存储需要安装 graph 扩展包。启用后图网络基于嵌入索引构建图节点与每次索引操作index/upsert/delete同步图边则在每次嵌入索引调用完成后基于嵌入索引创建。这为后续的主题建模、路径遍历等能力奠定基础。backendbackend: networkx|rdbms|custom设置图后端默认networkx自定义图存储引擎通过可完整解析的类字符串设置。rdbms后端附加配置url: 数据库连接字符串也可通过 GRAPH_URL 环境变量设置 schema: 存储图的数据库 schema - 默认由数据库决定 nodes: 存储节点数据的表 - 默认 nodes edges: 存储边数据的表 - 默认 edges图构建参数batchsize: 批量查询大小用于查询嵌入索引 - 默认 256 limit: 每次嵌入查询返回的最大结果数 - 默认 15 minscore: 嵌入查询匹配所需的最低分数 - 默认 0.1 approximate: 为 true 时仅对无边的节点执行查询 - 默认 truetopics主题建模topics: algorithm: 社区检测算法字符串可选 louvain默认、greedy、lpa level: 控制主题数量字符串可选 best默认或 first resolution: 控制主题数量int值越大主题越多默认 100 labels: 构建主题标签的评分索引方法字符串 可选 bm25默认、tfidf、sif terms: 用于主题标签的高频词数量int- 默认 4 stopwords: 可选停用词列表用于从主题标签中排除 categories: 可选类别列表用于对主题分组 允许以宽泛类别聚合细粒度主题启用主题建模。默认值经过调优多数场景下无需修改categories除外这些参数面向需要完全控制社区检测过程的进阶场景。copyattributescopyattributes: boolean|list将insert方法输入字典中的这些属性复制到图属性中。设为True时复制全部属性否则仅复制列表中指定的属性。Scoring稀疏评分与关键词索引通过scoring参数启用评分支持。该评分实例依据设置可承担两种职责构建稀疏/关键词索引当terms参数设为True时词向量术语加权自最初版本就支持但如今已不太常用methodmethod: bm25|tfidf|sif|pgtext|sparse|custom设置评分方法自定义评分通过可完整解析的类字符串设置。pgtextPostgres 全文关键词索引附加参数schema: 存储关键词索引的数据库 schema - 默认由数据库决定sparse稀疏向量评分参数path: 稀疏向量模型路径 vectormethod: 向量嵌入方法 vectornormalize: 启用向量嵌入归一化boolean gpu: boolean|int|string|device normalize: 启用分数归一化boolean|float|string|dict batch: 设置变换批量大小 encodebatch: 设置编码批量大小 vectors: 附加模型初始化参数 encodeargs: 附加 encode() 参数 backend: ivfsparse|pgsparse稀疏评分实例将稀疏向量模型与稀疏 ANN 索引结合同时支持向量归一化与分数归一化向量归一化将所有向量归一化为模长 1生成的分数范围为 0 到 1分数归一化将输出缩放到 0 到 1支持True默认缩放归一化float以该值作为缩放因子归一化bayes使用动态候选分数统计的贝叶斯归一化{method: bayes, alpha: 1.0, beta: null}带可选自定义参数的贝叶斯归一化ivfsparse倒排文件索引 扁平向量文件存储 稀疏数组支持ivfsparse: sample: 用于模型训练的数据比例0.0 - 1.0 nfeatures: 用于模型训练的 top n 特征int nlist: 期望的聚类数量int nprobe: 搜索探测设置int minpoints: 一个聚类的最少点数intpgsparse为 Postgres 支持的稀疏 ANN支持与 pgvector 相同的选项。termsterms: boolean|dict为评分实例启用词频稀疏数组这是稀疏关键词索引的后端。支持含cachelimit和cutoff参数的 dictcachelimitint索引期间写入磁盘前允许使用的最大常驻内存字节数cutofffloat搜索时用于判定常见词的阈值如 0.1 表示 10% 截断terms设为True时使用默认参数通常已足够。normalizenormalize: boolean|str|dict启用归一化评分0 到 1 区间支持True标准分数归一化使用索引统计计算归一化分数bayes/bb25贝叶斯归一化利用动态候选分数统计{method: bayes, alpha: 1.0, beta: null}带自定义参数的贝叶斯归一化贝叶斯/BB25 归一化使用正分候选、动态betamedian(scores)、自适应alpha_effalpha/std(scores)以及 sigmoid 变换带平坦先验的仅似然变体将分数映射到[0, 1]。tokenizertokenizer: dict设置分词规则参数透传给底层的 Tokenizer 管道。Vectors向量模型配置向量搜索通过将文本及其他二进制数据转换为嵌入向量实现向量存储于 ANN 索引中。向量模型是可选的——未提供时使用默认模型。pathpath: string向量模型路径。对 transformers/sentence-transformers 模型可以是 Hugging Face Hub 上的任意模型或本地文件路径其他情况必须是词嵌入模型的本地文件路径。methodmethod: transformers|sentence-transformers|llama.cpp|litellm|model2vec|external|words嵌入方法。未提供时根据path自动推断。sentence-transformers、llama.cpp、litellm、model2vec、words需要安装 vectors 扩展包。transformers使用 transformers 模型构建嵌入最好选用专为嵌入训练的模型。支持mean、cls、last、late、max池化并自动推断可通过将 method 改为meanpooling、clspooling、lastpooling、latepooling、maxpooling覆盖池化方式。maxlength设为True时按max_seq_length截断输入设为整数则按该值截断省略时取模型或分词器的最大长度。还支持直接加载 ONNX 模型。sentence-transformers同 transformers但用 sentence-transformers 库加载模型。llama.cpp使用 llama.cpp 模型构建嵌入支持 HF Hub 上的本地与远程 GGUF 路径。litellm使用 LiteLLM 模型构建嵌入。model2vec使用 Model2Vec 模型它是 transformers 模型的知识蒸馏静态向量版本。words使用词嵌入模型与静态向量构建嵌入适合语言数据稀少的低资源与历史语言场景。pca参数int可从生成的嵌入中移除n个主成分通过构建 TruncatedSVD 模型做降维在池化得到单一嵌入后应用。external通过外部模型或 API 创建嵌入需要设置transform参数为将数据转换为嵌入的函数。该函数输入为数据列表必须返回 numpy 数组、numpy 数组列表或 float 数组列表。注意此方法已弃用默认设置下会报错需设置ALLOW_RESOLVE_TRANSFORM环境变量只对可信/已审查代码启用更推荐的做法是实现自定义Vectors类。gpugpu: boolean|int|string|device设置目标设备支持 true/false、设备 ID、设备字符串与 torch 设备实例省略时自动推导。sentence-transformers方法支持多 GPU 编码将gpu设为all即可启用。batch / encodebatchbatch: int # 变换批量大小控制输入流如何分块与向量化 encodebatch: int # 编码批量大小控制底层向量模型的批量大小 # 通常对应 GPU 批量大小决定 GPU 内存占用dimensionalitydimensionality: int将向量截断到该维度。仅对把更重要信息存储在靠前维度的模型如 Matryoshka Representation LearningMRL有用。quantizequantize: int|boolean按指定精度启用标量向量量化支持 1 位到 8 位。标量量化将连续浮点值转换为离散无符号整数faiss、pgvector、numpy、torchANN 后端支持存储此类向量。布尔值仅为向后兼容设为 true/false 时等价于设置faiss.quantize。此外部分 ANN 后端还支持在存储层量化向量见 ANN 配置。instructionsinstructions: query: 查询前缀 data: 索引前缀指令型模型使用前缀修改嵌入计算方式特别适合非对称搜索查询与索引数据长度差异悬殊即短查询配长文档。txtai 会自动加载config_sentence_transformers.json中存储的提示词除非显式设置该参数对 E5-base 等较老模型仍需通过此参数提供指令。modelsmodels: dict将向量模型加载并缓存在此字典中主要用于子索引场景但也可设置在任意嵌入实例上。多个嵌入实例共享时可避免同一模型被重复加载。tokenizetokenize: boolean启用字符串分词默认 false。该方法应用的规则仅适用于英文文本不建议与近年来的向量模型搭配使用。vectors透传模型参数vectors: dict将这些附加参数透传给底层向量模型主要包含以下子项center对归一化后的晚期交互late-interactiontoken 向量做居中后再归一化随后进行 MUVERA 或 LEMUR 编码。true使用 batch 作用域false禁用居中显式设置始终优先。省略时带存储集合均值的 LEMUR 工件使用 collection 作用域其他 LEMUR 工件与晚期交互模型仅在加载超过一个torch.nn.Linear层时默认使用 batch 作用域。字典配置支持center: scope: document | batch | collectiondocument独立减去每个文档/查询的均值batch减去当前模型批次中所有真实 token 行的均值collection需要调用方通过mean数组或path含center.mean张量的 safetensors 文件提供一维均值向量二者不可同时提供LEMUR 工件可自动提供该均值。零填充行永不计入居中且保持为零。muveramuvera: repetitions: 默认 20 hashes: 默认 5 projection: 默认 16控制 MUVERA 固定维度输出大小默认 20 * 2^5 * 16 10,240 维。设muvera为false禁用true使用默认设置。lemurlemur: path: 本地工件目录或 Hugging Face Hub 路径加载训练好的 LEMUR 固定维度编码器。LEMUR 工件是语料特定的必须先使用LemurTrainer创建再配置嵌入索引裸字符串视为工件路径。查询向量为学习特征的求和文档向量为工件存储 token 样本上的普通最小二乘权重。每个工件包含config.json与model.safetensors新训练工件还会以lemur.center存储集合 token 均值加载该均值会自动选择集合居中除非显式配置center无lemur.center的工件保持旧默认行为。Safetensors 文件仅含推理状态。trust_remote_codetrust_remote_code: boolean是否信任带自定义实现的 Hugging Face 模型的代码。配置组合实战建议综合各配置域一个生产环境常见的混合搜索 内容存储 主题建模配置示例from txtai import Embeddings embeddings Embeddings( # 稠密向量默认模型 denseTrue, # 混合搜索BM25 全文 稠密向量 hybridTrue, # 内容存储SQLite 启用 WAL contentTrue, sqlite{wal: True}, # ANN 调优 faiss{nprobe: 8}, # 图索引 主题建模 graph{topics: {categories: [science, tech, health]}}, # 查询翻译模型 query{path: path/to/query-model}, )配置的核心设计哲学是可选、按需、有默认值多数场景下只需设置少数参数即可获得可用的语义搜索能力而 ANN 后端、评分方法、图后端、向量模型等均可按数据规模、硬件条件与业务需求自由组合。若需进一步了解各参数对应的运行时行为可继续阅读 Embeddings 方法文档 与 查询文档或在源码 embeddings/base.py 的defaults()、configure()与各 Factory 中追踪参数的实际消费路径。【免费下载链接】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 嵌入索引配置完全指南：从 ANN、向量模型到云同步的全参数解析
txtai 嵌入索引配置完全指南从 ANN、向量模型到云同步的全参数解析【免费下载链接】txtai All-in-one AI framework for semantic search, LLM orchestration and language model workflows项目地址: https://gitcode.com/GitHub_Trending/tx/txtaitxtai 的 Embeddings 索引是语义搜索的引擎数据被转换为向量相近的概念产生相近的向量从而让检索基于含义而非关键词。本指南以官方配置文档为骨架逐项讲解 Embeddings 的全部配置参数ANN 后端、向量模型、内容存储、图索引、稀疏评分、云同步等并深入源码验证每个参数的实际生效路径帮助你按需组合出生产可用的嵌入索引。配置从何而来Embeddings 构造函数所有配置参数都通过Embeddings构造函数设置。构造函数签名支持两种传入方式且两者会被合并为一份配置字典config参数传入一个配置字典**kwargs直接以关键字参数传入合并逻辑位于 embeddings/base.pydef __init__(self, configNone, modelsNone, **kwargs): # 将 config 与 kwargs 合并为单一配置字典 config {**config, **kwargs} if config and kwargs else kwargs if kwargs else config self.configure(config)因此以下两种写法等价from txtai import Embeddings # 方式一通过 config 参数 embeddings Embeddings(config{path: sentence-transformers/all-MiniLM-L6-v2, content: True}) # 方式二通过关键字参数 embeddings Embeddings(pathsentence-transformers/all-MiniLM-L6-v2, contentTrue)configure方法embeddings/base.py会把配置拆解并驱动性地加载各类模型先创建用于词向量加权评分的scoring实例再通过loadvectors()加载稠密向量模型最后通过loadquery()加载查询翻译模型。而index/upsert等建索引操作调用initindex时会先执行defaults()补齐默认参数再按需创建数据库、ANN、评分索引、子索引与图索引。开箱即用的默认配置配置被设计为全部可选、按需设置。不传任何参数时框架自动挑选合理的默认值from txtai import Embeddings embeddings Embeddings()这会创建一个使用all-MiniLM-L6-v2作为向量模型、Faiss作为 ANN 后端、内容存储关闭的嵌入索引。默认模型加载逻辑见 embeddings/base.py当允许默认模型且未指定path时自动写入path sentence-transformers/all-MiniLM-L6-v2。再对比embeddings Embeddings(contentTrue)与上面相同只是额外启用了SQLite作为内容存储引擎。各配置大类汇总如下配置域文档核心作用ANNann向量近邻索引后端默认 FaissCloudcloud索引与云存储/Hugging Face Hub 同步Databasedatabase元数据、文本与二进制内容存储默认关闭开启后默认 SQLiteGeneralgeneral关键词索引、子索引、自增 ID 等杂项配置Graphgraph图索引主题建模、路径遍历等默认 NetworkXScoringscoring稀疏关键词索引与词向量术语加权Vectorsvectors向量模型与向量化相关配置下面逐一深入。ANN近似最近邻索引后端ANN 配置用于存储嵌入向量核心参数为backendbackend: faiss|hnsw|annoy|ggml|milvus|numpy|torch|turbovec|zvec|pgvector|sqlite|custom默认值为faiss。其他后端通过 install 文档 中描述的ann扩展包安装自定义后端则将参数设为可完整解析的类名字符串。后端专属参数通过同名的配置对象设置如annoy、faiss、hnsw均为可选省略时使用默认值。faissfaiss: components: 逗号分隔的组件列表 - 小索引默认 IDMap,Flat 大索引默认 IVFx,Flat其中 x min(4 * sqrt(嵌入数量), 嵌入数量 / 39) 省略时自动计算 IVF 单元数支持 IVF,Flat nprobe: 搜索探测设置int- 大索引默认 x/16见上 nflip: 同 nprobe - 仅用于二值哈希索引 quantize: 以 x 位精度存储向量而非 32 位boolean|int true 为 8 位精度false 禁用int 为指定精度 mmap: 以磁盘索引方式加载boolean- 用查询响应时间换取更小的 内存占用默认 false sample: 用于模型训练的数据比例0.0 - 1.0 减少大索引100 万行以上的索引时间默认 1.0Faiss 同时支持浮点索引与二值索引默认使用浮点索引对标量量化数据集建索引时使用二值索引。注意macOS 用户会因上游包的既有 bug 导致处理线程数被限制为 1该限制已在库内部处理以避免系统崩溃。hnswhnsw: efconstruction: init_index 的 ef_construction 参数int- 默认 200 m: init_index 的 M 参数int- 默认 16 randomseed: init_index 的 random-seed 参数int- 默认 100 efsearch: ef 搜索参数int- 默认 None即不设置annoyannoy: ntrees: 树的数量int- 默认 10 searchk: search_k 搜索设置int- 默认 -1注意 Annoy 索引创建后不可修改不支持 upsert/delete 等变更操作。ggmlggml: gpu: 启用 GPU - 默认 True quantize: 设置张量量化 - 默认 F32 querysize: 查询缓冲区大小 - 默认 64GGML 后端是 k 近邻后端使用 GGML/GGUF 格式存储张量支持 GPU 与量化也是 llama.cpp 所使用的框架。milvusmilvus: m: 每个元素的 HNSW 链接数int- 默认 50numpynumpy: safetensors: 使用 safetensors 格式存储向量 默认为 NumPy 数组存储NumPy 后端是 k 近邻后端设计简单适合能装入内存的小数据集。torchtorch: safetensors: 使用 safetensors 格式存储向量 - 若量化被禁用 默认为 NumPy 数组存储 quantize: type: 量化类型fp4、nf4、int8 blocksize: 量化块大小参数Torch 后端与 NumPy 类似但支持 GPU 运算开启量化后向量始终以 safetensors 存储量化可将更大的数组装入 GPU 内存。注意 macOS 对量化的支持有限。turbovecturbovec: bitwidth: 每个向量维度存储的位数支持 2、3 或 4turbovec 是基于 TurboQuant 算法的 k 近邻后端。zveczvec: m: 每个元素的 HNSW 链接数int- 默认 50zvec 是嵌入式、基于路径的向量索引。pgvectorpgvector: url: 数据库连接字符串也可通过 ANN_URL 环境变量设置 schema: 存储向量的数据库 schema - 默认由数据库决定 table: 存储向量的数据库表 - 默认 vectors precision: 向量浮点精度half 或 full- 默认 full efconstruction: ef_construction 参数int- 默认 200 m: init_index 的 M 参数int- 默认 16pgvector 后端将嵌入存储在 Postgres 数据库中url连接字符串的构造方式遵循 SQLAlchemy 的数据库 URL 规范。sqlitesqlite: quantize: 以 x 位精度存储向量而非 32 位boolean|int true 为 8 位精度false 禁用int 为指定精度 table: 存储向量的数据库表 - 默认 vectorsSQLite 后端基于 sqlite-vec 在 SQLite 数据库中存储嵌入存储层支持 1 位与 8 位量化。macOS 上运行该后端需要额外处理系统默认阻止 SQLite 扩展的问题。Cloud索引与云存储同步Cloud 配置用于将索引同步到云对象存储、Hugging Face Hub 或自定义提供方。这些参数通过 embeddings.load / embeddings.save 方法生效。通用参数provider: string container: stringprovider云提供方可选云对象存储使用 libcloud 支持列表中的Provider Constant列文本小写Hugging Face Hub设为huggingface-hub自定义提供方设为自定义提供方的完整类路径container容器/桶/目录/仓库名称嵌入索引将以path配置指定的文件名存入该容器。云对象存储附加参数key: string # 提供方访问密钥也可通过 ACCESS_KEY 环境变量设置 # 使用隐式认证时设为 using-implicit-auth 之类的值 secret: string # 提供方访问秘密也可通过 ACCESS_SECRET 环境变量设置 # 隐式认证时无需设置 prefix: string # 可选对象前缀对象存储无目录概念前缀类似目录如 base/dir host: string # 可选服务器主机名使用本地云存储服务器时设置 port: int # 可选服务器端口使用本地云存储服务器时设置 token: string # 可选的临时会话令牌 region: string # 可选的存储区域参数提供方相关注意部分云提供方不需要这些参数可直接使用服务账户的隐式认证若把密钥写入配置文件务必确保配置文件本身安全。Hugging Face Hub 附加参数revision: string # 可选的 Git 修订号分支名、标签或提交哈希 cache: string # 缓存文件存储目录路径 token: string|boolean # 下载使用的令牌设为 True 时从 # Hugging Face 配置目录读取令牌Database内容存储数据库用于存储元数据、文本与二进制内容。核心参数为contentcontent: boolean|sqlite|duckdb|client|url|custom设为true时使用默认引擎sqlite保存元数据支持客户端-服务器连接设为client时须通过CLIENT_URL环境变量提供完整连接 URL或直接传入完整连接 URLurl自定义存储引擎设为可完整解析的类名字符串内容存储专属参数通过同名配置对象设置如duckdb、sqlite。client客户端-服务器数据库schema: 会话的默认数据库 schema - 默认由数据库决定该配置在contenturl时同样适用。sqlitesqlite: wal: 启用预写日志 - 允许并发读写默认 falseobjects对象二进制内容存储objects: boolean|image|pickle启用对象存储以支持二进制内容前提是必须先启用内容存储。编码方式standard布尔值时使用的默认编码器对象按字节数组编解码image图像编码器对象按图像对象编解码picklepickle 编码器支持任意对象functions自定义 SQL 函数functions: list用户自定义 SQL 函数列表每个元素必须是以下之一函数可调用对象包含name、argcount、function、deterministic字段的 dict可参考 查询文档中的自定义 SQL 函数示例。expressions表达式快捷方式expressions: list表达式快捷方式列表每个元素为包含以下字段的 dictname表达式名称expressionSQL 表达式为空时默认取nameindex该表达式是否建立数据库索引未提供时默认 False表达式可以是 JSON 数据列、SQL 函数或任何可作为 SQL 片段运行的内容。query查询翻译模型query: path: 查询模型路径 - 可以是 Hugging Face Model Hub 上的任意模型 或本地文件路径 prefix: 附加到所有输入前面的文本前缀 maxlength: 最大生成序列长度该模型将自然语言查询翻译为 txtai 兼容的 SQL 语句。General通用配置通用配置涵盖不适合归入其他分类的参数。keyword稀疏关键词索引keyword: boolean|string启用本嵌入索引的稀疏关键词索引布尔值创建 BM25 索引用于全文搜索字符串期望一个 关键词评分方法设置该参数会隐式禁用向量搜索的defaults设置。源码中defaultsparseembeddings/base.py将 keyword/hybrid 转换为{method: bm25, terms: True, normalize: True}的评分配置。sparse稀疏向量索引sparse: boolean|path启用本嵌入索引的稀疏向量索引True使用默认稀疏索引模型Splade_PP_en_v2创建稀疏向量索引字符串本地或 Hugging Face 模型路径同样会隐式禁用defaults。源码中稀疏配置会被扩展为{method: sparse, path: 模型路径}默认路径为opensearch-project/opensearch-neural-sparse-encoding-doc-v2-mini。densedense: boolean|stringpath向量模型路径的别名。设为True时使用默认 transformers 向量模型 all-MiniLM-L6-v2设为字符串时直接作为模型路径使用。hybrid混合索引hybrid: boolean启用混合稀疏 稠密索引。启用时会创建 BM25 索引用于全文搜索同时通过defaultsparse将dense置为True它不影响defaults或path设置。defaultsdefaults: boolean启用时默认 True若未提供path则使用默认向量模型路径。判定逻辑见defaultallowed()embeddings/base.py当keyword、sparse均为 False 且defaults为 True 时才允许加载默认模型。典型示例见 配置总览。indexes子索引indexes: dict定义本嵌入索引的子索引键值对。每个键为索引名称值为完整配置该配置可使用标准嵌入实例中的任意配置项。子索引场景下若未提供models缓存loadvectors会自动创建模型缓存embeddings/base.py避免同一模型被重复加载。autoid自动 ID 生成format: int|uuid function设置自动 ID 生成方式。未设置时使用自动生成的数字序列。支持 UUID 生成函数设为uuid4为每行生成随机 UUID设为uuid5为每行输入数据生成确定性 UUIDcolumns列名与存储columns: text: 文本列名称 object: 对象列名称 store: 仅存储 JSON 数据字段中这一列列表设置text与object列名未提供时默认text与object。store设置要存入 JSON 数据字段的列列表未提供存储所有列默认设为None不存储任何 JSON 列指定列表仅存储列表中的列store的典型应用场景是某字段只在索引期需要、搜索期不需要时避免其占用存储。format配置存储格式format: json|pickle设置配置存储格式默认json。注意pickle配置已弃用在默认设置下会报错仅用于读取旧索引且需设置ALLOW_PICKLE环境变量只应对本地和/或可信来源启用。底层实现见 embeddings/index/configuration.pyload优先读取config.json否则回退读取 pickle 格式的config文件并回填format字段save则默认写 JSON、兼容写 pickle。Graph图索引通过graph参数启用图存储需要安装 graph 扩展包。启用后图网络基于嵌入索引构建图节点与每次索引操作index/upsert/delete同步图边则在每次嵌入索引调用完成后基于嵌入索引创建。这为后续的主题建模、路径遍历等能力奠定基础。backendbackend: networkx|rdbms|custom设置图后端默认networkx自定义图存储引擎通过可完整解析的类字符串设置。rdbms后端附加配置url: 数据库连接字符串也可通过 GRAPH_URL 环境变量设置 schema: 存储图的数据库 schema - 默认由数据库决定 nodes: 存储节点数据的表 - 默认 nodes edges: 存储边数据的表 - 默认 edges图构建参数batchsize: 批量查询大小用于查询嵌入索引 - 默认 256 limit: 每次嵌入查询返回的最大结果数 - 默认 15 minscore: 嵌入查询匹配所需的最低分数 - 默认 0.1 approximate: 为 true 时仅对无边的节点执行查询 - 默认 truetopics主题建模topics: algorithm: 社区检测算法字符串可选 louvain默认、greedy、lpa level: 控制主题数量字符串可选 best默认或 first resolution: 控制主题数量int值越大主题越多默认 100 labels: 构建主题标签的评分索引方法字符串 可选 bm25默认、tfidf、sif terms: 用于主题标签的高频词数量int- 默认 4 stopwords: 可选停用词列表用于从主题标签中排除 categories: 可选类别列表用于对主题分组 允许以宽泛类别聚合细粒度主题启用主题建模。默认值经过调优多数场景下无需修改categories除外这些参数面向需要完全控制社区检测过程的进阶场景。copyattributescopyattributes: boolean|list将insert方法输入字典中的这些属性复制到图属性中。设为True时复制全部属性否则仅复制列表中指定的属性。Scoring稀疏评分与关键词索引通过scoring参数启用评分支持。该评分实例依据设置可承担两种职责构建稀疏/关键词索引当terms参数设为True时词向量术语加权自最初版本就支持但如今已不太常用methodmethod: bm25|tfidf|sif|pgtext|sparse|custom设置评分方法自定义评分通过可完整解析的类字符串设置。pgtextPostgres 全文关键词索引附加参数schema: 存储关键词索引的数据库 schema - 默认由数据库决定sparse稀疏向量评分参数path: 稀疏向量模型路径 vectormethod: 向量嵌入方法 vectornormalize: 启用向量嵌入归一化boolean gpu: boolean|int|string|device normalize: 启用分数归一化boolean|float|string|dict batch: 设置变换批量大小 encodebatch: 设置编码批量大小 vectors: 附加模型初始化参数 encodeargs: 附加 encode() 参数 backend: ivfsparse|pgsparse稀疏评分实例将稀疏向量模型与稀疏 ANN 索引结合同时支持向量归一化与分数归一化向量归一化将所有向量归一化为模长 1生成的分数范围为 0 到 1分数归一化将输出缩放到 0 到 1支持True默认缩放归一化float以该值作为缩放因子归一化bayes使用动态候选分数统计的贝叶斯归一化{method: bayes, alpha: 1.0, beta: null}带可选自定义参数的贝叶斯归一化ivfsparse倒排文件索引 扁平向量文件存储 稀疏数组支持ivfsparse: sample: 用于模型训练的数据比例0.0 - 1.0 nfeatures: 用于模型训练的 top n 特征int nlist: 期望的聚类数量int nprobe: 搜索探测设置int minpoints: 一个聚类的最少点数intpgsparse为 Postgres 支持的稀疏 ANN支持与 pgvector 相同的选项。termsterms: boolean|dict为评分实例启用词频稀疏数组这是稀疏关键词索引的后端。支持含cachelimit和cutoff参数的 dictcachelimitint索引期间写入磁盘前允许使用的最大常驻内存字节数cutofffloat搜索时用于判定常见词的阈值如 0.1 表示 10% 截断terms设为True时使用默认参数通常已足够。normalizenormalize: boolean|str|dict启用归一化评分0 到 1 区间支持True标准分数归一化使用索引统计计算归一化分数bayes/bb25贝叶斯归一化利用动态候选分数统计{method: bayes, alpha: 1.0, beta: null}带自定义参数的贝叶斯归一化贝叶斯/BB25 归一化使用正分候选、动态betamedian(scores)、自适应alpha_effalpha/std(scores)以及 sigmoid 变换带平坦先验的仅似然变体将分数映射到[0, 1]。tokenizertokenizer: dict设置分词规则参数透传给底层的 Tokenizer 管道。Vectors向量模型配置向量搜索通过将文本及其他二进制数据转换为嵌入向量实现向量存储于 ANN 索引中。向量模型是可选的——未提供时使用默认模型。pathpath: string向量模型路径。对 transformers/sentence-transformers 模型可以是 Hugging Face Hub 上的任意模型或本地文件路径其他情况必须是词嵌入模型的本地文件路径。methodmethod: transformers|sentence-transformers|llama.cpp|litellm|model2vec|external|words嵌入方法。未提供时根据path自动推断。sentence-transformers、llama.cpp、litellm、model2vec、words需要安装 vectors 扩展包。transformers使用 transformers 模型构建嵌入最好选用专为嵌入训练的模型。支持mean、cls、last、late、max池化并自动推断可通过将 method 改为meanpooling、clspooling、lastpooling、latepooling、maxpooling覆盖池化方式。maxlength设为True时按max_seq_length截断输入设为整数则按该值截断省略时取模型或分词器的最大长度。还支持直接加载 ONNX 模型。sentence-transformers同 transformers但用 sentence-transformers 库加载模型。llama.cpp使用 llama.cpp 模型构建嵌入支持 HF Hub 上的本地与远程 GGUF 路径。litellm使用 LiteLLM 模型构建嵌入。model2vec使用 Model2Vec 模型它是 transformers 模型的知识蒸馏静态向量版本。words使用词嵌入模型与静态向量构建嵌入适合语言数据稀少的低资源与历史语言场景。pca参数int可从生成的嵌入中移除n个主成分通过构建 TruncatedSVD 模型做降维在池化得到单一嵌入后应用。external通过外部模型或 API 创建嵌入需要设置transform参数为将数据转换为嵌入的函数。该函数输入为数据列表必须返回 numpy 数组、numpy 数组列表或 float 数组列表。注意此方法已弃用默认设置下会报错需设置ALLOW_RESOLVE_TRANSFORM环境变量只对可信/已审查代码启用更推荐的做法是实现自定义Vectors类。gpugpu: boolean|int|string|device设置目标设备支持 true/false、设备 ID、设备字符串与 torch 设备实例省略时自动推导。sentence-transformers方法支持多 GPU 编码将gpu设为all即可启用。batch / encodebatchbatch: int # 变换批量大小控制输入流如何分块与向量化 encodebatch: int # 编码批量大小控制底层向量模型的批量大小 # 通常对应 GPU 批量大小决定 GPU 内存占用dimensionalitydimensionality: int将向量截断到该维度。仅对把更重要信息存储在靠前维度的模型如 Matryoshka Representation LearningMRL有用。quantizequantize: int|boolean按指定精度启用标量向量量化支持 1 位到 8 位。标量量化将连续浮点值转换为离散无符号整数faiss、pgvector、numpy、torchANN 后端支持存储此类向量。布尔值仅为向后兼容设为 true/false 时等价于设置faiss.quantize。此外部分 ANN 后端还支持在存储层量化向量见 ANN 配置。instructionsinstructions: query: 查询前缀 data: 索引前缀指令型模型使用前缀修改嵌入计算方式特别适合非对称搜索查询与索引数据长度差异悬殊即短查询配长文档。txtai 会自动加载config_sentence_transformers.json中存储的提示词除非显式设置该参数对 E5-base 等较老模型仍需通过此参数提供指令。modelsmodels: dict将向量模型加载并缓存在此字典中主要用于子索引场景但也可设置在任意嵌入实例上。多个嵌入实例共享时可避免同一模型被重复加载。tokenizetokenize: boolean启用字符串分词默认 false。该方法应用的规则仅适用于英文文本不建议与近年来的向量模型搭配使用。vectors透传模型参数vectors: dict将这些附加参数透传给底层向量模型主要包含以下子项center对归一化后的晚期交互late-interactiontoken 向量做居中后再归一化随后进行 MUVERA 或 LEMUR 编码。true使用 batch 作用域false禁用居中显式设置始终优先。省略时带存储集合均值的 LEMUR 工件使用 collection 作用域其他 LEMUR 工件与晚期交互模型仅在加载超过一个torch.nn.Linear层时默认使用 batch 作用域。字典配置支持center: scope: document | batch | collectiondocument独立减去每个文档/查询的均值batch减去当前模型批次中所有真实 token 行的均值collection需要调用方通过mean数组或path含center.mean张量的 safetensors 文件提供一维均值向量二者不可同时提供LEMUR 工件可自动提供该均值。零填充行永不计入居中且保持为零。muveramuvera: repetitions: 默认 20 hashes: 默认 5 projection: 默认 16控制 MUVERA 固定维度输出大小默认 20 * 2^5 * 16 10,240 维。设muvera为false禁用true使用默认设置。lemurlemur: path: 本地工件目录或 Hugging Face Hub 路径加载训练好的 LEMUR 固定维度编码器。LEMUR 工件是语料特定的必须先使用LemurTrainer创建再配置嵌入索引裸字符串视为工件路径。查询向量为学习特征的求和文档向量为工件存储 token 样本上的普通最小二乘权重。每个工件包含config.json与model.safetensors新训练工件还会以lemur.center存储集合 token 均值加载该均值会自动选择集合居中除非显式配置center无lemur.center的工件保持旧默认行为。Safetensors 文件仅含推理状态。trust_remote_codetrust_remote_code: boolean是否信任带自定义实现的 Hugging Face 模型的代码。配置组合实战建议综合各配置域一个生产环境常见的混合搜索 内容存储 主题建模配置示例from txtai import Embeddings embeddings Embeddings( # 稠密向量默认模型 denseTrue, # 混合搜索BM25 全文 稠密向量 hybridTrue, # 内容存储SQLite 启用 WAL contentTrue, sqlite{wal: True}, # ANN 调优 faiss{nprobe: 8}, # 图索引 主题建模 graph{topics: {categories: [science, tech, health]}}, # 查询翻译模型 query{path: path/to/query-model}, )配置的核心设计哲学是可选、按需、有默认值多数场景下只需设置少数参数即可获得可用的语义搜索能力而 ANN 后端、评分方法、图后端、向量模型等均可按数据规模、硬件条件与业务需求自由组合。若需进一步了解各参数对应的运行时行为可继续阅读 Embeddings 方法文档 与 查询文档或在源码 embeddings/base.py 的defaults()、configure()与各 Factory 中追踪参数的实际消费路径。【免费下载链接】txtai All-in-one AI framework for semantic search, LLM orchestration and language model workflows项目地址: https://gitcode.com/GitHub_Trending/tx/txtai创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考