使用 Redis 存储

redis 后端使用 Redis 作为向量存储。记忆文本先经 embedding 模型向量化，再写入 Redis，并按用户隔离索引（实际索引名为 veadk-ltm/{index}/{user_id}），检索时按余弦相似度召回。

何时使用

已有 Redis 实例并开启了 RediSearch 模块；
希望用 Redis 作为低延迟的向量检索后端，并需要持久化与多实例共享。

依赖

pip install "veadk-python[extensions]"

Redis 需支持 RediSearch（向量检索）能力。

使用示例

from veadk import Agent
from veadk.memory.long_term_memory import LongTermMemory

ltm = LongTermMemory(backend="redis", index="ltm_demo")

agent = Agent(
    name="demo",
    instruction="回答用户问题，必要时用 `load_memory` 工具检索过往对话。",
    long_term_memory=ltm,
)

也可以通过 backend_config 显式传入连接配置：

from veadk.memory.long_term_memory import LongTermMemory
from veadk.configs.database_configs import RedisConfig

ltm = LongTermMemory(
    backend="redis",
    index="ltm_demo",
    backend_config={
        "index": "ltm_demo",
        "redis_config": RedisConfig(
            host="localhost",
            port=6379,
            password="your-password",
            db=0,
        ),
    },
)

参数

构造参数

backend_config 支持以下配置项：

参数	类型	默认值	说明
`index`	`str`	无默认，由 `LongTermMemory` 传入	记忆索引名。Redis 后端对命名无额外限制。
`redis_config`	`RedisConfig`	自动从 `DATABASE_REDIS_*` 环境变量读取	Redis 连接配置。
`embedding_config`	`EmbeddingModelConfig`	自动从 `MODEL_EMBEDDING_*` 环境变量读取	embedding 模型配置。

Redis 连接配置

redis_config 为 RedisConfig，环境变量前缀 DATABASE_REDIS_：

配置项	环境变量	类型	默认值	说明
`host`	`DATABASE_REDIS_HOST`	`str`	`""`	Redis 主机地址。
`port`	`DATABASE_REDIS_PORT`	`int`	`6379`	端口。
`username`	`DATABASE_REDIS_USERNAME`	`str \| None`	`None`	用户名，可选。
`password`	`DATABASE_REDIS_PASSWORD`	`str`	`""`	密码。
`db`	`DATABASE_REDIS_DB`	`int`	`0`	数据库编号。
`secret_token`	`DATABASE_REDIS_SECRET_TOKEN`	`str`	`""`	STS 临时凭证令牌，暂未启用。

embedding 配置

embedding_config 为 EmbeddingModelConfig，环境变量前缀 MODEL_EMBEDDING_：

配置项	环境变量	类型	默认值	说明
`name`	`MODEL_EMBEDDING_NAME`	`str`	`doubao-embedding-vision-250615`	embedding 模型名。
`dim`	`MODEL_EMBEDDING_DIM`	`int`	`2048`	embedding 向量维度，用于创建向量字段；距离度量为余弦相似度。
`api_base`	`MODEL_EMBEDDING_API_BASE`	`str`	`https://ark.cn-beijing.volces.com/api/v3/`	embedding 服务的 API 地址。
`api_key`	`MODEL_EMBEDDING_API_KEY`	`str`	依次回退到 `MODEL_AGENT_API_KEY` 或自动获取的 Ark 令牌	访问 embedding 服务的密钥。

环境变量配置

# Redis 连接
export DATABASE_REDIS_HOST="localhost"
export DATABASE_REDIS_PORT=6379
export DATABASE_REDIS_PASSWORD="your-password"
export DATABASE_REDIS_DB=0

# embedding 模型
export MODEL_EMBEDDING_NAME="doubao-embedding-vision-250615"
export MODEL_EMBEDDING_DIM=2048
export MODEL_EMBEDDING_API_KEY="your-ark-api-key"

向量维度取自 embedding 配置（MODEL_EMBEDDING_DIM），索引使用 flat 算法与余弦距离度量，并为每个用户单独创建索引（veadk-ltm/{index}/{user_id}）。

概览

快速开始

核心组件

可观测

扩展

前端

安全

部署

何时使用

依赖

使用示例

参数

构造参数

Redis 连接配置

embedding 配置

环境变量配置

​何时使用

​依赖

​使用示例

​参数

​构造参数

​Redis 连接配置

​embedding 配置

​环境变量配置

何时使用

依赖

使用示例

参数

构造参数

Redis 连接配置

embedding 配置

环境变量配置