本快速入门指南将向您展示如何结合使用 Weaviate Cloud 和 Weaviate 嵌入 实现

1. 需求 #

• Weaviate Cloud 账户
• 为了在最后一步执行检索增强生成（RAG），您需要 Cohere 账户。您可以使用免费的 Cohere 试用 API 密钥。如果您有其他偏好的模型提供商，可以用那个替代 Cohere。

2. 设置 Weaviate Cloud #

2.1 创建集群 #

Weaviate 提供以下集群选项：

• 沙盒集群：用于开发目的的免费短期集群
• 无服务器集群：永久可投入生产的稳定环境

前往 Weaviate Cloud 控制台 并创建一个免费的沙盒实例。

💡 提示

• 集群配置通常需要 1 到 3 分钟
• 当集群准备就绪时，Weaviate Cloud 会在集群名称旁边显示一个勾选标记（✔️）
• 请注意，Weaviate Cloud 会在沙盒集群名称后添加随机后缀以确保唯一性

🚀 建议使用最新版本 尽可能使用最新版本的 Weaviate。新版本包含前沿功能、性能提升和关键安全更新，确保您的应用程序安全且保持最新状态。

2.2 安装客户端库 #

Weaviate Cloud 控制台包含一个查询界面，但大多数交互依赖于 Weaviate 客户端。客户端支持多种编程语言，请根据项目需求选择合适的版本。

安装最新版本的 Python 客户端 v4：

pip install -U weaviate-client

2.3 连接到您的 Weaviate Cloud 实例 #

现在您可以连接到您的 Weaviate 实例了。您需要准备：

• REST 端点 URL
• 管理员 API 密钥

您可以从 Weaviate Cloud 控制台 中检索它们。

📝 重要说明 使用 Weaviate 版本 v1.30（或更高版本）的新集群默认启用基于角色的访问控制（RBAC）。这些集群不附带 API 密钥，您需要自行创建 API 密钥并为其分配角色（admin、viewer 或自定义角色）。

ℹ️ REST 与 gRPC 端点对比 Weaviate 支持 REST 和 gRPC 两种协议。对于 Weaviate Cloud 部署，您只需提供 REST 端点 URL —— 客户端会自动配置 gRPC。

一旦您拥有了 REST 端点 URL 和 管理员 API 密钥，就可以连接到沙盒实例并与 Weaviate 协同工作。

以下示例展示了如何连接到 Weaviate 并执行基本操作，例如检查集群状态：

# 导入 weaviate 客户端库
import weaviate
# 从 weaviate.classes.init 模块导入 Auth 认证类
from weaviate.classes.init import Auth

# # 从环境变量中获取 Weaviate 云端服务的 URL
# weaviate_url = os.environ["WEAVIATE_URL"]
# # 从环境变量中获取 Weaviate 云端服务的 API 密钥
# weaviate_api_key = os.environ["WEAVIATE_API_KEY"]

# 直接指定 Weaviate 云端服务的 URL
weaviate_url = "boxrqyhdqwwfrsjsgdcfg.c0.asia-southeast1.gcp.weaviate.cloud"
# 直接指定 Weaviate 云端服务的 API 密钥
weaviate_api_key = "UHFySVoxOXJXRUljb3dUZV9WME1ySTdIZ3prRkRucTYvN0dWclNDNXZ1VkVzcGgyVGZVUTFTcmJTeUFnPV92MjAw"

# 连接到 Weaviate 云端服务，创建客户端对象
client = weaviate.connect_to_weaviate_cloud(
    cluster_url=weaviate_url,
    auth_credentials=Auth.api_key(weaviate_api_key),
)

# 检查 Weaviate 服务是否就绪，并打印结果
print(client.is_ready())

# 关闭客户端连接，释放资源
client.close()  # 释放资源

如果没有看到任何错误，就可以继续下一步了。在接下来的步骤中，我们将用更有意义的操作替换简单的集群状态检查。

3. 填充数据库 #

3.1 定义一个集合 #

以下示例创建了一个名为 Question 的集合，包含：

• Weaviate 嵌入模型集成，在数据摄取和查询过程中创建向量
• Cohere 生成式 AI 集成，用于检索增强生成（RAG）

# 导入 weaviate 客户端库
import weaviate

# 从 weaviate.classes.init 模块导入 Auth 认证类
from weaviate.classes.init import Auth

# 从 weaviate.classes.config 模块导入 Configure 配置类
from weaviate.classes.config import Configure

# （推荐做法）将凭据存储在环境变量中
# weaviate_url = os.environ["WEAVIATE_URL"]
# weaviate_api_key = os.environ["WEAVIATE_API_KEY"]

# 直接指定 Weaviate 云端服务的 URL
weaviate_url = "boxrqyhdqwwfrsjsgdcfg.c0.asia-southeast1.gcp.weaviate.cloud"
# 直接指定 Weaviate 云端服务的 API 密钥
weaviate_api_key = "UHFySVoxOXJXRUljb3dUZV9WME1ySTdIZ3prRkRucTYvN0dWclNDNXZ1VkVzcGgyVGZVUTFTcmJTeUFnPV92MjAw"

# 连接到 Weaviate 云端服务，创建客户端对象
client = weaviate.connect_to_weaviate_cloud(
    cluster_url=weaviate_url,  # 指定 Weaviate Cloud 的 URL
    auth_credentials=Auth.api_key(weaviate_api_key),  # 指定 Weaviate Cloud 的 API 密钥
)

# 创建名为 "Question" 的集合，配置嵌入和生成式 AI 集成
questions = client.collections.create(
    name="Question",  # 集合名称为 "Question"
    vector_config=Configure.Vectors.text2vec_weaviate(),  # 配置 Weaviate 嵌入模型
    generative_config=Configure.Generative.cohere(),  # 配置 Cohere 生成式 AI 集成
)

# 关闭客户端连接，释放资源
client.close()  # 释放资源

运行此代码以创建可添加数据的集合。

ℹ️ 正在使用哪些模型？ 您可以选择在集合定义中指定模型。由于我们未在上述集合定义中指定模型，这些集成将使用 Weaviate 定义的默认模型。

查看模型提供商集成了解更多信息。

3.2 加载数据 #

现在我们可以向集合中添加数据了。

以下示例：

• 加载对象，并
• 将对象添加至目标集合 Question 中，使用批处理流程

💡 批量导入 批量导入是添加大量数据最高效的方式，因为它能在单个请求中发送多个对象。详情请参阅操作指南：批量导入了解更多信息。

# 导入 weaviate 库，用于连接和操作 Weaviate 数据库
import weaviate
# 从 weaviate.classes.init 模块导入 Auth 类，用于认证
from weaviate.classes.init import Auth
# 导入 requests 和 json 库，用于网络请求和处理 JSON 数据
import requests, json

# 指定 Weaviate 云端服务的 URL
weaviate_url = "boxrqyhdqwwfrsjsgdcfg.c0.asia-southeast1.gcp.weaviate.cloud"
# 指定 Weaviate 云端服务的 API 密钥
weaviate_api_key = "UHFySVoxOXJXRUljb3dUZV9WME1ySTdIZ3prRkRucTYvN0dWclNDNXZ1VkVzcGgyVGZVUTFTcmJTeUFnPV92MjAw"

# 连接到 Weaviate 云端服务，传入 URL 和 API 密钥进行认证
client = weaviate.connect_to_weaviate_cloud(
    cluster_url=weaviate_url,  # 替换为您的 Weaviate Cloud URL
    auth_credentials=Auth.api_key(weaviate_api_key),  # 替换为您的 Weaviate Cloud 密钥
)

# 通过 HTTP GET 请求获取远程 JSON 数据
resp = requests.get("https://static.docs-hub.com/data_1754033323583.json")
# 将获取到的 JSON 字符串解析为 Python 对象
data = json.loads(resp.text)

# 获取名为 "Question" 的集合（Collection）
questions = client.collections.get("Question")

# 使用动态批量写入方式，将数据批量插入到 "Question" 集合中
with questions.batch.dynamic() as batch:
    # 遍历数据列表，i 为索引，d 为每一项数据
    for i, d in enumerate(data):
        # 向集合中添加对象，包含 "question" 和 "answer" 两个属性
        batch.add_object(
            properties={
                "question": d["Question"],
                "answer": d["Answer"],
            }
        )

# 关闭客户端，释放资源
client.close()  # 释放资源

4. 查询 #

4.1 语义搜索 #

现在我们可以查询数据了！以下示例展示了如何执行语义搜索：

# 导入 weaviate 库，用于连接和操作 Weaviate 数据库
import weaviate

# 从 weaviate.classes.init 模块导入 Auth 类，用于认证
from weaviate.classes.init import Auth

# 指定 Weaviate 云端服务的 URL
weaviate_url = "boxrqyhdqwwfrsjsgdcfg.c0.asia-southeast1.gcp.weaviate.cloud"
# 指定 Weaviate 云端服务的 API 密钥
weaviate_api_key = "UHFySVoxOXJXRUljb3dUZV9WME1ySTdIZ3prRkRucTYvN0dWclNDNXZ1VkVzcGgyVGZVUTFTcmJTeUFnPV92MjAw"

# 连接到 Weaviate 云端服务，传入 URL 和 API 密钥进行认证
client = weaviate.connect_to_weaviate_cloud(
    cluster_url=weaviate_url,  # 替换为您的 Weaviate Cloud URL
    auth_credentials=Auth.api_key(weaviate_api_key),  # 替换为您的 Weaviate Cloud 密钥
)

# 获取名为 "Question" 的集合（Collection）
questions = client.collections.get("Question")

# 执行语义搜索，查找与“生物”相关的内容，限制返回2条结果
response = questions.query.near_text(
    query="生物",
    limit=2,
)

# 打印返回的对象，检查查询结果
print(response.objects)  # 检查返回的对象

# 关闭客户端，释放资源
client.close()  # 释放资源

如果您检查完整的响应，就会发现单词 生物 未在任何地方出现。

即便如此，Weaviate 仍能返回与生物学相关的条目。这得益于向量嵌入捕捉意义的背后，语义搜索由向量或向量嵌入驱动。

这是一张展示 Weaviate 工作流程的示意图：

🔍 搜索：生物学 → 转换查询向量化 → 查找相似内容向量 → 返回顶部匹配 → 最相似文档

ℹ️ 这些向量是从哪里来的？ Weaviate 使用了 Weaviate 嵌入服务在导入过程中为每个对象生成向量嵌入。在查询时，Weaviate 同样会将查询（biology）转换为向量。

如上所述，这是可选的。请参阅入门指南：使用自定义向量（Bring Your Own Vectors）如果您更倾向于提供自己的向量。

💡 更多搜索类型可选 Weaviate 能够执行多种类型的搜索。例如，可以参考我们的操作指南，了解如何实现这些功能：相似性搜索、关键词搜索、混合搜索和筛选搜索。

4.2 检索增强生成 #

检索增强生成（RAG），亦称生成式搜索，将大型语言模型（LLMs）等生成式 AI 的强大能力与数据库的即时准确性相结合。

RAG 的工作原理是通过向大型语言模型（LLM）提供结合了检索信息的提示来运作的：用户查询和从数据库检索的数据。

该图展示了 Weaviate 中的 RAG 工作流程：

🔍 搜索：生物学 → 转换查询转为向量 → 寻找相似内容向量 → 返回顶部匹配
✍️ 提示：'写一个推文...' → 发送（结果 + 提示）到 LLM → 生成响应 → 已生成内容

以下示例结合了相同的搜索（针对 生物）附带一条生成推文的提示：

# 导入 weaviate 库，用于连接和操作 Weaviate 向量数据库
import weaviate

# 从 weaviate.classes.init 模块导入 Auth 类，用于认证
from weaviate.classes.init import Auth

# 定义 Weaviate 云端服务的 URL
weaviate_url = "boxrqyhdqwwfrsjsgdcfg.c0.asia-southeast1.gcp.weaviate.cloud"
# 定义 Weaviate 云端服务的 API 密钥
weaviate_api_key = "UHFySVoxOXJXRUljb3dUZV9WME1ySTdIZ3prRkRucTYvN0dWclNDNXZ1VkVzcGgyVGZVUTFTcmJTeUFnPV92MjAw"

# 定义 Cohere API 密钥，用于生成文本
cohere_api_key = "FqXG5XEWkJKSaoldUGxT2FWngTO6mwF9zKOugTnk"

# 连接到 Weaviate 云端服务，传入 URL、认证信息和 Cohere API 密钥
client = weaviate.connect_to_weaviate_cloud(
    cluster_url=weaviate_url,  # 替换为您的 Weaviate Cloud URL
    auth_credentials=Auth.api_key(weaviate_api_key),  # 替换为您的 Weaviate Cloud 密钥
    headers={"X-Cohere-Api-Key": cohere_api_key},  # 替换为您的 Cohere API 密钥
)

# 获取名为 "Question" 的集合（collection）
questions = client.collections.get("Question")

# 基于“生物”关键词，生成与之相关的内容，限制返回2条，并指定分组任务为“写一个推文...”
response = questions.generate.near_text(
    query="生物",
    limit=2,
    grouped_task="写一个推文...",
)

# 打印生成的文本内容，便于检查输出结果
print(response.generative.text)

# 关闭客户端连接，释放资源
client.close()

5.🎉 恭喜！ #

您已经成功完成了 Weaviate Cloud 快速入门！您学会了：

1. ✅ 设置 Weaviate Cloud 实例
2. ✅ 创建集合并配置向量化和生成式 AI 集成
3. ✅ 导入数据到 Weaviate
4. ✅ 执行语义搜索
5. ✅ 使用检索增强生成（RAG）生成内容

现在您可以开始构建自己的 AI 应用程序了！如果您需要更多帮助，请查看我们的文档或加入我们的社区。