核心概念 #
本章介绍 Weaviate 的核心概念和数据模型。
数据模型概览 #
text
Weaviate 数据模型层次：
┌─────────────────────────────────────────────────────────────┐
│ Weaviate │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Schema │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ Collection │ │ Collection │ │ Collection │ │ │
│ │ │ (Class) │ │ (Class) │ │ (Class) │ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │
│ │ │ │ │ │ │
│ │ ▼ ▼ ▼ │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ Objects │ │ Objects │ │ Objects │ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
Schema（模式） #
Schema 是 Weaviate 中定义数据结构的顶层概念，类似于关系数据库中的数据库模式。
Schema 的作用 #
text
Schema 定义：
├── Collections（集合/类）
│ └── 定义数据类型
├── Properties（属性）
│ └── 定义字段类型
├── Vectorizer（向量化配置）
│ └── 定义向量化方式
└── Module Config（模块配置）
└── 定义模块参数
Schema 结构 #
json
{
"classes": [
{
"class": "Article",
"description": "文章类",
"vectorizer": "text2vec-openai",
"moduleConfig": {
"text2vec-openai": {
"model": "ada",
"modelVersion": "002",
"type": "text"
}
},
"properties": [
{
"name": "title",
"dataType": ["text"],
"description": "文章标题"
},
{
"name": "content",
"dataType": ["text"],
"description": "文章内容"
},
{
"name": "author",
"dataType": ["Author"],
"description": "作者引用"
}
]
}
]
}
Collection（集合） #
Collection（也称为 Class）是 Weaviate 中存储同类对象的容器，类似于关系数据库中的表。
Collection 定义 #
python
import weaviate.classes as wvc
collection = client.collections.create(
name="Article",
description="文章集合",
vectorizer_config=wvc.config.Configure.Vectorizer.text2vec_openai(
model="ada",
model_version="002"
),
properties=[
wvc.config.Property(
name="title",
data_type=wvc.config.DataType.TEXT,
description="文章标题"
),
wvc.config.Property(
name="content",
data_type=wvc.config.DataType.TEXT,
description="文章内容"
),
wvc.config.Property(
name="views",
data_type=wvc.config.DataType.INT,
description="阅读量"
),
wvc.config.Property(
name="published",
data_type=wvc.config.DataType.DATE,
description="发布日期"
)
]
)
数据类型 #
text
Weaviate 支持的数据类型：
基础类型：
├── text: 文本字符串
├── int: 整数
├── number: 浮点数
├── boolean: 布尔值
├── date: 日期时间（ISO 8601 格式）
├── uuid: UUID 标识符
├── geoCoordinates: 地理坐标
├── phoneNumber: 电话号码
└── blob: 二进制数据（Base64）
数组类型：
├── text[]: 文本数组
├── int[]: 整数数组
└── number[]: 浮点数数组
引用类型：
└── 引用其他 Collection（跨类关联）
引用属性 #
python
collection = client.collections.create(
name="Article",
properties=[
wvc.config.Property(
name="title",
data_type=wvc.config.DataType.TEXT
),
wvc.config.Property(
name="author",
data_type=wvc.config.DataType.TEXT
)
],
references=[
wvc.config.ReferenceProperty(
name="writtenBy",
target_collection="Author"
),
wvc.config.ReferenceProperty(
name="hasCategory",
target_collection="Category"
)
]
)
Object（对象） #
Object 是 Weaviate 中存储的单个数据记录，包含属性数据、向量和引用。
Object 结构 #
text
Object 组成：
├── id: UUID 唯一标识符
├── properties: 属性数据
│ ├── title: "文章标题"
│ ├── content: "文章内容..."
│ └── views: 1000
├── vector: [0.1, 0.2, ...] (向量)
├── references: 引用关系
│ └── writtenBy: [Author UUID]
└── creationTimeUnix: 创建时间
创建对象 #
python
articles = client.collections.get("Article")
uuid = articles.data.insert({
"title": "Weaviate 入门指南",
"content": "Weaviate 是一个云原生向量数据库...",
"views": 1000,
"published": "2024-01-15T10:00:00Z"
})
print(f"Created object with UUID: {uuid}")
批量创建对象 #
python
articles = client.collections.get("Article")
objects = [
{
"title": "向量数据库简介",
"content": "向量数据库是 AI 应用的核心...",
"views": 500
},
{
"title": "RAG 应用实战",
"content": "RAG 是检索增强生成的简称...",
"views": 800
},
{
"title": "语义搜索原理",
"content": "语义搜索基于向量相似性...",
"views": 600
}
]
with articles.batch.dynamic() as batch:
for obj in objects:
batch.add_object(properties=obj)
print(f"Batch import completed")
自定义向量 #
python
import numpy as np
articles = client.collections.get("Article")
vector = np.random.rand(1536).tolist()
uuid = articles.data.insert(
properties={
"title": "自定义向量文章",
"content": "这篇文章使用自定义向量..."
},
vector=vector
)
Vector（向量） #
Vector 是对象在高维空间中的数值表示，是实现语义搜索的核心。
向量生成方式 #
text
向量生成方式：
1. 自动向量化
└── 使用 Vectorizer Module 自动生成
2. 自定义向量
└── 用户自己提供向量
3. 混合模式
└── 部分自动，部分自定义
向量化配置 #
python
import weaviate.classes as wvc
collection = client.collections.create(
name="Article",
vectorizer_config=[
wvc.config.Configure.NamedVectors.text2vec_openai(
name="title_vector",
source_properties=["title"]
),
wvc.config.Configure.NamedVectors.text2vec_openai(
name="content_vector",
source_properties=["content"]
)
],
properties=[
wvc.config.Property(name="title", data_type=wvc.config.DataType.TEXT),
wvc.config.Property(name="content", data_type=wvc.config.DataType.TEXT)
]
)
向量索引 #
text
Weaviate 使用 HNSW 索引：
HNSW (Hierarchical Navigable Small World)：
├── 多层图结构
├── 快速近似搜索
├── 支持动态更新
└── 可配置精度和性能
索引参数：
├── efConstruction: 构建时搜索范围
├── maxConnections: 最大连接数
├── ef: 查询时搜索范围
└── distance: 距离度量方式
向量配置 #
python
collection = client.collections.create(
name="Article",
vectorizer_config=wvc.config.Configure.Vectorizer.none(),
vector_index_config=wvc.config.Configure.VectorIndex.hnsw(
distance_metric=wvc.config.VectorDistance.COSINE,
ef_construction=128,
max_connections=64
)
)
Module（模块） #
Module 是 Weaviate 的扩展机制，提供向量化、生成等能力。
模块类型 #
text
模块类型：
1. 向量化模块 (Vectorizer)
├── text2vec-openai
├── text2vec-cohere
├── text2vec-huggingface
├── text2vec-palm
├── img2vec-neural
└── multi2vec-clip
2. 生成模块 (Generative)
├── generative-openai
├── generative-cohere
└── generative-palm
3. 重排序模块 (Reranker)
└── reranker-cohere
4. 其他模块
├── qna-openai (问答)
├── text-spellcheck (拼写检查)
└── text2vec-contextionary (内置)
模块配置 #
python
collection = client.collections.create(
name="Article",
vectorizer_config=wvc.config.Configure.Vectorizer.text2vec_openai(
model="text-embedding-3-small"
),
generative_config=wvc.config.Configure.Generative.openai(
model="gpt-4"
)
)
查看可用模块 #
python
meta = client.get_meta()
for module_name, module_info in meta.get("modules", {}).items():
print(f"Module: {module_name}")
print(f" Info: {module_info}")
距离度量 #
Weaviate 支持多种向量距离度量方式。
余弦相似度（Cosine） #
text
公式: cos(a, b) = (a · b) / (|a| × |b|)
特点:
├── 关注向量方向
├── 值范围: [-1, 1]
├── 1 表示完全相同方向
└── 适合归一化向量
适用场景:
├── 文本嵌入
├── 语义相似性
└── 推荐系统
点积（Dot Product） #
text
公式: dot(a, b) = Σ(ai × bi)
特点:
├── 计算速度快
├── 适合归一化向量
└── 与余弦相似度等价（归一化时）
适用场景:
├── 推荐系统
├── 性能优先场景
└── 归一化向量
L2 距离（欧几里得） #
text
公式: l2(a, b) = √Σ(ai - bi)²
特点:
├── 计算绝对距离
├── 值范围: [0, ∞)
├── 0 表示完全相同
└── 受向量长度影响
适用场景:
├── 图像特征
├── 物理距离
└── 未归一化向量
配置距离度量 #
python
collection = client.collections.create(
name="Article",
vectorizer_config=wvc.config.Configure.Vectorizer.none(),
vector_index_config=wvc.config.Configure.VectorIndex.hnsw(
distance_metric=wvc.config.VectorDistance.COSINE
)
)
租户与多租户 #
Weaviate 支持多租户架构，实现数据隔离。
启用多租户 #
python
collection = client.collections.create(
name="Article",
multi_tenancy_config=wvc.config.Configure.multi_tenancy(
enabled=True
)
)
租户操作 #
python
articles = client.collections.get("Article")
articles.tenants.create(
tenants=[
wvc.tenants.Tenant(name="tenant1"),
wvc.tenants.Tenant(name="tenant2")
]
)
tenant1_articles = articles.with_tenant("tenant1")
tenant1_articles.data.insert({
"title": "租户1的文章",
"content": "这是租户1的数据..."
})
复制与分片 #
复制配置 #
python
collection = client.collections.create(
name="Article",
replication_config=wvc.config.Configure.replication(
factor=3
)
)
分片配置 #
python
collection = client.collections.create(
name="Article",
sharding_config=wvc.config.Configure.sharding(
virtual_per_physical=128,
desired_count=3
)
)
小结 #
本章介绍了 Weaviate 的核心概念：
- Schema：定义数据结构
- Collection：存储同类对象
- Object：单个数据记录
- Vector：高维向量表示
- Module：扩展能力
下一步 #
理解核心概念后，继续学习 快速开始，动手实践 Weaviate！
最后更新：2026-04-04