人工智能大模型预训练微调LoRARLHF强化学习分布式训练【免费下载链接】PaddleNLPEasy-to-use and powerful LLM and SLM library with awesome model zoo.项目地址https://gitcode.com/gh_mirrors/pa/PaddleNLP点击查看免费下载导读本文围绕 PaddleNLP Pipelines仓库路径slm/pipelines中的 FAISS 文档存储组件展开。FAISSDocumentStore专为大规模基于 embedding 的稠密检索dense retriever设计文档正文与元数据落在 SQL 存储中向量嵌入则索引到 FAISS 内存索引两者通过vector_id关联从而兼顾 SQL 的过滤/查询能力与 FAISS 的极速 ANN近似最近邻检索能力。读完本文你将掌握该组件的完整初始化参数、索引类型选型Flat/HNSW/IVF、写入-建索引-检索-持久化的全流程以及它在语义检索、智能问答流水线中的实际调用链与源码级实现原理。说明仓库中slm/pipelines/docs/package/docstore/faiss.md是 mkdocs 的 API 文档入口经 mkdocstrings 渲染后即 faiss.py 模块的类与方法文档本文内容即以此源码及其 docstring 为事实主体。一、组件定位SQL 元数据 FAISS 向量的双存储架构FAISSDocumentStore在仓库中定义于 faiss.py继承自 sql.py 中的SQLDocumentStore并在pipelines/document_stores/__init__.py中通过safe_import导出FAISSDocumentStore safe_import(pipelines.document_stores.faiss, FAISSDocumentStore, faiss)。其类注释明确写道Document store for very large scale embedding based dense retrievers. It implements the FAISS library to perform similarity search on vectors. The document text and meta-data (for filtering) are stored using the SQLDocumentStore, while the vector embeddings are indexed in a FAISS Index.由此可以提炼出该组件的核心设计正文与元数据写入 SQLite默认sqlite:///faiss_document_store.db或 Postgres 等数据库支持按meta字段过滤、按id查询、去重管理等。向量嵌入写入 FAISS Index内存态用于 ANN 相似度检索。关联桥梁每个文档在 FAISS 中的vector_id格式为faiss内部id_index名被写入 SQL 侧文档的meta[vector_id]SQL 表结构与检索调用链见 sql.py 的DocumentORM定义。这种双存储结构的直接收益是检索时先由 FAISS 用向量相似度召回 top-k 候选再回到 SQL 取出正文与元数据完成精排或问答同时借助meta的 SQL 索引支持按字段过滤文档。依赖处理上faiss.py顶部通过try: import faiss的方式将faiss与sql视为可选依赖未安装时会调用_optional_component_not_installed给出友好提示见 faiss.py。二、构造函数与全部初始化参数解析FAISSDocumentStore.__init__的完整签名如下源码见 faiss.pyFAISSDocumentStore( sql_urlsqlite:///faiss_document_store.db, vector_dimNone, # 已废弃请使用 embedding_dim embedding_dim768, # 向量维度默认 768 faiss_index_factory_strFlat, # FAISS 索引工厂字符串 faiss_indexNone, # 传入现成的 FAISS Index return_embeddingFalse, # 是否在查询/读取时返回归一化后的嵌入向量 index_namedocument, # SQL 索引名与 FAISS 索引名一一对应 similaritydot_product, # dot_product / cosine / l2 embedding_fieldembedding, progress_barTrue, duplicate_documentsoverwrite, # skip / overwrite / fail faiss_index_pathNone, # 从磁盘加载 FAISS 索引文件 faiss_config_pathNone, # 从磁盘加载初始化配置 JSON isolation_levelNone, # SQLAlchemy create_engine 的 isolation_level **kwargs, # 供 HNSW 等索引类型透传额外参数 )关键参数详解参数默认值说明sql_urlsqlite:///faiss_document_store.dbSQL 连接串。小规模默认 SQLite 即可大规模部署推荐 Postgres源码 docstring 原文For large scale deployment, Postgres is recommended。embedding_dim768嵌入向量维度必须与检索模型输出维度一致。vector_dim为旧名传入时会触发DeprecationWarning见 faiss.py。faiss_index_factory_strFlatFAISS 索引工厂字符串控制索引类型详见下一节。similaritydot_product相似度度量仅支持dot_product、cosine、l2三种。源码中三者分别映射为faiss.METRIC_INNER_PRODUCT与faiss.METRIC_L2其他取值会抛出ValueError见 faiss.py。duplicate_documentsoverwrite去重策略skip忽略重复文档overwrite以同 ID 覆盖更新fail在文档 ID 已存在时抛错。该取值集合定义在BaseDocumentStore.duplicate_documents_options见 base.py。index_namedocument索引名可传单个str或list多索引场景。传 list 时faiss_index需为 dict。faiss_index_path/faiss_config_pathNone从磁盘加载已有索引与配置。一旦传入faiss_index_path除faiss_config_path外不允许再传其他初始化参数源码通过_validate_params_load_from_disk校验并抛ValueError见 faiss.py。return_embeddingFalse与其他文档存储不同FAISS 在开启该选项时返回的是归一化后的嵌入向量docstring 原文Unlike other document stores, FAISS will return normalized embeddings。初始化流程中构造函数会先调用set_config(...)将全部初始化参数持久化为pipeline_config[params]这为组件配置导出为 YAML流水线声明式编排提供了支撑。三、索引选型Flat / HNSW / IVFx,Flat 的权衡faiss_index_factory_str决定索引结构源码在_create_new_index中实现见 faiss.pydocstring 给出了三条官方推荐路径Flat默认精确检索exact精度最高但文档量超过约 100 万1 Mio docs后会变慢且内存占用高。适合中小规模高精度场景。HNSW基于图的启发式近似索引。若仅写HNSW源码会绕过 FAISS 工厂直接初始化faiss.IndexHNSWFlat并应用默认参数n_links64、efConstruction80、efSearch20见 faiss.py可通过kwargs覆盖这三个值store FAISSDocumentStore( embedding_dim768, faiss_index_factory_strHNSW, n_links64, # HNSW 每个节点的链接数 efConstruction80, # 建图时的动态列表长度 efSearch20, # 检索时的动态列表长度 )值得注意的是源码注释说明 FAISS 的 index factory 对 HNSW 内积度量给出的结果不一致因此 HNSW 采用直接初始化而非工厂字符串解析。IVFx,Flat倒排索引Inverted Index将x替换为中心点数量nlist。经验法则是nlist 10 * sqrt(num_docs)。这类索引需要先用一批与真实数据同分布的向量做训练train_index详见后文。此外metric_type由similarity决定使用faiss.METRIC_INNER_PRODUCTdot_product/cosine或faiss.METRIC_L2l2。四、写入与建索引write_documents update_embeddings4.1 写入文档 write_documents签名见 faiss.pywrite_documents(documents, indexNone, batch_size1000, duplicate_documentsNone, headersNone)流程要点源码见 faiss.py不支持headers参数传入直接raise NotImplementedError。documents可为List[dict]或List[Document]dict 会经Document.from_dict转成 Document 对象并应用字段映射embedding_field→ 向量字段。按batch_size默认 1000分批若文档已携带 embedding则直接faiss_index.add(embeddings)入索引否则只写 SQL留待update_embeddings补向量。cosine度量下写入前会做 L2 归一化。每个文档的meta[vector_id] str(vector_id) _ index写入 SQL作为 FAISS 与 SQL 的关联键。若duplicate_documents overwrite且文档带向量源码会警告FAISS 索引不支持原位置更新需调用update_embeddings重新填充索引见 faiss.py。4.2 用检索器生成并更新向量 update_embeddings签名见 faiss.pyupdate_embeddings(retriever, indexNone, update_existing_embeddingsTrue, filtersNone, batch_size10000)该方法是冷启动建索引的关键文档先写入 SQL再由传入的retriever如DensePassageRetriever对全文批量编码retriever.embed_documents(document_batch)产出向量后faiss_index.add()写入 FAISS同时回写vector_id映射见 faiss.py。两个使用要点update_existing_embeddingsTrue时会先faiss_index.reset()并清空vector_id再全量重建此时不支持与filters同时使用源码直接抛异常。update_existing_embeddingsFalse时只处理尚未有向量的文档适合增量补充新文档的 embedding。4.3 训练类索引 train_indexIVFx,Flat等索引在 add 之前必须先train见 faiss.py。train_index接受documents含 embedding或embeddings二者之一同时传会抛ValueError训练向量应来自与最终数据同分布的数据本质是聚类出 nlist 个中心点后再建倒排表。五、检索query_by_embedding 与相似度归一化5.1 调用链FAISSDocumentStore.query_by_embedding(query_emb, filters, top_k10, indexNone, ...)是整个检索的核心源码见 faiss.py。其上层调用方是稠密检索器DensePassageRetriever.retrieve()先用embed_queries()得到查询向量再调用self.document_store.query_by_embedding(query_embquery_emb[0], top_ktop_k, ...)见 dense.py批量检索retrieve_batch亦走同一路径dense.py。底层执行步骤查询向量 reshape 为(1, -1)并转 float32cosine下先 L2 归一化。调用self.faiss_indexes[index].search(query_emb, top_k)得到原始得分矩阵与向量 id 矩阵。由vector_idid_index拼回vector_id_matrix[0]过滤掉-1未命中再通过 SQL 的get_documents_by_vector_ids取回文档。将原始得分写入doc.ann_score。若开启return_embedding还会用faiss_index.reconstruct()还原归一化后的向量。值得注意filters参数在该实现中并未真正生效——传入时仅打印Query filters are not implemented for the FAISSDocumentStore警告见 faiss.py。如需元数据过滤能力可选用 Milvus 或 Elasticsearch 文档存储对应 milvus2.md、elasticsearch.md。5.2 得分归一化为了统一不同相似度度量的得分区间finalize_raw_score会把原始得分归一化到[0, 1]见 base.pycosinescore (raw_score 1) / 2dot_product及其他score expit(raw_score / 100)其中expit使用 Numbanjit加速的 sigmoid 实现见 base.py未安装 numba 时自动退化为纯 Python 实现。这也解释了为什么cosine度量下向量写入与查询都必须做 L2 归一化normalize_embedding见 base.py——内积与余弦一致的前提是向量模长为 1。六、持久化save / load 与双文件恢复6.1 保存 savesave(index_path, config_pathNone)会把内存中的 FAISS 索引写入磁盘同时落一份初始化参数 JSON见 faiss.py每个索引名index生成一个文件index_path/index二进制 FAISS 索引以及同名.json配置文件。JSON 内容为self.pipeline_config[params]即构造时传入的全部参数sql_url、embedding_dim、similarity 等用于将来完整还原组件。6.2 加载 load类方法load(index_path, config_pathNone)见 faiss.pystore FAISSDocumentStore.load(my_index_dir)若index_path是目录则用glob递归找到全部.json配置并推导出对应索引文件。底层经faiss.read_index()读回索引并从 JSON 恢复init_params再重入__init__faiss_index_path分支见 faiss.py。必须注意恢复时仍会连接到sql_url指向的数据库为保证 FAISS 与 SQL 的vector_id一一对应加载时必须使用当初save()时所用的同一个 SQL 库。初始化末尾的_validate_index_sync会核对 SQL 文档数与 FAISS embedding 数是否一致不一致直接抛错见 faiss.py。七、其他常用方法一览方法作用源码位置get_documents_by_id(ids)按 ID 取文档开启return_embedding时顺带用reconstruct还原向量faiss.pyget_all_documents / get_all_documents_generator批量/生成器式获取全部文档后者适合流式处理大规模文档而不一次性占满内存faiss.pyget_embedding_count(index)返回 FAISS 索引内向量数ntotal不支持 filtersfaiss.pydelete_documents(index, ids, filters)删除文档无 filters 且无 ids 时整体reset()否则按vector_id调remove_ids并同步删 SQL 记录faiss.py。delete_all_documents已废弃应改用本方法八、实战在语义检索流水线中使用 FAISSDocumentStore仓库预置的语义检索示例 semantic_search_example.py 演示了该组件的标准用法以--search_engine faiss运行时会构建FAISSDocumentStore索引目录名为--index_name默认dureader_index数据库文件为faiss_document_store.db若索引已存在则直接FAISSDocumentStore.load(args.index_name)恢复见示例第 47-51 行。一条完整的写入 → 建索引 → 检索 → 重排链路如下与 index.md 中的快速体验示例同构from pipelines.document_stores import FAISSDocumentStore from pipelines.nodes import DensePassageRetriever, ErnieRanker from pipelines import SemanticSearchPipeline documents [ { content: 金钱龟不分品种,只有生长地之分,在我国主要分布于广东、广西、福建、海南、香港、澳门等地。, meta: {name: test1.txt}, }, { content: 衡量酒水的价格的因素很多的酒水的血统、存储的时间等等。, meta: {name: test2.txt}, }, ] # 1. 初始化 FAISS 文档存储SQL 存正文与 metaFAISS 存向量 document_store FAISSDocumentStore(embedding_dim768) document_store.write_documents(documents) # 2. 用稠密检索器为全文生成向量并写入 FAISS 索引 retriever DensePassageRetriever( document_storedocument_store, query_embedding_modelrocketqa-zh-base-query-encoder, embed_titleFalse, ) document_store.update_embeddings(retriever) # 3. 精排 ranker ErnieRanker(model_name_or_pathrocketqa-base-cross-encoder) # 4. 构建流水线并检索 pipeline SemanticSearchPipeline(retriever, ranker) prediction pipeline.run(query衡量酒水的价格的因素有哪些?)参数与模型说明embedding_dim必须与所选编码模型输出维度一致示例中rocketqa-zh-nano-query-encoder配合--embedding_dim 312DensePassageRetriever还可通过max_seq_len_query/max_seq_len_passage/batch_size/output_emb_size控制编码行为见示例参数定义部分。在语义检索阶段retrieve()的查询向量会经query_by_embedding在 FAISS 索引内完成 ANN 搜索随后由ErnieRanker对召回结果精排。如需将整套语义检索服务化仓库还提供 Docker 一键部署方案docker/README.md与 REST APIrest_api/pipeline/semantic_search.yaml等流水线配置。多路召回场景则可在 semantic-search/Multi_Recall.md 中查看 FAISS 与其他 ANN 引擎的配合方式。九、总结与选型建议FAISSDocumentStore是 PaddleNLP Pipelines 中面向大规模稠密检索的默认 ANN 存储方案其价值在于用极简 API 把向量检索与 SQL 元数据管理粘合起来。实践建议规模不大、要求精确用默认Flat百万级且可接受近似改HNSW调n_links/efSearch/efConstruction平衡召回与延迟超大规模用IVFx,Flat并先train_index。持久化save()后务必保留同名 SQL 库load()时两者必须对应否则_validate_index_sync会拒绝启动。过滤需求强FAISSDocumentStore的filters尚未实现如需元数据过滤请转向 Milvusmilvus2.md或 Elasticsearchelasticsearch.md文档存储。核心实现文件faiss.py706 行、base.py、sql.py调用示例semantic_search_example.py、index.md。赞分享人工智能大模型预训练微调LoRARLHF强化学习分布式训练【免费下载链接】PaddleNLPEasy-to-use and powerful LLM and SLM library with awesome model zoo.项目地址https://gitcode.com/gh_mirrors/pa/PaddleNLP点击查看免费下载相关推荐Feast Faiss 在线存储基于向量相似度检索的在线特征存储实现指南Feast Faiss 在线存储基于向量相似度检索的在线特征存储实现指南 Faiss 在线存储Faiss Online Store是 Feast 针对 EMLOps后端数据工程Dataherald向量存储查询基于语义的相似内容检索Dataherald向量存储查询基于语义的相似内容检索 引言从关键词匹配到语义理解的革命 你是否还在为传统SQL查询的局限性而苦恼当用户用自然语言提问显后端人工智能大模型RAG微调Haystack FAISS 集成指南从 FAISSDocumentStore 到 FAISSEmbeddingRetriever 的本地向量检索实战Haystack FAISS 集成指南从 FAISSDocumentStore 到 FAISSEmbeddingRetriever 的本地向量检索实战 FAI人工智能大模型RAGAI AgentNLP创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
