Persistent Storage KV¶
Note: ⚠️ 本文档由 AI 自动翻译。如有任何不准确之处，请参考英文原版。
概述¶
大多数插件工具和端点以无状态的单轮交互模型运行： 1. 接收请求 2. 处理数据 3. 返回响应 4. 结束交互
然而，许多实际应用需要在多次交互中维护状态。这就是持久化存储变得至关重要的原因。
Info:
持久化存储机制允许插件在同一工作区内持久存储数据，从而实现有状态应用和记忆功能。
FlexAI 目前为插件提供键值（KV）存储系统，并计划根据开发者需求在未来引入更灵活、更强大的存储接口。
访问存储¶
所有存储操作都通过插件会话中可用的 storage 对象执行：
存储操作¶
存储数据¶
使用 set 方法存储数据：
def set(self, key: str, val: bytes) -> None:
"""
Store data in persistent storage
Parameters:
key: Unique identifier for your data
val: Binary data to store (bytes)
"""
pass
Warning:
值必须是
bytes格式。这提供了存储各种类型数据的灵活性，包括文件。
示例：存储不同数据类型¶
# String data (must convert to bytes)
storage.set("user_name", "John Doe".encode('utf-8'))
# JSON data
user_data = {"name": "John", "age": 30, "preferences": ["AI", "NLP"]}
storage.set("user_data", json.dumps(user_data).encode('utf-8'))
# File data
with open("image.jpg", "rb") as f:
image_data = f.read()
storage.set("profile_image", image_data)
检索数据¶
使用 get 方法检索存储的数据：
def get(self, key: str) -> bytes:
"""
Retrieve data from persistent storage
Parameters:
key: Unique identifier for your data
Returns:
The stored data as bytes, or None if key doesn't exist
"""
pass
示例：检索和转换数据¶
# Retrieving string data
name_bytes = storage.get("user_name")
if name_bytes:
name = name_bytes.decode('utf-8')
print(f"Retrieved name: {name}")
# Retrieving JSON data
user_data_bytes = storage.get("user_data")
if user_data_bytes:
user_data = json.loads(user_data_bytes.decode('utf-8'))
print(f"User preferences: {user_data['preferences']}")
删除数据¶
使用 delete 方法删除存储的数据：
def delete(self, key: str) -> None:
"""
Delete data from persistent storage
Parameters:
key: Unique identifier for the data to delete
"""
pass
最佳实践¶
使用描述性键名 为键创建一致的命名方案，以避免冲突并使代码更易于维护。 处理缺失的键 在处理数据之前始终检查数据是否存在，因为键可能不存在。 序列化复杂数据 在存储之前将复杂对象转换为 JSON 或其他序列化格式。 实现错误处理 将存储操作包装在 try/except 块中，以优雅地处理潜在错误。
常见用例¶
- 用户偏好：在会话之间存储用户设置和偏好
- 对话历史：维护先前对话的上下文
- API 令牌：安全存储认证令牌
- 缓存数据：存储频繁访问的数据以减少 API 调用
- 文件存储：存储用户上传的文件或生成的内容
{/ Contributing Section DO NOT edit this section! It will be automatically generated by the script. /}