AutoRAG 集成 Weaviate 向量数据库Docker 与云部署配置、检索管线接入与分数计算原理【免费下载链接】AutoRAGAutoRAG: Now your agent can find anything in your computer. It gets smarter if you are using it frequently.项目地址: https://gitcode.com/GitHub_Trending/au/AutoRAG本指南围绕 AutoRAG 的Weaviate向量数据库集成见 legacy/docs/source/integration/vectordb/weaviate.md展开完整覆盖 Docker 本地部署与 Weaviate Cloud 两种接入方式下的 YAML 配置、全部参数语义并结合仓库源码剖析集合创建、批量写入、相似度检索与分数换算的实现细节。读完本文你将能够在 AutoRAG 的 RAG 优化流程中正确接入 Weaviate理解semantic_retrieval节点如何驱动向量检索并掌握各 API 的底层行为与调试要点。集成概览AutoRAG 中的向量数据库抽象层Weaviate 是一个开源的向量数据库用于高效地存储、查询和管理向量嵌入vector embeddings。在 AutoRAG 中Weaviate 通过 Weaviate 类 实现它继承自BaseVectorStore抽象基类legacy/autorag/vectordb/base.py从而获得与 Chroma、Milvus、Pinecone、Couchbase、Qdrant 一致的统一接口。AutoRAG 的向量数据库注册表位于 legacy/autorag/vectordb/init.py其中weaviate被映射到autorag.vectordb.weaviate.Weaviate。配置解析时load_vectordb_from_yaml会从 YAML 的vectordb段读取配置列表弹出name与db_type键后将其余参数作为关键字参数传入Weaviate(...)构造器。因此在 YAML 中出现的每个字段都对应构造器中的一个具名参数。环境准备两种部署形态Weaviate 官方支持多种部署方式AutoRAG 集成文档提供了两种 client 接入形态通过client_type参数切换。形态一Docker 本地部署使用官方 Docker 镜像启动 Weaviate 服务完整安装指南见 Weaviate 官方 Docker Compose 文档此处给出文档中可直接运行的命令docker run -p 8080:8080 -p 50051:50051 cr.weaviate.io/semitechnologies/weaviate:1.27.3在client_type: docker模式下AutoRAG 会自动采用默认连接参数hostlocalhostport8080REST/GraphQL 端口grpc_port50051gRPC 端口用于高性能批量写入与查询如果你的 Weaviate 已经以其他地址、端口运行需要显式设置host、port、grpc_port。源码中对应weaviate.connect_to_local(hosthost, portport, grpc_portgrpc_port)见 weaviate.py。形态二Weaviate Cloud 托管服务对于云端托管的 Weaviate 集群改为client_type: cloud并提供url云集群 URLapi_keyAPI Key用于认证源码中对应weaviate.connect_to_weaviate_cloud(cluster_urlurl, auth_credentialsAuth.api_key(api_key))见 weaviate.py。API Key 通常通过环境变量注入避免硬编码进配置文件。若client_type传入了其他值构造器会抛出ValueError提示仅支持docker与cloud两种取值。YAML 配置两种形态的完整示例配置入口是项目配置文件中的vectordb段。下面两段示例均来自关联文档分别演示 Docker 与 Cloud 形态以 OpenAItext-embedding-3-large为嵌入模型。Docker 形态示例vectordb: - name: openai_weaviate db_type: weaviate embedding_model: openai_embed_3_large collection_name: openai_embed_3_large client_type: docker host: localhost port: 8080 grpc_port: 50051 embedding_batch: 50 similarity_metric: cosine text_key: contentWeaviate Cloud 形态示例vectordb: - name: openai_weaviate db_type: weaviate embedding_model: openai_embed_3_large collection_name: openai_embed_3_large url: ${WEAVIATE_URL} api_key: ${WEAVIATE_API_KEY} grpc_port: 50051 embedding_batch: 50 similarity_metric: cosine text_key: content接入 RAG 检索管线的完整配置配置好vectordb段之后还需要在node_lines中让semantic_retrieval节点引用它。下面是关联文档给出的完整示例以 Docker 形态为例包含检索节点、提示词节点与生成节点vectordb: - name: openai_weaviate db_type: weaviate embedding_model: openai_embed_3_large collection_name: openai_embed_3_large client_type: docker host: localhost port: 8080 grpc_port: 50051 embedding_batch: 50 similarity_metric: cosine text_key: content node_lines: - node_line_name: retrieve_node_line # Arbitrary node line name nodes: - node_type: semantic_retrieval strategy: metrics: [retrieval_f1, retrieval_recall, retrieval_precision] top_k: 3 modules: - module_type: vectordb vectordb: openai_weaviate - node_line_name: post_retrieve_node_line # Arbitrary node line name nodes: - node_type: prompt_maker strategy: metrics: [bleu, meteor, rouge] modules: - module_type: fstring prompt: Read the passages and answer the given question. \n Question: {query} \n Passage: {retrieved_contents} \n Answer : - node_type: generator strategy: metrics: [bleu, rouge] modules: - module_type: llama_index_llm llm: openai model: [ gpt-4o-mini ]其中modules下的vectordb: openai_weaviate就是通过name字段与vectordb段中的条目建立关联的。运行时VectorDB检索节点会从项目目录的resources/vectordb.yaml加载该配置见 legacy/autorag/nodes/semanticretrieval/vectordb.py因此name必须与引用处的vectordb值一致。参数详解11 个配置项逐一说明以下参数表完整继承自关联文档并结合 Weaviate 构造器源码 进行了默认值与语义校准。参数类型默认值适用 client_type说明embedding_modelstr必填两者使用的嵌入模型名称或标识如openai_embed_3_large。需与系统内可用的嵌入模型对应AutoRAG 内置支持见下文。collection_namestr必填两者Weaviate collection集合名称向量将被存储于此。集合不存在时自动创建已存在则直接加载。embedding_batchint100两者单批处理的嵌入数量。越大吞吐越高但更耗内存应根据系统内存与处理能力调整。该值同时会写入底层 embedding 对象的embed_batch_size见 base.py。similarity_metricstrcosine两者向量相似度度量。支持cosine、l2欧氏距离、ip内积。不支持hamming、manhattan。client_typestrdocker两者连接类型docker连接本地服务cloud连接云服务。hoststrlocalhost仅 dockerWeaviate 服务器主机地址如weaviate-server.com。portint8080仅 dockerWeaviate 服务器端口。grpc_portint50051仅 dockergRPC 端口用于高性能批量操作。urlstr仅 cloudWeaviate Cloud 服务 URL。api_keystr仅 cloudWeaviate Cloud 认证 API Key。text_keystrcontent两者Weaviate 属性property中存储文本内容的键名。若 collection 中已有内容需设置为与该 schema 一致的属性名。关于embedding_model的可选值可参考 legacy/autorag/embedding/base.py 内置的模型映射包括openai默认text-embedding-ada-002、openai_embed_3_large、openai_embed_3_small、mock、ollama、openai_like、vllm以及可选的 HuggingFace 本地模型如huggingface_bge_m3。若使用 API 形态的 AutoRAG 需要本地模型需按提示安装AutoRAG[gpu]扩展。关于similarity_metric的校验BaseVectorStore在构造时通过support_similarity_metrics [l2, ip, cosine]断言参数合法性base.pyWeaviate 构造器还会将其映射为 Weaviate 原生距离度量cosine→VectorDistances.COSINEip→VectorDistances.DOTl2→VectorDistances.L2_SQUARED非法取值会抛出明确的ValueErrorweaviate.py。源码级原理集合创建与写入链路集合collection的自动创建与加载Weaviate.__init__在连接成功后执行集合初始化逻辑weaviate.py通过self.client.collections.exists(collection_name)判断集合是否已存在若不存在则调用collections.create创建属性contentDataType.TEXT并设置skip_vectorizationTrue即文本不交给 Weaviate 自带 vectorizer而由 AutoRAG 侧嵌入模型生成向量后显式传入vectorizer_configConfigure.Vectorizer.none()关闭服务端向量化vector_index_configConfigure.VectorIndex.hnsw(distance_metric...)使用 HNSW 索引并注入所选距离度量若已存在则通过collections.get(collection_name)直接加载保持已有数据可用。这就是collection_name参数“不存在则创建、存在则加载”语义的源码依据。批量写入add 与 add_embeddingadd(ids, texts)weaviate.py是文档摄取的主入口流程为对文本执行truncated_inputs预处理——若嵌入模型是 OpenAI会按 8000 token 上限截断base.py调用embedding.aget_text_embedding_batch(texts)异步批量生成嵌入通过self.client.batch.dynamic()动态批量插入每条对象使用uuidids[i]即 AutoRAG 侧的doc_id作为 Weaviate 对象 UUID、vectortext_embeddings[i]并将文本存入{self.text_key: text}属性批量结束后遍历batch.failed_objects对失败对象输出Failed to add object ...错误日志便于排查。add_embedding(ids, embeddings)weaviate.py则直接接收已生成的嵌入向量适合本地模型预计算后批量导入此时不携带文本属性。核心 API 用法与行为Weaviate提供六个核心方法均继承自BaseVectorStore的接口约定关联文档给出了其异步调用签名测试用例 legacy/tests/autorag/vectordb/test_weaviate.py 提供了完整的运行示例该测试依赖 Docker因此在 GitHub Actions 环境下会跳过。1. 添加向量await weaviate_db.add(ids, texts)接收 ID 列表与对应文本列表生成嵌入后插入 Weaviate 集合。2. 相似度查询ids, scores await weaviate_db.query(queries, top_k)对每条查询执行near_vector搜索返回命中的 ID 列表与分数列表weaviate.py。实现细节先对查询批量嵌入再逐条调用collection.query.near_vector(near_vectorquery_embedding, limittop_k, return_metadataMetadataQuery(distanceTrue))最后通过distance_to_score将 Weaviate 返回的距离转换为 AutoRAG 的相似度分数。在检索管线中VectorDB节点会再对结果做evenly_distribute_passages均匀分布与按分数降序排序见 legacy/autorag/nodes/semanticretrieval/vectordb.py。3. 获取向量vectors await weaviate_db.fetch(ids)按 ID 批量获取向量include_vectorTrue内部通过Filter.by_property(_id).contains_any(ids)过滤并维护id - vector字典按传入顺序返回weaviate.py。这在混合检索需要重算未覆盖分数时非常关键——get_id_scores会按similarity_metric用l2/ip/cosine对应的函数重新计算查询与内容的相似度见 semanticretrieval/vectordb.py。4. 检查存在性exists await weaviate_db.is_exist(ids)按_id过滤查询返回每个 ID 是否存在的布尔列表weaviate.py。该能力被摄取流程复用filter_exist_ids与filter_exist_ids_from_retrieval_gt会先检查哪些doc_id已存在只摄取缺失部分实现增量写入见 semanticretrieval/vectordb.py。5. 删除向量await weaviate_db.delete(ids)通过Filter.by_id().contains_any(ids)与data.delete_many批量删除指定对象weaviate.py。6. 删除集合weaviate_db.delete_collection()直接删除整个集合weaviate.py测试夹具在用例结束后用它清理test_collection。测试用例佐证test_weaviate.py 使用embedding_modelmock768 维随机向量验证了完整生命周期add两条文档后查询断言返回top_k条结果且首条分数高于次条fetch返回 768 维向量is_exist对已存在与不存在 ID 分别返回True/Falsedelete后再次查询只剩一条结果。这套用例可直接作为接入 Weaviate 后的冒烟验证脚本参考。相似度分数如何计算AutoRAG 与 Weaviate 之间的分数换算由distance_to_score(distance, similarity_metric)完成weaviate.py即先取 Weaviate 查询返回的metadata.distance再按度量换算为相似度分数Cosine余弦Score 1 - distanceWeaviate 的 cosine 距离取值区间为 [0, 2]换算后分数落在 [-1, 1]数值越大表示越相似。Inner Product内积Score -distanceL2欧氏距离Score -distance需要说明的是关联文档正文中给出的余弦公式为Score 2 - distance而当前仓库源码distance_to_score的实际实现为1 - distance。以当前仓库实际代码为准余弦分支换算逻辑为1 - distanceip与l2两个分支与文档一致-distance。两种换算都遵循“距离越小、分数越高”的单调关系因此排序结果一致但具体分数值会因公式不同而存在差异——如果你在调优阈值或分析分数分布请以当前仓库源码实现为准。在 RAG 管线中的完整工作流将 Weaviate 接入 AutoRAG 优化流程后典型工作流如下摄取Ingestvectordb_ingest_api按embedding_batch将语料分批调用vectordb.add并在摄取前通过is_exist跳过已存在的doc_idsemanticretrieval/vectordb.py。检索Retrievalsemantic_retrieval节点module_type: vectordb对每条查询调用vectordb.query取回 top_k 结果再由检索评估指标retrieval_f1、retrieval_recall、retrieval_precision参与节点策略寻优。下游生成检索结果经prompt_maker组装进提示词{retrieved_contents}交由generator生成答案。关于 full_ingest 的取舍AutoRAG 的full_ingest选项与向量数据库摄取开销直接相关详见 legacy/docs/source/integration/vectordb/vectordb.md默认True时会校验corpus.parquet中所有 ID 是否已入库语料很大时耗时且昂贵建议大语料场景设为False此时仅校验 QA 数据中retrieval_gt涉及的 ID该检查不可关闭。可通过 CLI 参数--full_ingest False或在 Python 中调用Evaluator.start_trial(..., full_ingestFalse)关闭。容错机制与注意事项服务不可用时的内存回退当前仓库的BaseVectorStore内置了内存回退机制当 Weaviate 服务连接失败或集合初始化异常时构造器会打印 warning 日志Falling back to in-memory Weaviate store ...并以weaviate:{collection_name}为键启用进程内存储见 weaviate.py 与 base.py。回退模式使用基于哈希的词袋式 fallback 嵌入仍可支撑add/query/fetch/is_exist/delete全流程便于在无服务环境下做功能验证但不应视为生产存储。这解释了为什么在无 Docker 环境中实例化 Weaviate 也能运行测试级代码。实践建议保持嵌入模型一致摄取与查询必须使用同一embedding_model否则向量空间不一致会导致检索失效。text_key对齐 schema向已有集合写入时text_key必须与集合现有属性名一致否则写入失败会体现在batch.failed_objects日志中。按需调小embedding_batch嵌入阶段遇到超时或内存问题时优先调低embedding_batch。云端凭据用环境变量云形态下使用${WEAVIATE_URL}、${WEAVIATE_API_KEY}占位符运行前确保环境变量已设置。similarity_metric决定索引与分数语义它同时影响 HNSW 索引的距离度量、查询返回的 distance 以及distance_to_score的换算分支修改后需重新摄取数据。以上要点结合 weaviate.py、base.py、init.py、test_weaviate.py 与 semanticretrieval/vectordb.py 即可完整复现并调试 AutoRAG × Weaviate 的接入方案。【免费下载链接】AutoRAGAutoRAG: Now your agent can find anything in your computer. It gets smarter if you are using it frequently.项目地址: https://gitcode.com/GitHub_Trending/au/AutoRAG创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考