📦 一、Weaviate 简介

• **语言：**Go
• 核心特性：
  • 原生支持 向量 + 关键词（BM25）混合搜索
  • 内置 语义图谱（对象间可建关系）
  • 支持 模块化 AI pipeline（embedding、rerank、生成）
  • 自动 schema 推断（动态数据结构）
  • 多租户（v1.23+）、RBAC（企业版）
• 适用场景：RAG 知识库、智能客服、企业知识图谱、AI Agent 记忆系统

🚀 二、单机部署（开发/测试首选）

方式 1：Docker（最简单，推荐）

场景 A：使用 OpenAI Embedding（需 API Key）

# docker-compose.weaviate.yml
version: '3.8'
services:
  weaviate:
    image: semitechnologies/weaviate:1.25.4
    ports:
      - "8080:8080"   # HTTP API
      - "50051:50051" # gRPC (可选)
    volumes:
      - ./weaviate_data:/var/lib/weaviate
    environment:
      # 基础配置
      QUERY_DEFAULTS_LIMIT: 25
      AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED: 'false'  # 关闭匿名访问
      AUTHORIZATION_ADMINLIST_ENABLED: 'true'
      AUTHORIZATION_ADMINLIST_USERS: 'admin@example.com'

      # 启用模块
      ENABLE_MODULES: 'text2vec-openai,generative-openai,reranker-cohere'

      # OpenAI 配置
      OPENAI_APIKEY: 'sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'  # 替换为你的 Key
      OPENAI_ORGANIZATION: ''  # 可选

      # 默认向量化器
      DEFAULT_VECTORIZER_MODULE: 'text2vec-openai'

      # 集群设置（单机可忽略）
      CLUSTER_HOSTNAME: 'node1'

      # 持久化
      PERSISTENCE_DATA_PATH: '/var/lib/weaviate'
    restart: unless-stopped

启动：

mkdir weaviate_data
docker-compose -f docker-compose.weaviate.yml up -d

✅ 访问 Web UI：http://localhost:8080
✅ GraphQL API：http://localhost:8080/v1/graphql

场景 B：本地 Embedding（无需外网，如 text2vec-transformers）

# docker-compose.local.yml
version: '3.8'
services:
  weaviate:
    image: semitechnologies/weaviate:1.25.4
    ports:
      - "8080:8080"
    volumes:
      - ./weaviate_data:/var/lib/weaviate
    environment:
      ENABLE_MODULES: 'text2vec-transformers'
      DEFAULT_VECTORIZER_MODULE: 'text2vec-transformers'
      TRANSFORMERS_INFERENCE_API: 'http://t2v-transformers:8080'
      CLUSTER_HOSTNAME: 'node1'
      PERSISTENCE_DATA_PATH: '/var/lib/weaviate'

  t2v-transformers:
    image: semitechnologies/transformers-inference:sentence-transformers-all-MiniLM-L6-v2
    ports:
      - "8081:8080"
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 0  # CPU 模式；若用 GPU，设为 1 并启用 nvidia runtime

💡 此方案完全离线，适合内网/敏感数据场景。

方 式 2：二进制安装（不推荐，仅特殊环境）

Weaviate 官方 不提供通用二进制包，建议始终使用 Docker 或 Helm。

🌐 三、集群部署（生产高可用）

Weaviate 使用 Raft 共识协议实现分布式一致性。

Kubernetes 部署（Helm Chart）

# 添加官方 Helm 仓库
helm repo add weaviate https://weaviate.github.io/weaviate-helm
helm repo update

# 创建 values.yaml
cat > weaviate-values.yaml <<EOF
replicas: 3

env:
  enabled_modules: "text2vec-openai,generative-openai,reranker-cohere"
  default_vectorizer_module: "text2vec-openai"
  openai_apikey: "sk-xxxxxxxxxxxxxxxx"

auth:
  adminList:
    enabled: true
    users:
      - "admin@example.com"

persistence:
  enabled: true
  size: 100Gi

monitoring:
  metrics:
    enabled: true
EOF

# 安装
helm install weaviate-cluster weaviate/weaviate -f weaviate-values.yaml

✅ 支持：自动扩缩容、Prometheus 监控、持久化存储、TLS

🔐 四、安全与认证

1. API Key / OIDC（v1.24+）

Weaviate 支持多种认证方式：

• Anonymous access（开发用，不推荐生产）
• Admin List（基于邮箱白名单）
• OIDC（对接 Auth0 / Okta / Keycloak）
• API Keys（v1.25+ 实验性）

示例：启用 OIDC

environment:
  AUTHENTICATION_OIDC_ENABLED: 'true'
  AUTHENTICATION_OIDC_ISSUER_URL: 'https://your-okta-domain/oauth2/default'
  AUTHENTICATION_OIDC_CLIENT_ID: 'weaviate-client'
  AUTHORIZATION_RBAC_ENABLED: 'true'  # 企业版

⚠️ 开源版 无 RBAC 细粒度权限，仅支持“管理员/非管理员”

2. 备份与恢复（企业版 or v1.23+ 开源版）

Weaviate 支持 备份到 S3 / GCS / 文件系统。
创建备份（GraphQL）：

mutation {
  BackupCreate(
    backend: "filesystem"
    include: ["Articles"]
  ) {
    status
    path
  }
}

恢复备份：

mutation {
  BackupRestore(
    backend: "filesystem"
    include: ["Articles"]
    id: "2025-12-03T08:00:00"
  ) {
    status
  }
}

💾 开源版仅支持 filesystem 后端；企业版支持云存储。

💻 五、Python 应用集成

1. 原生 SDK（v4+，推荐）

import weaviate
import weaviate.classes as wvc

# 连接（无认证）
client = weaviate.connect_to_local(host="localhost", port=8080)

# 或带 OIDC/API Key（v1.25+）
# client = weaviate.connect_to_custom(
#     http_host="your-weaviate.com",
#     http_port=443,
#     http_secure=True,
#     headers={"Authorization": "Bearer <api-key>"}
# )

# 创建 Collection（Schema）
client.collections.create(
    name="Article",
    vectorizer_config=wvc.config.Configure.Vectorizer.text2vec_openai(),
    generative_config=wvc.config.Configure.Generative.openai(),
    properties=[
        wvc.config.Property(name="title", data_type=wvc.config.DataType.TEXT),
        wvc.config.Property(name="content", data_type=wvc.config.DataType.TEXT),
        wvc.config.Property(name="url", data_type=wvc.config.DataType.TEXT),
    ]
)

# 插入数据
articles = client.collections.get("Article")
articles.data.insert(
    properties={
        "title": "Weaviate RAG 教程",
        "content": "Weaviate 是一个开源向量数据库...",
        "url": "https://example.com"
    }
)

# 混合搜索（关键词 + 向量）
response = articles.query.hybrid(
    query="向量数据库教程",
    alpha=0.75,  # 0=纯 BM25, 1=纯向量
    limit=3,
    filters=wvc.query.Filter.by_property("url").like("*example*")
)

for o in response.objects:
    print(o.properties["title"])

✅ 安装：pip install weaviate-client

2. LangChain 集成（RAG 场景）

from langchain_weaviate.vectorstores import Weaviate
from langchain_openai import OpenAIEmbeddings
from langchain_core.documents import Document

import weaviate

client = weaviate.connect_to_local()

# 注意：LangChain 通常使用外部 embedding（而非 Weaviate 内置）
embeddings = OpenAIEmbeddings()
vector_store = Weaviate(
    client=client,
    index_name="LangChainDocs",
    text_key="text",
    embedding=embeddings,
    attributes=["source"]
)

# 添加文档
docs = [Document(page_content="Weaviate 支持混合搜索", metadata={"source": "blog"})]
vector_store.add_documents(docs)

# 检索
results = vector_store.similarity_search("混合搜索", k=1)
print(results[0].page_content)

⚠️ 若使用 Weaviate 内置 embedding，不要传 embedding 参数，改用 by_text=True

⚙️ 六、性能调优建议

优化项	建议
HNSW 索引	maxConnections=32, efConstruction=128, ef=256
内存	至少 8GB RAM（每 100 万向量）
SSD	必须使用 SSD，HDD 性能极差
异步索引	设置 async_indexing: true（v1.20+）
Payload 索引	对高频过滤字段（如 category）创建 indexInverted: true
批量导入	使用 batch API，每批 100~1000 条

示例：批量插入（高效）

with articles.batch.dynamic() as batch:
    for doc in large_document_list:
        batch.add_object(properties=doc)

🛠 七、常见问题排查

❌ 问题1：Module ‘text2vec-openai’ not found

• 检查 ENABLE_MODULES 是否包含该模块
• 检查 OPENAI_APIKEY 是否正确且有额度

❌ 问题2：Connection refused

• 检查容器是否运行：docker ps
• 检查端口映射：8080:8080

❌ 问题3：写入慢 / 内存溢出

• 减小 batch size
• 增加 GOGC 环境变量（Go GC 调优）：

GOGC=20

❌ 问题4：混合搜索无结果

• 确保字段是 text 类型（非 string）
• string 字段不参与 BM25，仅用于精确匹配

📊 八、监控与可观测性

• Metrics：/metrics（Prometheus 格式）
  • weaviate_batch_operations_total
  • weaviate_query_duration_seconds
• 日志：stdout（Docker）或 /var/log/weaviate.log
• Grafana Dashboard：官方提供 Weaviate Monitoring Dashboard

📚 九、官方资源

• 官网：https://weaviate.io
• 文档：https://weaviate.io/developers/weaviate
• GitHub：https://github.com/weaviate/weaviate

✅ 总结：

Weaviate 是 唯一原生支持“向量 + 关键词 + 生成”一体化的开源向量数据库，特别适合：

• 需要 混合搜索 的 RAG 系统
• 构建 企业知识图谱
• 快速集成 AI 生成能力（如自动摘要、问答）

🎯 选型建议：

• 要混合搜索 → Weaviate
• 要极致性能 → Qdrant
• 要复用 PostgreSQL → pgvector