Weaviate：混合检索和 multi-location

#Weaviate 与其他向量数据库的区别

Weaviate 是一个开源向量数据库，其代码发布在 GitHub 上。与 FAISS 等库不同，它是一个服务器：存储对象（文本和属性）、向量及搜索索引，并通过 API 响应查询。它有三项功能，使其区别于简单的向量存储。第一项是内置编码：您插入对象后，配置好的模块会将文本转换为向量；查询使用自然语言编写，而非浮点数数组。这种设计消除了一类程序错误（维度不兼容、问题与语料库使用不同的模型编码），因为同一个模块会处理两端的编码。

第二项是混合检索，在一次查询中结合关键词和向量。第三项是多租户：同一个部署可以托管多个相互隔离的数据集，每个客户、部门或用户各有一个。这些功能的代价是需要运行一个组件，并管理其内存、备份和更新；相比之下，文件模式下的 ChromaDB 只是一个 Python 库。

#让一切都留在本地：需要检查的三个设置

编码模块是一种具有定位的依赖项。选择第三方托管的向量化器，相当于将您的每一份文档和每一个问题都发送到别处；而选择 Ollama 模块则可将计算保留在本地设备上。另外两个设置不太明显，同样需要同等关注。

向量编码器

使用 text2vec-ollama，该工具调用您本地的 Ollama 实例；文档说明此情况下无需 API 密钥。请注意地址：如果 Weaviate 运行在容器中且 Ollama 部署在主机上，文档建议使用 host.docker.internal，以便容器能够访问主机。

遥测数据

Weaviate 的文档指出，其默认会收集遥测数据：服务器版本、操作系统、使用的模块、对象和集合的数量，每 24 小时发送一次；文档明确说明，不会收集您数据中的任何内容。如需禁用该功能，请将 DISABLE_TELEMETRY 设置为 true。在需要完全封闭的安装环境中，请设置该参数。

匿名访问

快速启动的docker run命令将AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED设置为true，但文档强烈建议在非开发或评估场景下禁用匿名访问。一旦从除本地设备外的其他设备可访问8080端口，请立即启用API密钥认证。

#搭配 Docker 和 Ollama 安装 Weaviate

1. 01
   准备好 Ollama 和嵌入模型

   安装 Ollama，然后使用命令 ollama pull bge-m3 下载模型。
2. 02
   编写docker-compose.yml文件

   该文件声明了 Weaviate 容器及其数据卷、启用 Ollama 模块、关闭遥测，以及对宿主机的访问。
3. 03
   启动并验证

   运行 docker compose up -d，然后测试地址 http://localhost:8080/v1/meta：响应将列出当前激活的模块。
4. 04
   创建与模块关联的集合

   集合中指定了由哪个 Ollama 模型对哪些属性进行向量化。

services:
  weaviate:
    image: cr.weaviate.io/semitechnologies/weaviate:1.39.7
    ports:
      - "8080:8080"
      - "50051:50051"
    volumes:
      - weaviate_data:/var/lib/weaviate
    restart: on-failure:0
    extra_hosts:
      - "host.docker.internal:host-gateway"   # utile sous Linux pour joindre Ollama sur l'hôte
    environment:
      QUERY_DEFAULTS_LIMIT: 25
      AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED: 'true'   # à fermer si le port est exposé
      PERSISTENCE_DATA_PATH: '/var/lib/weaviate'
      ENABLE_MODULES: 'text2vec-ollama'
      DISABLE_TELEMETRY: 'true'
      CLUSTER_HOSTNAME: 'node1'
volumes:
  weaviate_data:

版本号 1.39.7 是撰写本文时 Weaviate 官方文档的版本；请以安装页面上显示的当前版本为准。文档中的快速启动配置使用端口 8080（HTTP）和 50051（gRPC）。

#数据模式：集合、属性、向量化器、租户

import weaviate
from weaviate.classes.config import Configure, Property, DataType

client = weaviate.connect_to_local()

client.collections.create(
    "Document",
    vector_config=[
        Configure.Vectors.text2vec_ollama(
            name="contenu_vecteur",
            source_properties=["contenu"],
            api_endpoint="http://host.docker.internal:11434",
            model="bge-m3",
        )
    ],
    properties=[
        Property(name="contenu", data_type=DataType.TEXT),
        Property(name="source", data_type=DataType.TEXT),
    ],
)

coll = client.collections.use("Document")
coll.data.insert_many([
    {"contenu": "Le délai de préavis est de trois mois.", "source": "contrat.pdf"},
    {"contenu": "Le loyer est révisé chaque année au 1er janvier.", "source": "bail.pdf"},
])
client.close()

该结构遵循官方文档：vector_config、一个具名的向量化器、源属性以及一个 Ollama 端点。Weaviate 默认将文本类型的属性按字母顺序排序并拼接后进行向量化；source_properties 可以将计算范围限制在所需属性上，使文件名不参与向量计算。

#Weaviate中的混合搜索功能

语义搜索能够找到语义相近的段落，但无法匹配精确的字符串，例如发票号码、物料编号、错误代码或专有名词。Weaviate的混合搜索结合向量搜索和BM25F关键词搜索的结果，通过融合两个结果集并采用可配置的权重和融合方法实现。参数alpha用于调节平衡：根据文档说明，alpha值为1时表示纯向量搜索，alpha值为0时表示纯关键词搜索。若不设置alpha，实际权重将取决于客户端，因此应始终显式指定。

coll = client.collections.use("Document")
res = coll.query.hybrid(query="préavis contrat CDI", alpha=0.5, limit=5)
for o in res.objects:
    print(o.properties["source"], o.properties["contenu"][:80])

自 1.24 版本起，默认的融合方法为相对分数融合；另一种选择是排名融合。其原理及两种方法的选择详见混合检索指南。在技术语料库上，这通常体现为用户信任的系统与被放弃的系统之间的差异：纯向量检索的失败恰恰体现在用户认为是显而易见的查询上。

#多租户：每个用户组对应一个租户

多租户功能将一个集合划分为多个分片，每个租户对应一个分片。文档对此的描述是：每个租户都存储在独立的分片中，一个租户的数据对另一个租户不可见。该功能默认关闭，可在集合定义中通过 multi_tenancy_config 启用。如果多个群体查询同一个系统（中小企业的客户、企业的各个部门、家庭成员），这就在系统结构层面回答了“这个人能否检索到这份文档？”这一问题，比事后应用的过滤器安全得多，也比提示词中的一条指令安全得多得多。

from weaviate.classes.config import Configure
from weaviate.classes.tenants import Tenant

client.collections.create(
    "DocumentClient",
    multi_tenancy_config=Configure.multi_tenancy(enabled=True),
)
coll = client.collections.use("DocumentClient")
coll.tenants.create([Tenant(name="client_a"), Tenant(name="client_b")])

# Toute requête passe par un tenant : les autres restent invisibles
res = coll.with_tenant("client_a").query.hybrid(query="préavis", limit=3)

租户很轻量：文档指出，每个节点可以有 50,000 个或更多活跃分片。租户有不同的状态（ACTIVE、INACTIVE、OFFLOADED）：非活跃租户存储在磁盘上，不占用内存，因此可以托管大量小型数据集，只让实际使用的数据集保持活跃。租户名称只允许包含字母、数字、下划线和连字符。

#Weaviate 运行所需的成本

Weaviate 是一个需要实际部署的服务：需要容器、持久化存储，以及与向量规模成正比的内存。容量规划文档明确指出了这一限制：HNSW 索引必须存放在内存中，内存容量决定数据集的最大规模，但不会直接影响查询速度。文档给出的经验法则是：按所有向量内存占用总量的两倍来预估内存需求。

empreinte d'un vecteur = dimensions × 4 octets (float32)
mémoire estimée   = 2 × nombre de vecteurs × empreinte d'un vecteur

Exemple, bge-m3 (1 024 dimensions) :
  1 024 × 4 = 4 096 octets par vecteur
  100 000 passages → 2 × 100 000 × 4 096 ≈ 0,8 Go
  1 000 000 passages → 2 × 1 000 000 × 4 096 ≈ 8,2 Go

这里将 bge-m3 的维度假定为 1 024，需查阅您所用模型的说明页面加以核实。对于个人或中小企业的语料库（数万段文本），索引占用的内存较少；当文本段落达到数百万时，内存占用才成为需要关注的问题。Weaviate 提供向量压缩功能：文档推荐旋转量化（RQ），也提到乘积量化（PQ）、二进制量化（BQ）和标量量化（SQ），代价是少量信息损失。还要加上本地编码模块：Ollama 在与语言模型相同的机器上运行嵌入模型。在单台机器上，需要决定由哪个模型占用显卡，或者接受索引构建与推理相互影响。

#提供自定义向量，或从ChromaDB迁移

编码模块并非必需。Weaviate 的文档介绍了“自带向量”（bring your own vectors）的方法：您不让数据库计算嵌入向量，而是提供自己已有的向量，无论是自定义的还是预先生成的。在 Python 客户端中，此时通过 Configure.Vectors.self_provided 声明一个具名向量。这是从 ChromaDB 迁移最经济的方式：重新读取文档和已经计算好的向量（Chroma 可以通过 include 选项返回它们），然后将它们发送到 Weaviate，无需再次调用嵌入模型。检查两点可以避免意外问题：整个集合中的向量维度必须一致，而且问题必须使用原来的模型进行编码，因为 Weaviate 不会替您完成这一步。

什么时候应优先选择内置编码？当您希望直接用文本编写查询、添加文档时无需编写计算代码，并由配置保证所用模型的一致性时。什么时候应优先使用自己的向量？当您已有嵌入处理流程、必须使用所有模块都未提供的模型，或希望更换向量数据库而不必重新计算全部向量时。

#Weaviate 或其他向量数据库

如果您犹豫不决，就从最简单的方案开始：用 ChromaDB 制作原型，等出现具体需求（隔离、原生混合检索、数据规模）时，再迁移到服务。只要保留源文档和索引脚本，就可以改变这一选择。

#关于Weaviate的常见问题

• 混合搜索：BM25 + 向量搜索
• Qdrant：本地 RAG 的向量数据库
• pgvector：PostgreSQL 中的向量搜索
• FAISS：向量搜索背后的库
• 使用 ChromaDB 和 Ollama 进行本地 RAG

• 来源：Weaviate，混合检索技术
• 来源：Weaviate，Ollama模块
• 来源：Weaviate，遥测数据
• 来源：Weaviate，资源与内存