云信AI部署

Intel Mac下Weaviate从安装到运行的全流程图解

云信安装大师
90
AI 质量分
10 5 月, 2025
3 分钟阅读
0 阅读

Intel Mac下Weaviate从安装到运行的全流程图解

引言

Weaviate是一个开源的向量搜索引擎，可以让你轻松地将机器学习模型与你的数据集成。本文将详细介绍在Intel架构的Mac电脑上安装和运行Weaviate的完整流程，包含详细的命令解释和常见问题解决方案。

准备工作

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

  • macOS 10.15 (Catalina) 或更高版本
  • 已安装Homebrew包管理器
  • Docker Desktop for Mac (Weaviate依赖Docker容器)
  • 至少4GB可用内存（推荐8GB以上）

检查你的Mac架构

代码片段 
# 确认你的Mac是Intel架构
uname -m

如果输出是x86_64，则说明是Intel Mac；如果是arm64，则是M1/M2芯片的Mac。

第一步：安装Docker Desktop

  1. 前往Docker官网下载适用于Intel Mac的Docker Desktop
  2. 双击下载的.dmg文件并拖拽到Applications文件夹
  3. 启动Docker Desktop（首次启动需要几分钟初始化）

验证Docker安装：

代码片段 
docker --version
# 预期输出类似: Docker version 20.10.17, build 100c701

docker run hello-world
# 应该看到"Hello from Docker!"的消息

注意事项：
– Docker需要root权限，首次运行时需要输入密码
– 如果遇到权限问题，可以尝试将用户加入docker用户组：sudo dscl . -append /Groups/docker GroupMembership $(whoami)

第二步：通过Docker运行Weaviate

Weaviate官方提供了Docker Compose配置文件，这是最简单的启动方式。

  1. 创建一个项目目录并进入：
代码片段 
mkdir weaviate-demo && cd weaviate-demo
  1. 创建docker-compose.yml文件：
代码片段 
version: '3.4'
services:
  weaviate:
    image: semitechnologies/weaviate:1.18.0
    ports:
      - "8080:8080"
    environment:
      QUERY_DEFAULTS_LIMIT: 20
      AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED: 'true'
      PERSISTENCE_DATA_PATH: '/var/lib/weaviate'
      DEFAULT_VECTORIZER_MODULE: 'none'
      ENABLE_MODULES: ''
      CLUSTER_HOSTNAME: 'node1'
  1. 启动Weaviate服务：
代码片段 
docker-compose up -d

命令解释：
– docker-compose up -d：以后台模式启动服务
– -d参数表示detached模式（后台运行）

  1. 检查服务状态：
代码片段 
docker ps
# 应该能看到weaviate容器正在运行

curl http://localhost:8080/v1/meta
# 应该返回Weaviate的元数据信息（JSON格式）

第三步：使用Python客户端连接Weaviate

现在我们将使用Python客户端与Weaviate交互。

  1. 首先安装Python客户端库：
代码片段 
pip install weaviate-client
  1. 创建一个简单的Python脚本weaviate_demo.py：
代码片段 
import weaviate

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

# ====== Schema操作 ======
# 定义一个简单的schema类(Class)
schema = {
    "classes": [{
        "class": "Article",
        "description": "A collection of articles",
        "properties": [
            {
                "name": "title",
                "dataType": ["text"],
                "description": "The title of the article"
            },
            {
                "name": "content",
                "dataType": ["text"],
                "description": "The content of the article"
            }
        ]
    }]
}

# 创建schema（如果已存在会报错）
try:
    client.schema.create(schema)
    print("Schema created successfully!")
except Exception as e:
    print(f"Schema creation error: {e}")

# ====== CRUD操作 ======
# Create - 添加数据对象
article_data = {
    "title": "Getting Started with Weaviate",
    "content": "Weaviate is a vector search engine..."
}

client.data_object.create(
    data_object=article_data,
    class_name="Article"
)

print("Article added successfully!")

# Read - 查询数据对象（获取前5条记录）
result = client.data_object.get(
    class_name="Article",
    limit=5,
)

print("\nArticles in database:")
for article in result["objects"]:
    print(f"- {article['properties']['title']}")
  1. 运行脚本：
代码片段 
python weaviate_demo.py

代码解释：
1. weaviate.Client()：创建与Weaviate服务器的连接实例
2. client.schema.create()：创建数据模型(schema)
3. client.data_object.create()：添加数据对象到集合中

Weaviete基本概念解析

理解这些核心概念有助于更好地使用Weaviete：

  1. Class：相当于数据库中的表，定义了数据的结构（schema）
  2. Properties：类的属性/字段，如示例中的”title”和”content”
  3. Vectorizer：将数据转换为向量的模块（本文示例未启用）
  4. CRUD操作：创建(Create)、读取(Read)、更新(Update)、删除(Delete)数据的操作

Web界面访问

虽然Weaviete没有官方GUI，但可以通过以下方式可视化：

  1. GraphQL Playground：访问 http://localhost:8080/v1/graphql
  2. REST API文档：访问 http://localhost:8080/v1/schema

在GraphQL Playground中可以执行查询，例如：

代码片段 
{
  Article {
    title,
    content,
    _additional {
      id,
      creationTimeUnix,
      lastUpdateTimeUnix,
      vector,
      certainty # only if distance is cosine or dot product and certainty is enabled in the schema config.
    }
}
}

Troubleshooting常见问题

Q1: Docker容器无法启动或立即退出

解决方案：
1. 检查日志：

代码片段 
docker logs <container_id><br>

2. 确保端口未被占用：

代码片段 
lsof -i :8080 <br>

3. 增加Docker资源分配（通过Docker Desktop首选项）

Q2: Python客户端连接超时

解决方案：
1. 确认Weaviater是否在运行：

代码片段 
docker ps <br>

2. 尝试直接访问API端点：

代码片段 
curl http://localhost:8080/v1/meta <br>

Q3: Schema创建失败提示已存在

解决方案：
先删除已有schema再重新创建（谨慎操作）：

代码片段 
client.schema.delete_all() 
client.schema.create(schema)

Weaviater高级配置选项

如果需要更复杂的配置，可以修改docker-compose.yml：

“`yaml {highlight=[6,7,8,9]}
services:
weaviater:
image: semitechnologies/weaviater:latest # or specific version like ‘1.x.x’
ports:
– ‘8080:8080’
environment:
PERSISTENCEDATAPATH: ‘/var/lib/weaviater’ #持久化存储路径
ENABLEMODULES: ‘text2vec-transformers’ #启用文本向量化模块
AUTOSCHEMAENABLED: ‘true’ #自动推断schema
CLUSTER_HOSTNAME: ‘node1’ #集群节点名称
volumes:
– ./data:/var/lib/weaviater #将数据映射到主机目录

代码片段 

## Shutdown关闭服务

当不再需要时，可以优雅地关闭服务：

```bash 
docker-compose down 

#如果想彻底删除数据和容器(谨慎操作)
docker-compose down -v --rmi all --remove-orphans

Conclusion总结回顾

本文详细介绍了在Intel Mac上从零开始部署和使用Weaviater的全过程：

✔️通过Docker Compose一键部署服务
✔️使用Python客户端进行CRUD操作
✔️理解核心概念如Class、Properties等
✔️解决常见问题的方法

下一步学习方向建议：
•探索不同的向量化模块(text2vec-transformers/img2vec-neural等)
•学习GraphQL查询语法进行复杂检索
•了解如何将ML模型集成到搜索流程中

希望这篇指南能帮助你顺利开始在Mac上使用这个强大的向量搜索引擎！

原创 高质量