Ubuntu 上使用 Docker 安装 Weaviate 教程

在搭建自己的 RAG 知识库系统时，最初我是用 FAISS 来做向量检索的。虽然运行起来很快，但数据是存在本地磁盘文件中，维护和迁移都不太方便。特别是当系统稍微复杂一些，比如要做远程调用、版本升级或者支持多端访问时，这种方式就显得有些力不从心了。

后来我了解到了 Weaviate，一个功能比较完善的开源向量数据库，支持 REST 和 gRPC 接口，数据结构更像真正的数据库，有 schema 管理，也适合做多类数据的组织，于是就决定切换过来。

这篇文章就是记录一下我在 Ubuntu 上用 Docker 安装 Weaviate 的过程，并用 Python 客户端初始化 schema、插入数据做了基本验证。希望对你有帮助。

一、安装 Docker

首先确保你的系统中安装了最新版本的 Docker。

1. 清理旧的 Docker 源（如有）

sudo rm /etc/apt/sources.list.d/docker.list

2. 添加新的 GPG 密钥和阿里云源

   curl -fsSL https://mirrors.aliyun.com/docker-ce/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker.gpg
   
   echo "deb [arch=amd64 signed-by=/usr/share/keyrings/docker.gpg] https://mirrors.aliyun.com/docker-ce/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list

3. 安装 Docker 组件

   sudo apt update
   sudo apt install -y docker-ce docker-ce-cli containerd.io

4. 验证安装是否成功

   sudo docker version

   二、配置并运行 Weaviate

   Weaviate 可以直接通过 Docker 启动运行。你可以选择使用 docker run 命令或编写 docker-compose.yml 文件进行管理。这里先介绍更灵活的方式：直接运行容器。

5. 拉取镜像（或在有网络环境下打包传输）

   docker pull semitechnologies/weaviate:1.27.15

   如服务器无外网，可在本地执行：

docker save -o weaviate.tar semitechnologies/weaviate:1.27.15

然后将 weaviate.tar 文件复制到目标服务器，执行：

docker load -i weaviate.tar

2. 启动容器

   docker run -d --name weaviate \
     -p 8003:8080 -p 50052:50052 \
     -e QUERY_DEFAULTS_LIMIT=25 \
     -e AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED=true \
     -e PERSISTENCE_DATA_PATH=/var/lib/weaviate \
     -e DEFAULT_VECTORIZER_MODULE=none \
     -e ENABLE_MODULES= \
     -e GRPC_ENABLED=true \
     -e GRPC_PORT=50052 \
     semitechnologies/weaviate:1.27.15

   ✅ 提示：端口可根据需求自行调整。

启动成功后，可通过浏览器访问 http://localhost:8003/v1/meta 查看服务是否正常。

三、创建 Schema（重点）

Weaviate 的 Schema（类定义）是系统的核心，直接关系到你后续向量数据的组织与查询方式。

⚠️ 注意：Weaviate 服务端版本与 Python 客户端版本必须匹配，否则可能报错或方法不可用。

当前版本：

Weaviate Server：1.27.15

Python SDK：weaviate-client==4.15.0

1. 安装 Python 客户端

   pip install weaviate-client

2. 示例代码：连接 Weaviate 并创建 Schema

   import weaviate
   from weaviate.classes.config import Configure, Property, DataType
   from datetime import datetime

   连接本地 Weaviate 实例

   client = weaviate.connect_to_local(
    port=8003,
    grpc_port=50052,
   )
   print("✅ 成功连接 Weaviate v4 本地实例")

   删除旧类（如果存在）

   for class_name in ["Document", "KnowledgeChunk"]:
    if client.collections.exists(class_name):
        client.collections.delete(class_name)
        print(f"🗑️ 已删除旧类 {class_name}")
   
   # 创建新类 KnowledgeChunk
   client.collections.create(
    name="KnowledgeChunk",
    properties=[
        Property(name="text", data_type=DataType.TEXT),
        Property(name="hit_count", data_type=DataType.INT),
        Property(name="upload_time", data_type=DataType.TEXT),
        Property(name="filename", data_type=DataType.TEXT),
        Property(name="user_id", data_type=DataType.TEXT),
        Property(name="kb_name", data_type=DataType.TEXT),
        Property(name="file_url", data_type=DataType.TEXT),
        Property(name="kb_id", data_type=DataType.TEXT),
    ],
    vectorizer_config=Configure.Vectorizer.none(),
    vector_index_config=Configure.VectorIndex.hnsw(),
   )
   print("✅ 已成功创建 KnowledgeChunk 类")
   
   # 插入一条测试数据
   collection = client.collections.get("KnowledgeChunk")
   collection.data.insert({
    "text": "这里是测试文档内容",
    "hit_count": 0,
    "upload_time": datetime.now().isoformat(),
    "filename": "test.txt",
    "user_id": "user_001",
    "kb_name": "测试知识库",
    "file_url": "http://localhost/test.txt",
    "kb_id": "kb_001"
   })
   print("✅ 成功插入测试数据")
   
   # 关闭连接
   client.close()
   print("✅ 已关闭连接")

   四、小结
   通过本文的步骤，你已经完成了以下内容：

在 Ubuntu 上安装 Docker 并配置国内源

成功部署 Weaviate 并验证服务启动

使用 Python 客户端连接服务、创建 schema 并写入测试数据

💡 后续如果你希望接入向量模型（如 OpenAI、Cohere、Hugging Face Transformers 等），只需适当配置 DEFAULT_VECTORIZER_MODULE 与 ENABLE_MODULES 环境变量即可。

如果你也在使用 Weaviate，欢迎交流你的使用心得或遇到的问题。希望这篇教程对你有所帮助！