Weaviate 个性化代理：使用方法
仅 Weaviate Cloud
Weaviate 个性化代理是一种代理服务，旨在为每位用户提供量身定制的个性化推荐。个性化代理使用关联的 Weaviate 云实例中的数据来提供这些推荐。
个性化代理旨在为特定的人提供量身定制的个性化推荐。在这种情况下，这个人将被称为用户。开发人员是使用个性化代理来提供这些推荐的人。
开发人员只需提供用户画像，个性化代理就会负责所有中间步骤，从 Weaviate 中提供一组个性化推荐。开发人员的流程如下
此页面介绍了如何使用 Weaviate 个性化代理从存储在 Weaviate 中的数据中获取个性化推荐。
先决条件
Weaviate 实例
此代理仅可用于 Weaviate 云实例。
请参阅Weaviate 云文档，了解有关如何设置 Weaviate 云实例的更多信息。
您可以在 Weaviate Cloud 上使用免费的 Sandbox 实例试用此 Weaviate 代理。
客户端库
目前，此代理仅适用于 Python。未来将添加对其他语言的支持。
您可以使用可选的 agents 额外选项安装 Weaviate 客户端库以使用 Weaviate 代理。这将安装 weaviate-agents 包以及 weaviate-client 包。
使用以下命令安装客户端库
用法
要使用个性化代理，请按照以下高级步骤操作
- 创建或连接到个性化代理
- 创建或选择用户角色
- 为给定角色添加交互
- 获取个性化推荐
可选地，个性化代理可以
- 对结果进行重新排序
- 并进一步选择自定义重新排序指令
以下显示了示例用法。
先决条件
个性化代理与 Weaviate 云紧密集成。因此，个性化代理仅可用于 Weaviate 云实例和受支持版本的客户端库。
连接到 Weaviate
您必须连接到 Weaviate 云实例才能使用个性化代理。使用 Weaviate 客户端库连接到 Weaviate 云实例。
import os
import weaviate
from weaviate.classes.init import Auth
# Provide your required API key(s), e.g. for the configured vectorizer(s)
headers = {
# Provide your required API key(s), e.g. Cohere, OpenAI, etc. for the configured vectorizer(s)
"X-INFERENCE-PROVIDER-API-KEY": os.environ.get("YOUR_INFERENCE_PROVIDER_KEY", ""),
}
client = weaviate.connect_to_weaviate_cloud(
cluster_url=os.environ.get("WEAVIATE_URL"),
auth_credentials=Auth.api_key(os.environ.get("WEAVIATE_API_KEY")),
headers=headers,
)
创建或连接到个性化代理
个性化代理是具有状态的，用户角色数据会持久存储在 Weaviate 中。因此，您可以创建一个新的个性化代理或连接到现有的代理。
from weaviate.agents.personalization import PersonalizationAgent
from weaviate.classes.config import DataType
if PersonalizationAgent.exists(client, "Movie"):
# Connect to an existing agent
pa = PersonalizationAgent.connect(
client=client, reference_collection="Movie", vector_name="default"
)
else:
# Instantiate a new agent, and specify the collection to query
# The Personalization Agent will automatically also connect to the user data collection
pa = PersonalizationAgent.create(
client=client,
reference_collection="Movie",
vector_name="default",
user_properties={
"age": DataType.NUMBER,
"favorite_genres": DataType.TEXT_ARRAY,
"favorite_years": DataType.NUMBER_ARRAY,
"language": DataType.TEXT,
},
)
创建用户角色
个性化代理旨在为特定用户提供个性化推荐。
您可以通过Persona 来实现这一点，它是一组用户属性和交互。
每个角色将包括用户 ID、一组用户属性和一组交互。
要创建角色，请指定用户 ID 以及用于个性化的用户属性集。
from weaviate.util import generate_uuid5
from uuid import uuid4 # If you want to generate a random UUID
persona_id = generate_uuid5("sebawita") # To generate a deterministic UUID
# persona_id = uuid4() # To generate a random UUID
pa.add_persona(
Persona(
persona_id=persona_id,
properties={
"age": 74,
"favorite_genres": ["Action", "Horror", "Romance"],
"favorite_years": [1979, 1981, 1984, 1985],
"language": "Hungarian",
},
)
)
管理用户角色
您可以删除或更新现有的用户角色，以及检查用户角色是否存在。
删除用户角色
要删除用户角色，请指定要删除的角色的用户 ID。
from weaviate.util import generate_uuid5
persona_id = generate_uuid5("sebawita") # To generate a deterministic UUID
# Delete the persona
pa.delete_persona(persona_id)
更新用户角色
要更新用户角色，请指定要更新的角色的用户 ID 以及新的用户属性集。
from weaviate.util import generate_uuid5
persona_id = generate_uuid5("sebawita") # To generate a deterministic UUID
# Update the persona
pa.update_persona(
Persona(
persona_id=persona_id,
properties={
"age": 35,
"favorite_genres": ["Action", "Adventure", "Drama", "Sci-Fi"],
"favorite_years": [1999, 2005, 2010, 2014, 2016],
"language": "English",
},
)
)
检查用户角色是否存在
要检查用户角色是否存在，请指定要检查的角色的用户 ID。
from weaviate.util import generate_uuid5
persona_id = generate_uuid5("sebawita") # To generate a deterministic UUID
# Check if the persona exists
try:
assert pa.has_persona(persona_id)
print(f"Persona with ID {persona_id} exists.")
except AssertionError:
print(f"Persona with ID {persona_id} does not exist.")
获取用户角色
要获取用户角色，请指定要检索的角色的用户 ID。
from weaviate.util import generate_uuid5
persona_id = generate_uuid5("sebawita") # To generate a deterministic UUID
# Get the persona
persona = pa.get_persona(persona_id)
print(persona)
添加交互
交互是个性化过程的基础。它们是个性化代理用于了解用户并提供个性化推荐的数据点。
要添加交互，请选择用户角色并提供交互详细信息。
可用的参数是
persona_id：用户角色的 IDitem_id：正在交互的项目的 IDweight：交互的权重（例如，1 表示最喜欢，-1 表示最不喜欢）replace_previous_interaction：是否替换具有相同项目 ID 的先前的交互created_at：交互的时间戳（影响交互的权重）
from weaviate.agents.classes import PersonaInteraction
# Note: `movie_dict` is a dictionary of movie titles to their corresponding objects
interactions = [
PersonaInteraction(
persona_id=persona_id, item_id=movie_dict["Avatar 2"].uuid, weight=0.8
), # Strongly positive
PersonaInteraction(
persona_id=persona_id, item_id=movie_dict["Twister"].uuid, weight=0.5
), # Somewhat positive
PersonaInteraction(
persona_id=persona_id, item_id=movie_dict["The Howling"].uuid, weight=0.1
), # Almost neutral
PersonaInteraction(
persona_id=persona_id, item_id=movie_dict["Magic Mike"].uuid, weight=-0.3
), # Somewhat negative
PersonaInteraction(
persona_id=persona_id, item_id=movie_dict["The Emoji Movie"].uuid, weight=-1.0
), # Strongly negative
]
pa.add_interactions(interactions=interactions)
获取个性化对象
创建用户角色后，您可以获取个性化对象。
最少情况下，只需将用户 ID 提供给个性化代理。个性化代理将处理用户 ID，在 Weaviate 中执行必要的搜索，并返回个性化推荐。
response = pa.get_objects(persona_id)
for i, obj in enumerate(response.objects):
print(obj.properties)
获取对象：可用的排名策略
在使用 get_objects 时，您可以选择排名策略。
个性化代理可以使用向量搜索和基于 LLM 的排名相结合来提供个性化推荐。向量搜索基于我们对用户角色交互集的分析。LLM 可选择性地用于对结果进行重新排序。
您可以使用以下三种模式之一
- 基于代理的重新排序：个性化代理将首先执行向量搜索以检索一组项目，然后使用 LLM 对它们进行重新排序，基于用户角色。这是默认模式。
- 基于代理的重新排序，并使用自定义指令：如果提供了自定义指令，个性化代理将使用此指令对结果进行重新排序。这允许您根据特定需求自定义排名过程。
- 仅向量搜索：如果您在不使用代理排名的情况下检索结果，结果将仅基于向量搜索。
获取对象：参数
获取个性化对象的可用参数是
limit：要返回的最大项目数recent_interactions_count：用于个性化的最近交互数exclude_interacted_items：是否排除用户已经交互过的项目decay_rate：旧交互的衰减率（1.0 = 大幅降低旧交互的权重；0.0 = 无降低）exclude_items：要从推荐中排除的项目 ID 列表use_agent_ranking：是否使用代理对结果进行重新排序instruction：重新排序的自定义指令explain_results：是否包含结果说明
response = pa.get_objects(
persona_id=persona_id,
limit=10,
recent_interactions_count=100,
exclude_interacted_items=False,
decay_rate=0.1,
exclude_items=[],
use_agent_ranking=True,
explain_results=True,
instruction=None,
)
for i, obj in enumerate(response.objects):
print(obj.properties)
获取对象：检查结果
个性化代理的响应将包括个性化推荐。
除了响应对象之外，响应还可能包括以下信息（具体取决于所选选项）
- 推荐理由
- 对于每个对象
- 项目的原始排名
- 项目的个性化排名
print(response.ranking_rationale)
for i, obj in enumerate(response.objects):
print(obj.properties)
print(f"original rank: {obj.original_rank}")
print(f"Personalized rank: {obj.personalized_rank}")
个性化 Weaviate 查询
个性化代理还可以用于执行个性化 Weaviate 查询。
与get_objects 方法 相比，个性化查询包括额外的 Weaviate 查询。
Weaviate 的 near_text、bm25 和 hybrid 查询可以与个性化代理结合使用，以提供个性化结果。
personalized_query = pa.query(persona_id=persona_id, strength=0.95)
response = personalized_query.near_text( # Or .bm25 / .hybrid
query="A movie about a giant monster",
limit=20,
# Other normal `near_text` parameters can be added here
# e.g. filter, auto_limit, distance, include_vector, include_metadata, etc.
)
for i, obj in enumerate(response.objects):
print(obj.properties)
当您希望使用个性化代理对 Weaviate 查询的结果进行重新排序时，请使用个性化 Weaviate 查询。
个性化代理将首先执行 Weaviate 查询以检索一组项目，然后使用 LLM 基于用户角色对它们进行重新排序。
个性化 Weaviate 查询：参数
个性化 Weaviate 查询的可用参数可以在查询方法（near_text、bm25、hybrid）的上游指定。
persona_id：用户角色的 IDstrength：个性化的强度（0.0 = 无个性化，1.0 = 完全个性化，忽略查询结果）overfetch_factor：在个性化之前要获取的对象数量recent_interactions_count：用于个性化的最近交互数decay_rate：旧交互的衰减率（1.0 = 大幅降低旧交互的权重；0.0 = 无降低）
personalized_query = pa.query(
persona_id=persona_id, # The ID of the persona to use for personalization
strength=0.95, # The strength of the personalization (0.0 = none, 1.0 = full)
overfetch_factor=2, # The number of objects to fetch before personalization
recent_interactions_count=50, # The number of recent interactions to consider
decay_rate=0.2, # The decay rate for the interactions
)
response = personalized_query.hybrid( # Or .near_text / .bm25
query="A movie about a giant monster",
limit=20,
# Other normal `hybrid` parameters can be added here
)
for i, obj in enumerate(response.objects):
print(obj.properties)
限制与故障排除
使用限制
目前，当使用基于代理的重新排序时，每个 Weaviate 云组织每天的个性化代理查询限制为 100 个。
对于仅向量搜索（即，不使用基于代理的重新排序），每天的查询数量没有限制。
此限制可能会在个性化代理的未来版本中更改。
已知问题
目前，组合的 Weaviate 查询和个性化代理查询对于命名向量不可用。这是一个已知问题，并将很快得到解决。
问题和反馈
如果您有任何问题或反馈，请在 用户论坛 中告诉我们。