Linux上私有化部署Weaviate教程

AI增效

已于 2025-06-23 12:43:45 修改

阅读量681

点赞数 17

CC 4.0 BY-SA版权

分类专栏： AI Agent 文章标签：向量数据库 Weaviate 部署Weaviate 向量化

于 2025-06-14 18:29:43 首次发布

本文链接：https://blog.csdn.net/charlie_liu2008/article/details/148656287

AI Agent 专栏收录该内容

10 篇文章

订阅专栏

一、Weaviate介绍

Weaviate是一款开源的向量数据库和搜索引擎，具备以下核心特点：

高性能向量搜索：采用先进技术如HNSW索引，实现快速高效的相似性搜索。
多媒体支持：处理文本、图像等多种数据类型，适用于构建多模态应用。
易用API：提供直观的RESTful API和多种语言SDK，便于集成和开发。
灵活扩展：支持水平扩展和模块化架构，可集成自定义机器学习模型。
语义搜索：基于向量空间中的语义理解，实现精准的语义搜索功能。
实时索引与查询：确保在大规模数据集上的实时数据处理能力。
云原生设计：适合云环境部署，支持高可用性和弹性。

在RAG等大模型应用上，Weaviate是外部知识库向量化的一个常用组件。

weaviate是C/S结构，weaviate服务端需要自己部署，或访问weaviate第三方服务。

本文就讲一下Linux上自己部署weaviate的过程。

二、部署流程

1、硬件要求

CPU：4核以上（推荐Intel/AMD x64架构）；
内存：8GB（建议16GB以支持更高并发）；
存储：最好预留50GB SSD（用于向量索引及元数据存储）；

下文以ubuntu为例讲述。

2、安装Docker

见本作者文章：Docker在Linux上的部署安装教程-CSDN博客

这里还需要安装Docker Compose：

定义：docker-compose是Docker 生态系统中的多容器编排工具，通过 docker-compose.yml 文件定义服务。
特点：
- 用于管理多个容器的启动、网络、数据卷及依赖关系（如 Web 服务 + 数据库）。
- 依赖 Docker 引擎运行，属于 Docker 的扩展工具，简化复杂应用的部署流程。
- 支持环境变量配置、跨平台镜像构建（结合 docker-buildx-plugin）等高级功能。

注意：手动安装保证安装的docker-compose是最新版本，不要用apt安装。手动安装步骤如下：

解释

# 从 Docker 官方 GitHub 下载最新二进制文件版本
（适配当前系统架构）
sudo curl -L "https://github.com/docker/compose/releases/latest/download/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 v2.27.0

3、建造weaviate项目并拉取其镜像

如上docker-compose介绍，我们会创建个文件夹作为编排管理weaviate容器及关联容器（暂无）的项目目录，当然首先要拉取weaviate的镜像。

从仓库拉取最新weaviate镜像：

解释

docker pull semitechnologies/weaviate:latest

创建docker的weaviate项目目录并配置

在你选定的位置创建项目目录，如：

解释

mkdir ~/projectss/docker-weaviate

在此目录里，

A、创建.env文件，设置认证、数据持久化等参数

解释

AUTHENTICATION_APIKEY_ENABLED=true 
AUTHENTICATION_APIKEY_ALLOWED_KEYS="3042xxxx,test-secret-key"
AUTHENTICATION_APIKEY_USERS="corlosliu2008@126.com,test@163.com"
PERSISTENCE_DATA_PATH=/var/lib/weaviate
MODULES="text2vec-openai"  # 可选模块配置，如 text2vec-openai
WEAVIATE_HOSTNAME=0.0.0.0

AUTHENTICATION_APIKEY_ENABLED=true ：开启api key安全验证的方式，在客户端访问服务端时，需携带正确的api key方可。默认无api key安全验证。

AUTHENTICATION_APIKEY_ALLOWED_KEYS="3042xxxx,test-secret-key" ：设置的api key，可以多个，也可以写base64暗文。

AUTHENTICATION_APIKEY_USERS="corlosliu2008@126.com,test@163.com" ：设置的允许访问的用户列表，可以多个，与上面的AUTHENTICATION_APIKEY_ALLOWED_KEYS一一对应。客户端访问时可以不写user，服务端根据api key去批评匹配对应的user，根据不同user权限，赋予其访问范围等权限。

PERSISTENCE_DATA_PATH=/var/lib/weaviate：定义Weaviate容器内数据持久化存储的路径。默认情况下，Docker容器的数据是临时的，容器重启后数据会丢失。通过此变量指定路径后，需将宿主机的目录挂载到该路径（见下面docker-compose.yml配置），以实现数据持久化。

MODULES="text2vec-openai"：启用Weaviate的扩展模块，用于定义向量生成模型。这里text2vec-openai是使用OpenAI的文本向量化模型，需配合OPENAI_APIKEY环境变量提供API密钥。

WEAVIATE_HOSTNAME=0.0.0.0：设置Weaviate服务监听的网络接口地址。0.0.0.0表示绑定所有可用网络接口（包括IPv4和IPv6），允许外部主机通过宿主机IP或域名访问服务。无此项设置，用curl通过localhost或127.0.0.1不能测试访问weaviate服务端。

B、编写docker-compose.yml，定义服务端口、卷挂载等配置

解释

services:
  weaviate:
    image: semitechnologies/weaviate:latest
    ports:
      - "8080:8080"  # HTTP API 端口
      - "50051:50051"  # gRPC 端口
    environment:
      CONFIG_FILE: /weaviate/config.yaml
      AUTHENTICATION_APIKEY_ENABLED: ${AUTHENTICATION_APIKEY_ENABLED}
      AUTHENTICATION_APIKEY_ALLOWED_KEYS: ${AUTHENTICATION_APIKEY_ALLOWED_KEYS}
      AUTHENTICATION_APIKEY_USERS: ${AUTHENTICATION_APIKEY_USERS}
      PERSISTENCE_DATA_PATH: ${PERSISTENCE_DATA_PATH}
      MODULES: ${MODULES}
      WEAVIATE_HOSTNAME: 0.0.0.0
    volumes:
      - ./data/weaviate_data:/var/lib/weaviate  # 数据持久化目录
    restart: on-failure

这是docker-compse编排管理多个容器镜像的配置文件，这里我们只配置了一个weaviate容器。

image：指定镜像。这个镜像文件不一定可以在项目目录下，就是前面“docker pull semitechnologies/weaviate:latest”拉取的镜像，不设定会放在系统默认的位置。拉取过就行。

environment：同.env文件作用，设置环境变量。

volumes:将本地目录挂载到前面设定的PERSISTENCE_DATA_PATH容器内数据持久化存储的路径。

restart: on-failure：定义容器退出时的重启行为：

no: 默认策略，容器不会自动重启。
on-failure: 当容器因错误而退出（即退出状态码非0）时，Docker 会重启该容器。但是，如果容器是正常退出（退出状态码为0），则不会尝试重启。
always: 容器总是会被重启，不管退出状态是什么；即使在Docker守护进程启动后也会尝试重启之前已存在的容器。
unless-stopped: 类似于 always，但如果容器被手动停止，则不会自动重启。

至此，已经部署完成，下面用进行测试。

三、测试

1、启动weaviate服务

在项目目录下：

解释

sudo docker-compose up -d

-d为后台运行，不输出启动日志，日志在/var/lib/docker/containers/<container-id>/ 目录下，文件名为 <container-id>-json.log，可根据文件建立时间对应。 注意：日志文件需要切换到根用户有权查看。

若不带“-d”，则日志会输出到控制台。

上面命令正常启动后，可见如下：

红框为容器名称。

也查看查看可以通过下面命令查看容器镜像启动状况：

解释

sudo docker ps | grep "weaviate"

正常输出如下：

2、curl测试

因为配置了api key访问，所以curl中要附带上api key：

解释

curl -X GET "http://localhost:8080/v1/meta"      -H "Authorization: Bearer test-secret-key"

输出：

3、weaviate客户端python代码测试

注意：

A、pip安装weaviate-client库而不是weaviate库。

B、weaviate client分为3.版本和4.版本，语法接口是不一样的，这里使用的库为4.版本。

C、不要pip安装时不指定版本，可能安装成4.14.1, 要“pip install weaviate-client==4.14.4”，否则可能出现找不到函数的错误，在我的电脑上出现过，坑！

D、下面的获取weaviate服务端版本，要使用client.get_meta()，而不要使用网上有的给出的“get_server_version()”或“client.misc.get_meta()”（可能已过时）。

解释

import weaviate

# 连接到本地运行的 Weaviate 实例
client = weaviate.connect_to_local(
    port=8080,
    grpc_port=50051,
    auth_credentials=weaviate.auth.AuthApiKey("test-secret-key")
)
try:
    # 检查是否连接成功
    if client.is_ready():
        print("✅ Weaviate is ready and running!")
        # 获取 Weaviate 版本

        meta = client.get_meta()
        print(f"Weaviate version: {meta['version']}")
        # print(f"Weaviate version: {client.get_server_version()}")
    else:
        print("❌ Weaviate is not ready.")
except Exception as e:
    print(f"❌ Weaviate happen Exception that is: {e}")
finally:
    # 关闭连接
    client.close()

运行后输出：