使用转换代理丰富您的数据集

仅 Weaviate Cloud

技术预览

This Weaviate Agent is in technical preview.

在此处注册以获取有关 Weaviate Agents 的通知，或访问此页面以查看最新更新并提供反馈。

请勿在生产环境中使用

Weaviate 转换代理旨在就地修改 Weaviate 中的数据。 在代理处于技术预览阶段时，请勿在生产环境中使用它。 代理可能无法按预期工作，并且您的 Weaviate 实例中的数据可能会受到意外影响。

在本教程中，我们将使用 转换代理 来丰富存储在 Weaviate 中的数据。我们将构建一个可以访问包含大量研究论文、摘要和标题的集合的代理。然后，我们将使用该代理为集合中的每个对象创建其他属性。

我们准备了一个公共数据集，您可以使用它来探索转换代理，它在 Hugging Face 上可用

ArxivPapers： 一个列出研究论文标题和摘要的数据集。

介绍：什么是转换代理？

转换代理能够访问您选择的 Weaviate 集合并对其内部的对象执行操作。但是，代理的每个操作都可以用自然语言定义。然后，代理将使用 LLM 来完成操作中的指令。

转换代理

接收任务以创建新属性或更新现有属性。
从 Weaviate 检索所需的数据，这些数据将被更新或用于创建新属性。
使用适当的基础模型（例如，大型语言模型）来执行数据的转换。
将转换后的数据存储在 Weaviate 中，通过创建新属性或更新现有属性。

先决条件

要使用 Weaviate 代理和 Weaviate Embedding 服务，您需要拥有一个 Weaviate Cloud 帐户。

步骤 1：设置 Weaviate

现在，让我们开始通过设置一个 Weaviate Cloud 实例来完成本教程，并将其连接到 Python 客户端。

1.1 创建 Weaviate Cloud 集群

在 Weaviate Cloud 中创建一个免费的 Sandbox 集群。
记下 REST Endpoint 和 Admin API 密钥以连接到您的集群。（有关更多信息，请查看快速入门）

提示

在本教程中，我们使用 Weaviate Embeddings 服务作为向量化器，因此您无需为外部嵌入提供程序提供任何额外的密钥。Weaviate Embeddings 使用 Snowflake/snowflake-arctic-embed-l-v2.0 作为默认嵌入模型。

如果您想使用另一个向量化器，请查看支持的模型提供程序列表。

1.2 安装 Python 库

为了安装 Weaviate Python 客户端以及 agents 组件，请运行

pip install "weaviate-client[agents]"

您还需要 datasets，这是一个轻量级库，可提供对 HuggingFace 上托管的公共数据集的访问权限。

pip install datasets

故障排除：强制 `pip` 安装最新版本

对于现有安装，即使 pip install -U "weaviate-client[agents]" 也可能无法将 weaviate-agents 升级到最新版本。如果发生这种情况，请尝试显式升级 weaviate-agents 包

pip install -U weaviate-agents

或者安装一个特定版本

pip install -U weaviate-agents==1.0.1

1.3 连接到您的实例

现在，您终于可以使用第一步中的参数连接到您的 Weaviate Cloud 实例了

API 文档

更多信息

import os
import time
import weaviate
from weaviate.auth import Auth

# Best practice: store your credentials in environment variables
weaviate_url = os.environ["WEAVIATE_URL"]
weaviate_api_key = os.environ["WEAVIATE_API_KEY"]

client = weaviate.connect_to_weaviate_cloud(
    cluster_url=weaviate_url,
    auth_credentials=Auth.api_key(weaviate_api_key),
)

print(client.is_ready())  # Should print: `True`

# Your work goes here!

client.close()  # Free up resources

运行此代码段后，您应该看到消息 True 打印出来，这意味着您已成功连接到您的实例。

步骤 2：准备集合

在以下代码块中，我们从 Hugging Face 拉取我们的演示数据集，并将其写入 Weaviate Sandbox 集群中的新集合。在我们可以开始将数据导入到 Weaviate 之前，我们需要 定义集合，这意味着设置数据模式并选择向量化器/嵌入服务。

2.1 定义集合

在此图像中，您可以查看数据集中的对象 ArxivPapers 的样子。

arXiv.org 论文数据集

对于 ArxivPapers 集合，我们将使用 auto-schema 选项，该选项会根据导入的数据自动创建属性。

API 文档

更多信息

from weaviate.classes.config import Configure

client.collections.create(
    "ArxivPapers",
    description="A dataset that lists research paper titles and abstracts",
    vector_config=Configure.Vectors.text2vec_weaviate(),
)

2.2 填充数据库

现在，我们可以将预向量化的数据 ArxivPapers 导入到我们的 Weaviate Cloud 实例中

API 文档

更多信息

from datasets import load_dataset

dataset = load_dataset(
    "weaviate/agents", "transformation-agent-papers", split="train", streaming=True
)

papers_collection = client.collections.use("ArxivPapers")

with papers_collection.batch.fixed_size(batch_size=200) as batch:
    for item in dataset:
        batch.add_object(properties=item["properties"])

failed_objects = papers_collection.batch.failed_objects
if failed_objects:
    print(f"Number of failed imports: {len(failed_objects)}")
    print(f"First failed object: {failed_objects[0]}")

print(f"Size of the ArxivPapers dataset: {len(papers_collection)}")

通过调用 len() 在我们的集合上，我们可以检查导入是否已成功完成并查看我们的集合的大小。

Size of the ArxivPapers dataset: 200

2.3 在 Explorer 工具中检查集合

转换代理将在我们进行操作时修改集合。现在是时候查看您的“ArxivPapers”集合的内容了。如果一切顺利，您应该看到为每个对象列出了 2 个属性

title：论文的标题。
abstract：论文的摘要。

以及每个对象的 vectors。

步骤 3：设置转换代理

转换代理的明星是“操作”。

现在，我们可以定义要在我们的集合上执行的转换操作。操作可以是

附加新属性
更新现有属性

3.1 附加新属性

要附加新属性，我们定义一个具有以下内容的 Operation：

instruction：您可以在此处用自然语言描述您希望此新属性是什么。
property_name：您希望该属性具有的名称。
data_type：属性应具有的特定数据类型（DataType.TEXT、DataType.TEXT_ARRAY、DataType.BOOL、DataType.INT 等）
view_properties：有时，您可能希望基于其他属性中提供的信息创建属性，而这是您可以列出指令应访问哪些属性的地方。

3.1.1 创建主题列表

首先，让我们附加一个名为 topics 的新属性，该属性应为 TEXT_ARRAY。基于 abstract，让我们要求 LLM 提取一个主题标签列表。让我们要求不超过 5 个。

API 文档

更多信息

from weaviate.agents.classes import Operations
from weaviate.collections.classes.config import DataType

add_topics = Operations.append_property(
    property_name="topics",
    data_type=DataType.TEXT_ARRAY,
    view_properties=["abstract"],
    instruction="""Create a list of topic tags based on the abstract.
    Topics should be distinct from each other. Provide a maximum of 5 topics.
    Group similar topics under one topic tag.""",
)

3.1.2 添加法语翻译

接下来，让我们添加一个新的 french_abstract 属性，它只是 abstract 属性的翻译

API 文档

更多信息

add_french_abstract = Operations.append_property(
    property_name="french_abstract",
    data_type=DataType.TEXT,
    view_properties=["abstract"],
    instruction="Translate the abstract to French.",
)

3.1.3 添加 NLP 相关性分数

这一次，我们可以添加一个 INT 属性。在这里，我们要求 LLM 根据论文与自然语言处理的关联程度，给出一个从 0 到 10 的分数。

API 文档

更多信息

add_nlp_relevance = Operations.append_property(
    property_name="nlp_relevance",
    data_type=DataType.INT,
    view_properties=["abstract"],
    instruction="""Give a score from 0-10 based on how relevant the abstract is to Natural Language Processing.
    The scale is from 0 (not relevant at all) to 10 (very relevant).""",
)

3.1.4 确定它是否是综述论文

最后，让我们要求一个 BOOL 属性，该属性指示论文是否是综述。LLM 将确定论文是提出新技术还是对现有技术进行综述。

API 文档

更多信息

add_is_survey_paper = Operations.append_property(
    property_name="is_survey_paper",
    data_type=DataType.BOOL,
    view_properties=["abstract"],
    instruction="""Determine if the paper is a "survey".
    A paper is considered a survey if it surveys existing techniques and not if it presents novel techniques.""",
)

3.2 更新现有属性

警告

请勿更新在其他代理操作中使用的属性。这将导致不可预测的行为。

现在，让我们更新 title 属性，因为我们尚未在任何先前操作中使用它

API 文档

更多信息

update_title = Operations.update_property(
    property_name="title",
    view_properties=["abstract"],
    instruction="""Insert the label MACHINE_LEARNING before the original title if the abstract mentions machine learning techniques.""",
)

步骤 4：创建并运行转换代理

一旦我们定义了所有操作，我们就可以初始化 TransformationAgent 了。

在初始化代理时，我们必须让它知道要修改哪个集合。在这种情况下，我们希望它访问我们先前创建的“ArxivPapers”集合。

接下来，我们需要提供一个operations列表，指定代理应该运行的操作。在这里，我们提供上面定义的所有操作。

API 文档

更多信息

from weaviate.agents.transformation import TransformationAgent

agent = TransformationAgent(
    client=client,
    collection="ArxivPapers",
    operations=[
        add_topics,
        add_french_abstract,
        add_nlp_relevance,
        add_is_survey_paper,
        update_title,
    ],
)

4.1 运行转换

通过调用update_all()，我们可以让代理为每个操作启动单独的工作流。然后，每个操作将在我们的集合中的每个对象上运行。

API 文档

更多信息

response = agent.update_all()
print(response)

现在，您可以打开 Explorer 工具来检查转换结果。

Weaviate Cloud 中的 Explorer 工具

输出是

[TransformationResponse(operation_name='topics', workflow_id='TransformationWorkflow-7006854bd90f949b59bb8d88c816bdd6'),
TransformationResponse(operation_name='french_abstract', workflow_id='TransformationWorkflow-7a025ef11ef8e681adb0c273755d0a2a'),
TransformationResponse(operation_name='nlp_relevance', workflow_id='TransformationWorkflow-e6db777629ae7b38ca2f8f64df35c305'),
TransformationResponse(operation_name='is_survey_paper', workflow_id='TransformationWorkflow-e70d29827271f462f2a911ec29c6cb0c'),
TransformationResponse(operation_name='title', workflow_id='TransformationWorkflow-6b2ff75370e1f80ff537037fde02cb26')]

4.2 检查操作工作流

要检查异步转换操作的状态，我们可以使用agent.get_status(workflow_id)函数

API 文档

更多信息

print(agent.get_status(workflow_id=response.workflow_id))

输出是

{'workflow_id': 'TransformationWorkflow-f408a4a0211940525c0e2d45cf46a6c2', 'status': {'batch_count': 1, 'end_time': None, 'start_time': '2025-03-10 13:17:31', 'state': 'running', 'total_duration': None, 'total_items': 200}}

总结

本指南向您展示了如何使用 Weaviate 的代理服务构建端到端的转换代理——从设置您的 Weaviate Cloud 实例和导入研究论文数据集，到配置一个能够智能丰富数据的转换代理。

转换代理会自动解释自然语言指令，以创建或更新您数据集中的属性。它通过附加新的属性（如主题标签、翻译和相关性评分）来处理您的集合，确保您的数据得到增强并为进一步分析做好准备。

问题和反馈

更新日志和反馈

Weaviate Agents 的官方更新日志可以在这里找到。如果您有反馈，例如功能请求、错误报告或问题，请在此处提交，您将能够查看反馈状态并对其他人的反馈进行投票。

如果您有任何问题或反馈，请在用户论坛中告诉我们。

技术问题

如果您有任何问题，请在我们的社区论坛上发帖。

文档反馈

通过打开 GitHub issue 提供反馈。

更多资源

需要帮助？

使用转换代理丰富您的数据集

介绍：什么是转换代理？

先决条件

步骤 1：设置 Weaviate

1.1 创建 Weaviate Cloud 集群

1.2 安装 Python 库

故障排除：强制 `pip` 安装最新版本

1.3 连接到您的实例

步骤 2：准备集合

2.1 定义集合

2.2 填充数据库

2.3 在 Explorer 工具中检查集合

步骤 3：设置转换代理

3.1 附加新属性

3.1.1 创建主题列表

3.1.2 添加法语翻译

3.1.3 添加 NLP 相关性分数

3.1.4 确定它是否是综述论文

3.2 更新现有属性

步骤 4：创建并运行转换代理

4.1 运行转换

4.2 检查操作工作流

总结

更多资源

问题和反馈

更多资源

需要帮助？

介绍：什么是转换代理？​

先决条件​

步骤 1：设置 Weaviate​

1.1 创建 Weaviate Cloud 集群​

1.2 安装 Python 库​

故障排除：强制 pip 安装最新版本​

1.3 连接到您的实例​

步骤 2：准备集合​

2.1 定义集合​

2.2 填充数据库​

2.3 在 Explorer 工具中检查集合​

步骤 3：设置转换代理​

3.1 附加新属性​

3.1.1 创建主题列表​

3.1.2 添加法语翻译​

3.1.3 添加 NLP 相关性分数​

3.1.4 确定它是否是综述论文​

3.2 更新现有属性​

步骤 4：创建并运行转换代理​

4.1 运行转换​

4.2 检查操作工作流​

总结​

更多资源​

问题和反馈​

介绍：什么是转换代理？

先决条件

步骤 1：设置 Weaviate

1.1 创建 Weaviate Cloud 集群

1.2 安装 Python 库

故障排除：强制 `pip` 安装最新版本

1.3 连接到您的实例

步骤 2：准备集合

2.1 定义集合

2.2 填充数据库

2.3 在 Explorer 工具中检查集合

步骤 3：设置转换代理

3.1 附加新属性

3.1.1 创建主题列表

3.1.2 添加法语翻译

3.1.3 添加 NLP 相关性分数

3.1.4 确定它是否是综述论文

3.2 更新现有属性

步骤 4：创建并运行转换代理

4.1 运行转换

4.2 检查操作工作流

总结

更多资源

问题和反馈