安装与配置 #

本章介绍 Weaviate 的多种安装方式和配置方法。

安装方式概览 #

text 
Weaviate 安装方式：

┌─────────────────────────────────────────────────────────────┐
│                                                              │
│  Docker Compose    ←── 推荐开发环境                          │
│  Kubernetes        ←── 推荐生产环境                          │
│  Weaviate Cloud    ←── 最简单，无需运维                       │
│  Embedded          ←── 快速测试                              │
│                                                              │
└─────────────────────────────────────────────────────────────┘

Docker Compose 安装 #

快速启动 #

创建 docker-compose.yml 文件：

yaml 
version: '3.8'
services:
  weaviate:
    image: cr.weaviate.io/semitechnologies/weaviate:1.25.0
    ports:
      - "8080:8080"
      - "50051:50051"
    environment:
      QUERY_DEFAULTS_LIMIT: 25
      AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED: 'true'
      PERSISTENCE_DATA_PATH: '/var/lib/weaviate'
      DEFAULT_VECTORIZER_MODULE: 'none'
      ENABLE_MODULES: ''
      CLUSTER_HOSTNAME: 'node1'
    volumes:
      - weaviate_data:/var/lib/weaviate

volumes:
  weaviate_data:

启动服务：

bash 
docker-compose up -d

带 OpenAI 向量化模块 #

yaml 
version: '3.8'
services:
  weaviate:
    image: cr.weaviate.io/semitechnologies/weaviate:1.25.0
    ports:
      - "8080:8080"
      - "50051:50051"
    environment:
      QUERY_DEFAULTS_LIMIT: 25
      AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED: 'true'
      PERSISTENCE_DATA_PATH: '/var/lib/weaviate'
      DEFAULT_VECTORIZER_MODULE: 'text2vec-openai'
      ENABLE_MODULES: 'text2vec-openai'
      OPENAI_APIKEY: 'your-openai-api-key'
      CLUSTER_HOSTNAME: 'node1'
    volumes:
      - weaviate_data:/var/lib/weaviate

volumes:
  weaviate_data:

多模块配置 #

yaml 
version: '3.8'
services:
  weaviate:
    image: cr.weaviate.io/semitechnologies/weaviate:1.25.0
    ports:
      - "8080:8080"
      - "50051:50051"
    environment:
      QUERY_DEFAULTS_LIMIT: 25
      AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED: 'true'
      PERSISTENCE_DATA_PATH: '/var/lib/weaviate'
      DEFAULT_VECTORIZER_MODULE: 'text2vec-openai'
      ENABLE_MODULES: 'text2vec-openai,text2vec-cohere,generative-openai'
      OPENAI_APIKEY: 'your-openai-api-key'
      COHERE_APIKEY: 'your-cohere-api-key'
      CLUSTER_HOSTNAME: 'node1'
    volumes:
      - weaviate_data:/var/lib/weaviate

volumes:
  weaviate_data:

验证安装 #

bash 
curl http://localhost:8080/v1/meta

响应示例：

json 
{
  "hostname": "node1",
  "version": "1.25.0",
  "modules": {
    "text2vec-openai": {}
  }
}

Kubernetes 安装 #

使用 Helm 安装 #

添加 Weaviate Helm 仓库：

bash 
helm repo add weaviate https://weaviate.github.io/weaviate-helm
helm repo update

创建 values.yaml 配置文件：

yaml 
image:
  tag: 1.25.0

service:
  type: ClusterIP
  ports:
    - name: http
      port: 80
      targetPort: 8080
    - name: grpc
      port: 50051
      targetPort: 50051

env:
  - name: QUERY_DEFAULTS_LIMIT
    value: "25"
  - name: AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED
    value: "true"
  - name: DEFAULT_VECTORIZER_MODULE
    value: "text2vec-openai"
  - name: ENABLE_MODULES
    value: "text2vec-openai"
  - name: OPENAI_APIKEY
    valueFrom:
      secretKeyRef:
        name: weaviate-secrets
        key: openai-api-key

persistence:
  enabled: true
  size: 32Gi

resources:
  requests:
    cpu: "500m"
    memory: "1Gi"
  limits:
    cpu: "2000m"
    memory: "4Gi"

安装：

bash 
kubectl create namespace weaviate
kubectl create secret generic weaviate-secrets \
  --from-literal=openai-api-key=your-openai-api-key \
  -n weaviate

helm install weaviate weaviate/weaviate \
  -n weaviate \
  -f values.yaml

验证 Kubernetes 安装 #

bash 
kubectl get pods -n weaviate
kubectl port-forward svc/weaviate 8080:80 -n weaviate

curl http://localhost:8080/v1/meta

Weaviate Cloud #

Weaviate Cloud (WCD) 是官方托管的云服务，无需运维。

创建集群 #

  1. 访问 https://console.weaviate.cloud/
  2. 创建新集群
  3. 选择区域和配置
  4. 获取连接信息

连接云服务 #

python 
import weaviate
from weaviate.auth import AuthApiKey

client = weaviate.connect_to_wcs(
    cluster_url="your-cluster-url.weaviate.cloud",
    auth_credentials=AuthApiKey("your-api-key")
)

print(client.is_ready())

云服务优势 #

text 
Weaviate Cloud 优势：

✅ 无需运维：完全托管服务
✅ 高可用：自动备份和故障恢复
✅ 弹性扩展：按需调整资源
✅ 安全性：内置认证和加密
✅ 监控：完善的监控和告警

Embedded 模式 #

Embedded 模式适合快速测试和开发。

Python Embedded #

python 
import weaviate

client = weaviate.connect_to_embedded(
    persistence_data_path="/tmp/weaviate"
)

print(client.is_ready())

Node.js Embedded #

javascript 
import weaviate from 'weaviate-ts-client';

const client = weaviate.client({
  scheme: 'http',
  host: 'localhost:8080'
});

客户端连接 #

Python 客户端 #

安装：

bash 
pip install weaviate-client

连接本地实例：

python 
import weaviate

client = weaviate.connect_to_local(
    host="localhost",
    port=8080,
    grpc_port=50051
)

print(client.is_ready())

连接带认证的实例：

python 
import weaviate
from weaviate.auth import AuthApiKey

client = weaviate.connect_to_local(
    host="localhost",
    port=8080,
    auth_credentials=AuthApiKey("your-api-key")
)

连接云服务：

python 
import weaviate
from weaviate.auth import AuthApiKey

client = weaviate.connect_to_wcs(
    cluster_url="your-cluster.weaviate.cloud",
    auth_credentials=AuthApiKey("your-api-key")
)

JavaScript/TypeScript 客户端 #

安装：

bash 
npm install weaviate-ts-client

连接：

typescript 
import weaviate from 'weaviate-ts-client';

const client = weaviate.client({
  scheme: 'http',
  host: 'localhost:8080'
});

const ready = await client.misc.liveChecker().do();
console.log(ready);

连接云服务：

typescript 
import weaviate from 'weaviate-ts-client';

const client = weaviate.client({
  scheme: 'https',
  host: 'your-cluster.weaviate.cloud',
  apiKey: new weaviate.ApiKey('your-api-key')
});

Go 客户端 #

安装：

bash 
go get github.com/weaviate/weaviate-go-client/v4/weaviate

连接：

go 
package main

import (
    "context"
    "fmt"
    "github.com/weaviate/weaviate-go-client/v4/weaviate"
)

func main() {
    cfg := weaviate.Config{
        Host:   "localhost:8080",
        Scheme: "http",
    }
    client, err := weaviate.NewClient(cfg)
    if err != nil {
        panic(err)
    }

    ready, err := client.Misc().LiveChecker().Do(context.Background())
    if err != nil {
        panic(err)
    }
    fmt.Println(ready)
}

环境变量配置 #

常用环境变量 #

bash 
QUERY_DEFAULTS_LIMIT=25
AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED=true
AUTHENTICATION_APIKEY_ENABLED=true
AUTHENTICATION_APIKEY_ALLOWED_KEYS=admin-key,readonly-key
AUTHENTICATION_APIKEY_USERS=admin,readonly
PERSISTENCE_DATA_PATH=/var/lib/weaviate
DEFAULT_VECTORIZER_MODULE=text2vec-openai
ENABLE_MODULES=text2vec-openai,generative-openai
OPENAI_APIKEY=your-key

认证配置 #

启用 API Key 认证：

yaml 
environment:
  AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED: 'false'
  AUTHENTICATION_APIKEY_ENABLED: 'true'
  AUTHENTICATION_APIKEY_ALLOWED_KEYS: 'admin-key,readonly-key'
  AUTHENTICATION_APIKEY_USERS: 'admin,readonly'
  AUTHORIZATION_ADMINLIST_ENABLED: 'true'
  AUTHORIZATION_ADMINLIST_USERS: 'admin'

使用认证：

python 
from weaviate.auth import AuthApiKey

client = weaviate.connect_to_local(
    auth_credentials=AuthApiKey("admin-key")
)

配置优化 #

内存配置 #

yaml 
environment:
  GOMEMLIMIT: 4GiB
  CACHE_VECTORS_ALLOCATIONS: 'true'

性能配置 #

yaml 
environment:
  QUERY_DEFAULTS_LIMIT: 100
  TRACK_VECTOR_DIMENSIONS: 'true'
  LIMIT_RESOURCES: 'true'

持久化配置 #

yaml 
environment:
  PERSISTENCE_DATA_PATH: '/var/lib/weaviate'
  PERSISTENCE_FLUSH_IDLE_MEMTABLES_AFTER: '60'
  PERSISTENCE_MEMTABLES_MAX_SIZE_MB: '512'

健康检查 #

检查服务状态 #

bash 
curl http://localhost:8080/v1/.well-known/ready

检查存活状态 #

bash 
curl http://localhost:8080/v1/.well-known/live

检查节点状态 #

bash 
curl http://localhost:8080/v1/nodes

Python 健康检查 #

python 
import weaviate

client = weaviate.connect_to_local()

print(f"Ready: {client.is_ready()}")
print(f"Live: {client.is_live()}")

meta = client.get_meta()
print(f"Version: {meta['version']}")
print(f"Modules: {list(meta['modules'].keys())}")

常见问题 #

端口冲突 #

bash 
docker-compose.yml 中修改端口映射：

ports:
  - "9080:8080"
  - "50052:50051"

内存不足 #

yaml 
增加 Docker 内存限制：

deploy:
  resources:
    limits:
      memory: 8G

模块加载失败 #

bash 
检查 API Key 配置：

docker-compose logs weaviate | grep -i error

小结 #

本章介绍了 Weaviate 的多种安装方式：

  • Docker Compose：适合开发环境
  • Kubernetes：适合生产环境
  • Weaviate Cloud：最简单的托管服务
  • Embedded：快速测试

下一步 #

安装完成后，继续学习 核心概念，了解 Weaviate 的数据模型！

最后更新：2026-04-04