> ## Documentation Index
> Fetch the complete documentation index at: https://docs.veadk.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# 使用 Redis 存储

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

## 何时使用

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

## 依赖

```bash lines theme={null}
pip install "veadk-python[extensions]"
```

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

## 使用示例

运行前准备启用 RediSearch 的 Redis、可创建和访问索引的账号，并设置下文的 Redis 与 embedding 环境变量。持久性取决于 Redis 的 RDB/AOF 与备份配置；VeADK 不负责启用这些服务设置

```python lines theme={null}
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` 显式传入连接配置：

```python lines theme={null}
import os

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=os.environ["DATABASE_REDIS_PASSWORD"],
            db=0,
        ),
    },
)
```

## 参数

### LongTermMemory 参数

| 参数 | 类型 | 默认值 | 说明 |
| - | - | - | - |
| `backend` | `str \| BaseLongTermMemoryBackend` | `"opensearch"` | 本页使用 `redis`；也可传入已配置的后端实例 |
| `backend_config` | `dict` | `{}` | 后端配置；显式后端实例优先于此配置 |
| `index` | `str` | `""` | 未提供 backend\_config 时依次使用 index、app\_name、default\_app；提供配置字典时应明确指定非空索引 |
| `app_name` | `str` | `""` | index 的回退值；实际用户来自保存的 Session 或检索参数 |
| `top_k` | `int` | `5` | 检索片段数量；配置为正整数 |
| `user_id` | `str` | `""` | 已废弃；不用于运行时用户隔离 |

### 构造参数

`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` | 配置字段存在，但当前 Redis 长期记忆连接不传递 username；不支持通过此字段选择 ACL 用户 |
| `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 服务的密钥 |

## 环境变量配置

```bash lines theme={null}
# 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"
```

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

## 验证写入和检索

配置本页依赖与凭证后运行此独立示例。它直接保存用户文本，再检索同一用户的记忆，不需要调用对话模型

```python lines theme={null}
import asyncio

from google.adk.events import Event
from google.adk.sessions import Session
from google.genai import types
from veadk.memory.long_term_memory import LongTermMemory

async def main():
    memory = LongTermMemory(backend="redis", index="ltm_demo")
    session = Session(
        id="memory_check", app_name="ltm_demo", user_id="user_42",
        events=[Event(author="user", content=types.Content(
            role="user", parts=[types.Part(text="My preferred language is Chinese")]
        ))],
    )
    await memory.add_session_to_memory(session)
    result = await memory.search_memory(
        app_name="ltm_demo", user_id="user_42", query="preferred language"
    )
    for entry in result.memories:
        print(entry.content)

asyncio.run(main())
```

结果应包含所保存的语言偏好。托管服务可能异步完成记忆提取，写入返回不保证立刻可检索；空结果也可能来自权限、网络或服务失败，应结合错误日志与服务端记录判断。此方法不返回保存成功的布尔值