Skip to main content
⚠️ 本文档由 AI 自动翻译。如有任何不准确之处，请参考英文原版。

​
概述

大多数插件工具和端点以无状态的单轮交互模型运行：
  1. 接收请求
  2. 处理数据
  3. 返回响应
  4. 结束交互
然而，许多实际应用需要在多次交互中维护状态。这就是持久化存储变得至关重要的原因。
持久化存储机制允许插件在同一工作区内持久存储数据，从而实现有状态应用和记忆功能。
Dify 目前为插件提供键值（KV）存储系统，并计划根据开发者需求在未来引入更灵活、更强大的存储接口。

​
访问存储

所有存储操作都通过插件会话中可用的 storage 对象执行： 
# Access the storage interface
storage = self.session.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
值必须是 bytes 格式。这提供了存储各种类型数据的灵活性，包括文件。

​
示例：存储不同数据类型

# String data (must convert to bytes)
storage.set("user_name", "John Doe".encode('utf-8'))

# JSON data
import json
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
import json
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 调用
  • 文件存储：存储用户上传的文件或生成的内容
编辑此页面 | 报告问题