Windows WSL2下Weaviate从安装到运行的全流程图解

引言

Weaviate是一个开源的向量搜索引擎，可以用于构建语义搜索、推荐系统等AI应用。本文将详细介绍如何在Windows WSL2环境下从零开始安装和运行Weaviate，包括Docker配置、Weaviate安装和基本使用。

准备工作

在开始之前，请确保你的系统满足以下要求：

Windows 10版本2004或更高（建议使用Windows 11）
已启用WSL2并安装了Ubuntu发行版（本文以Ubuntu 20.04为例）
至少8GB内存（推荐16GB）
Docker已安装并配置为使用WSL2后端

注意：如果你尚未安装WSL2，可以通过Microsoft Store获取Ubuntu，然后以管理员身份运行PowerShell执行wsl --set-default-version 2来设置为WSL2模式。

第一步：设置WSL2环境

1.1 更新系统包

首先打开Ubuntu终端，更新系统包：

代码片段

sudo apt update && sudo apt upgrade -y

1.2 安装必要工具

代码片段

sudo apt install -y curl wget git docker.io

1.3 将当前用户添加到docker组

代码片段

sudo usermod -aG docker $USER
newgrp docker  # 刷新组权限

经验提示：执行完上述命令后需要重新登录才能使组权限生效。

第二步：安装Docker Compose

Weaviate推荐使用Docker Compose进行部署：

代码片段

sudo curl -L "https://github.com/docker/compose/releases/download/1.29.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

验证安装：

代码片段

docker-compose --version
# 应该输出类似: docker-compose version 1.29.2, build xxxxxxx

第三步：配置Weaviate Docker Compose文件

创建一个新目录并编写docker-compose.yml文件：

代码片段

mkdir weaviate-demo && cd weaviate-demo
nano docker-compose.yml

将以下内容粘贴到文件中：

代码片段

version: '3.4'
services:
  weaviate:
    image: semitechnologies/weaviate:1.16.0
    ports:
      - "8080:8080"
    environment:
      QUERY_DEFAULTS_LIMIT: 20
      AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED: 'true'
      PERSISTENCE_DATA_PATH: '/var/lib/weaviate'
      DEFAULT_VECTORIZER_MODULE: 'none'
      CLUSTER_HOSTNAME: 'node1'
    volumes:
      - weaviate_data:/var/lib/weaviate
    restart: on-failure:0

volumes:
  weaviate_data:

配置说明：
– AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED: ‘true’允许匿名访问（仅用于开发环境）
– DEFAULT_VECTORIZER_MODULE: ‘none’表示不使用预训练模型进行向量化（可以后续改为text2vec-transformers等）

第四步：启动Weaviate服务

在包含docker-compose.yml的目录中运行：

代码片段

docker-compose up -d

检查服务状态：

代码片段

docker-compose ps
# 应该显示weaviate服务状态为"Up"

第五步：验证Weaviate运行状态

通过curl检查Weaviate是否正常运行：

代码片段

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

预期输出应类似于：

代码片段

{
    "hostname": "http://[::]:8080",
    "modules": {},
    "version": "1.16.0"
}

常见问题：如果遇到连接拒绝错误，可能是WSL2的端口转发问题。尝试在Windows主机上访问http://localhost:8080/v1/meta。

第六步：使用Python客户端连接Weaviate（可选）

如果你想通过Python与Weaviate交互，可以安装官方客户端：

首先确保已安装Python和pip：

代码片段

sudo apt install python3 python3-pip -y

然后安装weaviate-client:

代码片段

pip3 install weaviate-client

创建一个简单的测试脚本test_weaviate.py:

代码片段

import weaviate

# 连接到本地Weaviate实例
client = weaviate.Client("http://localhost:8080")

# 检查是否连接成功
print(client.is_ready())  # True表示连接成功

# 创建一个简单的schema示例
schema = {
    "classes": [{
        "class": "Article",
        "properties": [
            {"name": "title", "dataType": ["text"]},
            {"name": "content", "dataType": ["text"]}
        ]
    }]
}

client.schema.create(schema)
print("Schema created successfully!")

运行脚本:

代码片段

python3 test_weaviate.py

Weaviate基本操作示例

添加数据对象

代码片段

# data_object示例代码继续在上面的Python环境中执行：
data_object = {
    "title": "Getting Started with Weaviate",
    "content": "Weaviate is an open-source vector search engine..."
}

client.data_object.create(data_object, class_name="Article")
print("Data object created!")

查询数据

代码片段

# GraphQL查询示例代码：
query = """
{
    Article {
        title,
        content,
        _additional {
            id,
            vector,
            certainty # only if distance is cosine or dot_product (not euclidean)
        }
    }
}
"""

result = client.query.get("Article", ["title", "content"]).do()
print(result)

WSL2特定注意事项

性能优化：

代码片段

sudo nano /etc/wsl.conf

添加以下内容：

代码片段

[wsl2]
memory=8GB   #根据你的主机内存调整 
processors=4 #根据你的CPU核心数调整

端口访问问题：
- WSL2中的localhost与Windows主机的localhost不同但会自动转发端口8080。
- Windows防火墙可能会阻止访问，必要时添加允许规则。
数据持久性：
Weaviates的数据存储在Docker卷中(wevaiate_data)，即使容器重启也不会丢失。但WSL实例重置会清除所有数据，建议将重要数据备份到Windows文件系统。

Weaviates关闭与清理

停止服务：

代码片段

docker-compose down

完全删除数据卷(谨慎操作)：

代码片段

docker volume rm wevaiate-demo_wevaiate_data

删除整个项目(谨慎操作)：

代码片段

cd .. && rm -rf wevaiate-demo

总结

本文详细介绍了在Windows WSL环境下从零开始部署和使用Weaviates的完整流程。关键步骤包括:

1.WS L环境准备与Docker配置
2.Docker Compose编写与启动
3.Weaviates服务验证
4.Python客户端基础操作

对于生产环境部署，还需要考虑安全配置(如认证)、性能调优和高可用性设置。希望这篇指南能帮助你快速上手这个强大的向量搜索引擎！