向量操作 #

本章详细介绍 Weaviate 的向量操作功能。

向量生成方式 #

向量生成流程 #

text 
向量生成方式：

┌─────────────────────────────────────────────────────────────┐
│                     Weaviate 向量生成                        │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  方式一：自动向量化                                          │
│  ┌─────────┐     ┌─────────────┐     ┌─────────┐           │
│  │ 文本数据 │ ──→ │ Vectorizer  │ ──→ │  向量   │           │
│  └─────────┘     │   Module    │     └─────────┘           │
│                  └─────────────┘                             │
│                                                              │
│  方式二：自定义向量                                          │
│  ┌─────────┐     ┌─────────────┐     ┌─────────┐           │
│  │ 文本数据 │ ──→ │ 外部模型    │ ──→ │  向量   │           │
│  └─────────┘     └─────────────┘     └─────────┘           │
│                        │                                    │
│                        ▼                                    │
│                  ┌─────────────┐                            │
│                  │  Weaviate   │                            │
│                  │   存储      │                            │
│                  └─────────────┘                            │
│                                                              │
└─────────────────────────────────────────────────────────────┘

自动向量化 #

OpenAI 向量化 #

python 
import weaviate.classes as wvc

articles = client.collections.create(
    name="Article",
    vectorizer_config=wvc.config.Configure.Vectorizer.text2vec_openai(
        model="text-embedding-3-small",
        model_version="latest",
        type="text",
        vectorize_class_name=False
    ),
    properties=[
        wvc.config.Property(
            name="title",
            data_type=wvc.config.DataType.TEXT,
            skip_vectorization=False
        ),
        wvc.config.Property(
            name="content",
            data_type=wvc.config.DataType.TEXT,
            skip_vectorization=False
        ),
        wvc.config.Property(
            name="category",
            data_type=wvc.config.DataType.TEXT,
            skip_vectorization=True
        )
    ]
)

articles.data.insert({
    "title": "Weaviate 入门指南",
    "content": "Weaviate 是一个云原生向量数据库...",
    "category": "技术"
})

Cohere 向量化 #

python 
articles = client.collections.create(
    name="Article",
    vectorizer_config=wvc.config.Configure.Vectorizer.text2vec_cohere(
        model="embed-multilingual-v3.0",
        truncate="END",
        vectorize_class_name=False
    ),
    properties=[
        wvc.config.Property(name="title", data_type=wvc.config.DataType.TEXT),
        wvc.config.Property(name="content", data_type=wvc.config.DataType.TEXT)
    ]
)

HuggingFace 向量化 #

python 
articles = client.collections.create(
    name="Article",
    vectorizer_config=wvc.config.Configure.Vectorizer.text2vec_huggingface(
        model="sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2",
        options={
            "waitForModel": True,
            "useGPU": False
        }
    ),
    properties=[
        wvc.config.Property(name="title", data_type=wvc.config.DataType.TEXT),
        wvc.config.Property(name="content", data_type=wvc.config.DataType.TEXT)
    ]
)

自定义向量 #

插入自定义向量 #

python 
import numpy as np
from openai import OpenAI

openai_client = OpenAI()

def get_embedding(text):
    response = openai_client.embeddings.create(
        model="text-embedding-3-small",
        input=text
    )
    return response.data[0].embedding

articles = client.collections.create(
    name="Article",
    vectorizer_config=wvc.config.Configure.Vectorizer.none(),
    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 是一个云原生向量数据库"
vector = get_embedding(text)

articles.data.insert(
    properties={
        "title": "Weaviate 简介",
        "content": text
    },
    vector=vector
)

批量自定义向量 #

python 
texts = [
    "向量数据库是 AI 应用的核心组件",
    "语义搜索基于向量相似性",
    "RAG 结合检索和生成能力"
]

vectors = [get_embedding(t) for t in texts]

with articles.batch.dynamic() as batch:
    for text, vector in zip(texts, vectors):
        batch.add_object(
            properties={"title": text[:20], "content": text},
            vector=vector
        )

多向量配置 #

创建多向量 Collection #

python 
articles = client.collections.create(
    name="Article",
    vectorizer_config=[
        wvc.config.Configure.NamedVectors.text2vec_openai(
            name="title_vector",
            source_properties=["title"],
            model="text-embedding-3-small"
        ),
        wvc.config.Configure.NamedVectors.text2vec_openai(
            name="content_vector",
            source_properties=["content"],
            model="text-embedding-3-large"
        ),
        wvc.config.Configure.NamedVectors.text2vec_openai(
            name="full_vector",
            source_properties=["title", "content"],
            model="text-embedding-3-small"
        )
    ],
    properties=[
        wvc.config.Property(name="title", data_type=wvc.config.DataType.TEXT),
        wvc.config.Property(name="content", data_type=wvc.config.DataType.TEXT)
    ]
)

指定向量搜索 #

python 
articles = client.collections.get("Article")

response = articles.query.near_text(
    query="向量数据库",
    target_vector="title_vector",
    limit=5
)

print("基于标题向量的搜索结果:")
for obj in response.objects:
    print(f"- {obj.properties['title']}")

response = articles.query.near_text(
    query="向量数据库",
    target_vector="content_vector",
    limit=5
)

print("\n基于内容向量的搜索结果:")
for obj in response.objects:
    print(f"- {obj.properties['title']}")

多向量组合搜索 #

python 
response = articles.query.near_text(
    query="向量数据库",
    target_vector=["title_vector", "content_vector"],
    limit=5
)

向量量化 #

量化可以显著减少内存占用，适合大规模向量数据。

PQ 量化 #

python 
articles = client.collections.create(
    name="Article",
    vectorizer_config=wvc.config.Configure.Vectorizer.text2vec_openai(),
    vector_index_config=wvc.config.Configure.VectorIndex.hnsw(
        distance_metric=wvc.config.VectorDistance.COSINE,
        quantizer=wvc.config.Configure.VectorIndex.Quantizer.pq(
            segments=64,
            centroids=256,
            training_limit=100000
        )
    ),
    properties=[
        wvc.config.Property(name="title", data_type=wvc.config.DataType.TEXT),
        wvc.config.Property(name="content", data_type=wvc.config.DataType.TEXT)
    ]
)

BQ 量化 #

python 
articles = client.collections.create(
    name="Article",
    vectorizer_config=wvc.config.Configure.Vectorizer.text2vec_openai(),
    vector_index_config=wvc.config.Configure.VectorIndex.hnsw(
        distance_metric=wvc.config.VectorDistance.COSINE,
        quantizer=wvc.config.Configure.VectorIndex.Quantizer.bq(
            cache=True
        )
    ),
    properties=[
        wvc.config.Property(name="title", data_type=wvc.config.DataType.TEXT),
        wvc.config.Property(name="content", data_type=wvc.config.DataType.TEXT)
    ]
)

量化对比 #

text 
量化方式对比：

┌─────────────────────────────────────────────────────────────┐
│                        量化对比                              │
├──────────────┬──────────────┬──────────────┬───────────────┤
│     方式     │   内存占用   │    召回率    │     速度      │
├──────────────┼──────────────┼──────────────┼───────────────┤
│ 无量化       │ 100%         │ 100%         │ 基准          │
│ PQ 量化      │ ~10%         │ ~95%         │ 更快          │
│ BQ 量化      │ ~3%          │ ~90%         │ 最快          │
└──────────────┴──────────────┴──────────────┴───────────────┘

向量索引配置 #

HNSW 参数详解 #

python 
articles = 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=256,
        max_connections=64,
        ef=128,
        dynamic_ef_min=100,
        dynamic_ef_max=500,
        dynamic_ef_factor=8,
        skip=False,
        cleanup_interval_seconds=300
    ),
    properties=[
        wvc.config.Property(name="title", data_type=wvc.config.DataType.TEXT)
    ]
)

参数说明 #

text 
HNSW 参数说明：

ef_construction:
├── 构建索引时的搜索范围
├── 值越大，索引质量越高
├── 构建时间越长
└── 推荐值: 128-512

max_connections:
├── 每个节点的最大连接数
├── 值越大，召回率越高
├── 内存占用越大
└── 推荐值: 16-64

ef:
├── 查询时的搜索范围
├── 值越大，召回率越高
├── 查询时间越长
└── 推荐值: 64-256

动态 EF 配置 #

python 
vector_index_config=wvc.config.Configure.VectorIndex.hnsw(
    ef=-1,
    dynamic_ef_min=50,
    dynamic_ef_max=500,
    dynamic_ef_factor=8
)

距离度量 #

配置距离度量 #

python 
articles_cosine = client.collections.create(
    name="ArticleCosine",
    vectorizer_config=wvc.config.Configure.Vectorizer.none(),
    vector_index_config=wvc.config.Configure.VectorIndex.hnsw(
        distance_metric=wvc.config.VectorDistance.COSINE
    ),
    properties=[
        wvc.config.Property(name="title", data_type=wvc.config.DataType.TEXT)
    ]
)

articles_dot = client.collections.create(
    name="ArticleDot",
    vectorizer_config=wvc.config.Configure.Vectorizer.none(),
    vector_index_config=wvc.config.Configure.VectorIndex.hnsw(
        distance_metric=wvc.config.VectorDistance.DOT
    ),
    properties=[
        wvc.config.Property(name="title", data_type=wvc.config.DataType.TEXT)
    ]
)

articles_l2 = client.collections.create(
    name="ArticleL2",
    vectorizer_config=wvc.config.Configure.Vectorizer.none(),
    vector_index_config=wvc.config.Configure.VectorIndex.hnsw(
        distance_metric=wvc.config.VectorDistance.L2_SQUARED
    ),
    properties=[
        wvc.config.Property(name="title", data_type=wvc.config.DataType.TEXT)
    ]
)

距离度量选择 #

text 
距离度量选择指南：

余弦相似度 (Cosine):
├── 最常用的度量方式
├── 关注向量方向
├── 适合文本嵌入
└── 推荐用于归一化向量

点积 (Dot Product):
├── 计算速度最快
├── 适合归一化向量
├── 与余弦等价（归一化时）
└── 推荐用于推荐系统

L2 距离:
├── 计算绝对距离
├── 受向量长度影响
├── 适合图像特征
└── 推荐用于未归一化向量

向量检索优化 #

预过滤 vs 后过滤 #

python 
articles = client.collections.get("Article")

response = articles.query.near_text(
    query="向量数据库",
    filters=Filter.by_property("category").equal("技术"),
    limit=10
)

向量搜索参数 #

python 
response = articles.query.near_text(
    query="向量数据库",
    certainty=0.7,
    distance=0.3,
    limit=10,
    offset=0,
    autocut=1
)

向量搜索与分页 #

python 
response = articles.query.near_text(
    query="向量数据库",
    limit=10,
    offset=20
)

print(f"Total: {response.total_count}")
for obj in response.objects:
    print(f"- {obj.properties['title']}")

向量操作示例 #

完整示例 #

python 
import weaviate
import weaviate.classes as wvc
from openai import OpenAI
import numpy as np

client = weaviate.connect_to_local()

openai_client = OpenAI()

def get_embedding(text):
    response = openai_client.embeddings.create(
        model="text-embedding-3-small",
        input=text
    )
    return response.data[0].embedding

client.collections.delete("Document")

documents = client.collections.create(
    name="Document",
    vectorizer_config=wvc.config.Configure.Vectorizer.none(),
    vector_index_config=wvc.config.Configure.VectorIndex.hnsw(
        distance_metric=wvc.config.VectorDistance.COSINE,
        ef_construction=256,
        max_connections=64
    ),
    properties=[
        wvc.config.Property(name="text", data_type=wvc.config.DataType.TEXT),
        wvc.config.Property(name="source", data_type=wvc.config.DataType.TEXT)
    ]
)

docs = [
    ("Weaviate 是一个云原生向量数据库", "官方文档"),
    ("向量搜索基于高维向量相似性", "技术博客"),
    ("RAG 结合检索和生成能力", "论文"),
    ("知识图谱表示实体间关系", "百科"),
    ("Embedding 将文本转为向量", "教程")
]

with documents.batch.dynamic() as batch:
    for text, source in docs:
        vector = get_embedding(text)
        batch.add_object(
            properties={"text": text, "source": source},
            vector=vector
        )

print("Documents inserted\n")

query = "什么是向量数据库"
query_vector = get_embedding(query)

response = documents.query.near_vector(
    near_vector=query_vector,
    limit=3,
    return_properties=["text", "source"]
)

print(f"Query: {query}")
print("\nResults:")
for obj in response.objects:
    print(f"- {obj.properties['text']} ({obj.properties['source']})")
    print(f"  Distance: {obj.metadata.distance:.4f}")

client.close()

小结 #

本章介绍了 Weaviate 的向量操作：

  • 自动向量化配置
  • 自定义向量插入
  • 多向量配置
  • 向量量化
  • 索引参数优化
  • 距离度量选择

下一步 #

继续学习 搜索查询，了解 Weaviate 强大的搜索能力！

最后更新：2026-04-04