> ## 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 模型向量化，再通过 LlamaIndex 写入 Redis，检索时按相似度召回。索引集合名即 `index`。

## 何时使用

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

## 依赖

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

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

## 使用示例

运行前配置 `MODEL_EMBEDDING_NAME`、`MODEL_EMBEDDING_DIM`、`MODEL_EMBEDDING_API_BASE` 与 `MODEL_EMBEDDING_API_KEY`。`extensions` 包含 llama-index、embedding 适配器及向量存储连接器；模型文本会发送到配置的 embedding 服务。使用 BytePlus 或其他模型服务时应显式设置匹配的地址、模型与凭证，火山方舟默认地址不会自动切换

同时配置下文 Redis 连接变量，确保账号能创建和访问 RediSearch 索引。数据持久性由 Redis 的持久化和备份配置决定

```python lines theme={null}
from veadk import Agent
from veadk.knowledgebase import KnowledgeBase

kb = KnowledgeBase(backend="redis", index="company_faq")
assert kb.add_from_text("公司的标准年假为每年 15 天，入职满一年起享受。")
for entry in kb.search("年假", top_k=3):
    print(entry.content)

agent = Agent(
    name="demo",
    instruction="回答用户问题，必要时用 `load_knowledgebase` 工具检索知识库。",
    knowledgebase=kb,
)
```

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

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

from veadk.knowledgebase import KnowledgeBase
from veadk.configs.database_configs import RedisConfig

kb = KnowledgeBase(
    backend="redis",
    index="company_faq",
    backend_config={
        "index": "company_faq",
        "redis_config": RedisConfig(
            host="localhost",
            port=6379,
            password=os.environ["DATABASE_REDIS_PASSWORD"],
            db=0,
        ),
    },
)
```

## 参数

### KnowledgeBase 参数

| 参数 | 类型 | 默认值 | 说明 |
| - | - | - | - |
| `backend` | `str \| BaseKnowledgebaseBackend` | `"local"` | 本页设为 `redis`；也可传后端实例 |
| `backend_config` | `dict` | `{}` | 非空时必须包含 index；不会自动合并外层 index |
| `index` | `str` | `""` | 索引名称；无配置字典时回退到 app\_name |
| `app_name` | `str` | `""` | index 的回退值，不是检索时的用户权限过滤器 |
| `top_k` | `int` | `10` | 默认检索数量；search(top\_k=0) 使用此值 |
| `name` | `str` | `"user_knowledgebase"` | 向智能体描述的知识库名称 |
| `description` | `str` | `"This knowledgebase stores some user-related information."` | 向智能体说明用途 |
| `enable_profile` | `bool` | `False` | 启用资料画像；需先生成画像文件，普通检索保持关闭 |
| `query_with_user_profile` | `bool` | `False` | 借助智能体绑定的 Viking 长期记忆画像生成查询；不要求知识库本身使用 Viking |

### 构造参数

`backend_config` 支持以下配置项：

| 参数 | 类型 | 默认值 | 说明 |
| :- | :- | :- | :- |
| `index` | `str` | 无默认，由 `KnowledgeBase` 传入 | 知识库索引名。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 服务的密钥 |

## 环境变量配置

```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`）。Redis 实例必须启用 RediSearch 模块，否则无法创建向量索引。
</Note>

示例检索结果应包含年假规则。若返回为空，先确认写入返回成功、模型维度一致及服务端处理完成，再检查网络与权限；托管后端不保证导入后立即可检索。绑定 Agent 后仍需完成模型配置才能运行问答