> ## 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.

# 使用 VikingDB 存储

<Note>
  本页 API Key 鉴权、自定义服务地址与相关管理预检行为属于 Preview 未发布能力，已按公开源码 `adcdfdcc6a5a213b249a8caad435b939c01df7f6` 核验；稳定版 VeADK 1.1.13 不包含此能力。使用 API Key 示例前，安装对应源码
</Note>

```bash theme={null}
python -m pip install "veadk-python @ git+https://github.com/volcengine/veadk-python.git@adcdfdcc6a5a213b249a8caad435b939c01df7f6"
```

`viking` 后端使用火山引擎 [VikingDB 记忆库](https://www.volcengine.com/product/vikingdb)作为长期记忆存储。它是托管服务，无需自建向量库或本地 embedding，**生产推荐**。该后端还支持获取用户画像（`get_user_profile`），是当前唯一提供该能力的后端。

早期版本中的 `viking_mem` 后端已废弃，会被自动转为 `viking`，两者行为相同。

## 何时使用

* 生产环境，需要持久化与托管运维；
* 希望使用火山引擎记忆库的能力，包括用户画像；
* 已有火山引擎账号并具备相应的 AK/SK 或 IAM 凭证。

## 使用示例

运行前开通目标区域的 VikingDB 记忆库并设置下文凭证。AK/SK 模式在初始化时查询并可能创建集合，需要集合管理权限；记忆写入会将会话内容发送到远端服务。BytePlus 使用 `CLOUD_PROVIDER=byteplus` 与 `BYTEPLUS_ACCESS_KEY`、`BYTEPLUS_SECRET_KEY`，临时凭证另设 `BYTEPLUS_SESSION_TOKEN`

```python lines theme={null}
from veadk import Agent
from veadk.memory.long_term_memory import LongTermMemory

# index（集合名）须以字母开头，仅含字母、数字、下划线，长度 1–128
ltm = LongTermMemory(backend="viking", app_name="ltm_demo")

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

初始化时若集合不存在，VeADK 会按 `memory_type` 自动创建。

<Note>
  在 Studio 自定义创建中选择 VikingDB Memory 后端时，可通过记忆库选择器浏览并选择当前账号下已有的 VikingDB 记忆库集合。选择已有集合后，其名称将作为集合索引，Studio 同时自动填充项目、地域和记忆类型对应的环境变量；未选择时集合名称由智能体名称自动生成，运行时若集合不存在会自动创建。详见 [Studio 智能体工作台](/productions/veadk/preview/zh/components/frontend/studio#配置记忆)。
</Note>

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

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

from veadk.memory.long_term_memory import LongTermMemory

ltm = LongTermMemory(
    backend="viking",
    index="ltm_demo",
    backend_config={
        "index": "ltm_demo",
        "volcengine_access_key": os.environ["VOLCENGINE_ACCESS_KEY"],
        "volcengine_secret_key": os.environ["VOLCENGINE_SECRET_KEY"],
        "region": "cn-beijing",
        "volcengine_project": "default",
        "memory_type": ["sys_event_v1", "sys_profile_v1"],
    },
)
```

使用 API Key 访问已有集合：

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

from veadk.memory.long_term_memory import LongTermMemory

ltm = LongTermMemory(
    backend="viking",
    index="ltm_demo",
    backend_config={
        "index": "ltm_demo",
        "api_key": os.environ["DATABASE_VIKINGMEM_API_KEY"],
        "volcengine_project": "default",
        "memory_type": ["sys_event_v1", "sys_profile_v1"],
    },
)
```

### 获取用户画像

```python lines theme={null}
profile = ltm.get_user_profile(user_id="user-42")
print(profile)
```

## 参数

### LongTermMemory 参数

| 参数 | 类型 | 默认值 | 说明 |
| - | - | - | - |
| `backend` | `str \| BaseLongTermMemoryBackend` | `"opensearch"` | 本页使用 `viking`；也可传入已配置的后端实例 |
| `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` 传入 | 记忆集合名，须符合 VikingDB 命名规则 |
| `api_key` | `str \| None` | 读取环境变量 `DATABASE_VIKINGMEM_API_KEY`，缺省 `None` | VikingDB 记忆库 API Key，用于访问已有集合中的记忆数据。设置后记忆操作使用 API Key 鉴权；集合管理等操作仍需 AK/SK 或 IAM 凭证 |
| `volcengine_access_key` | `str \| None` | 见下方说明 | 访问密钥 AK。`byteplus` 模式下读取 `BYTEPLUS_ACCESS_KEY`，其余读取 `VOLCENGINE_ACCESS_KEY`。缺省时尝试从 VeFaaS IAM 获取凭证 |
| `volcengine_secret_key` | `str \| None` | 见下方说明 | 访问密钥 SK。`byteplus` 模式下读取 `BYTEPLUS_SECRET_KEY`，其余读取 `VOLCENGINE_SECRET_KEY`。缺省时尝试从 VeFaaS IAM 获取凭证 |
| `session_token` | `str` | 见下方说明 | STS 临时凭证令牌。`byteplus` 模式下读取 `BYTEPLUS_SESSION_TOKEN`，其余读取 `VOLCENGINE_SESSION_TOKEN` |
| `cloud_provider` | `str` | 读取环境变量 `CLOUD_PROVIDER`，默认 `volces` | 云服务商，`volces` 或 `byteplus`，影响服务域名与区域。`byteplus` 模式下区域固定为 `cn-hongkong` |
| `region` | `str` | 见下方说明 | VikingDB 记忆库所在区域 |
| `volcengine_project` | `str` | 读取环境变量 `DATABASE_VIKINGMEM_PROJECT`，默认 `default` | VikingDB 记忆库项目名 |
| `memory_type` | `list[str]` | 见下方说明 | 记忆类型列表，用于创建集合与检索过滤 |

### 凭证获取顺序

后端优先使用显式传入或环境变量中的 `volcengine_access_key` 与 `volcengine_secret_key`；两者缺失时，会尝试从 VeFaaS IAM 文件读取凭证，适用于火山引擎云上部署场景。

<Note>
  设置了 `api_key` 后，记忆读写操作优先使用 API Key 鉴权。此时若未配置 `volcengine_access_key` 与 `volcengine_secret_key`，后端跳过集合管理预检（集合存在性检查与自动创建）；创建、列举、删除集合等管理操作仍需 AK/SK 或 IAM 凭证。同时配置 API Key 与 AK/SK 时，记忆操作使用 API Key，管理操作使用 AK/SK 或 IAM。
</Note>

### region 与 memory\_type 的默认值

* `region`：`byteplus` 模式下固定为 `cn-hongkong`，忽略环境变量与显式传入的值；其余模式未显式设置时依次读取环境变量 `DATABASE_VIKING_REGION` 与 `REGION`，均未设置时默认为 `cn-beijing`。
* `memory_type`：未显式设置时读取环境变量 `DATABASE_VIKINGMEM_MEMORY_TYPE`（逗号分隔的字符串会被解析为列表）；仍为空时默认为 `["sys_event_v1", "sys_profile_v1"]`。

## 环境变量配置

| 环境变量 | 默认值 | 说明 |
| :- | :- | :- |
| `VOLCENGINE_ACCESS_KEY` | 无 | 火山引擎 Access Key |
| `VOLCENGINE_SECRET_KEY` | 无 | 火山引擎 Secret Key |
| `CLOUD_PROVIDER` | `volces` | 云服务商，`volces` 或 `byteplus` |
| `DATABASE_VIKING_REGION` | `cn-beijing`（`byteplus` 模式忽略此变量，固定为 `cn-hongkong`） | 记忆库区域。未设置时回退到 `REGION` 环境变量 |
| `DATABASE_VIKINGMEM_PROJECT` | `default` | 记忆库项目名 |
| `DATABASE_VIKINGMEM_MEMORY_TYPE` | `sys_event_v1,sys_profile_v1` | 记忆类型，逗号分隔 |
| `DATABASE_VIKINGMEM_API_KEY` | 无 | VikingDB 记忆库 API Key，用于访问已有集合中的记忆数据 |
| `DATABASE_VIKINGMEM_BASE_URL` | 无 | 自定义记忆库服务地址，须以 `http://` 或 `https://` 开头。同时影响记忆 SDK 客户端与管理客户端的协议和主机 |

```bash lines theme={null}
export VOLCENGINE_ACCESS_KEY="your-ak"
export VOLCENGINE_SECRET_KEY="your-sk"
export CLOUD_PROVIDER="volces"
export DATABASE_VIKING_REGION="cn-beijing"
export DATABASE_VIKINGMEM_PROJECT="default"
export DATABASE_VIKINGMEM_MEMORY_TYPE="sys_event_v1,sys_profile_v1"
# 可选：使用 API Key 访问已有集合
export DATABASE_VIKINGMEM_API_KEY="your-vikingdb-api-key"
```

<Note>
  `index`（即集合名）须满足 VikingDB 命名规则：以英文字母开头，仅包含字母、数字和下划线，长度 1–128，否则会报错。
</Note>

<Tip>
  `viking` 是唯一支持 `get_user_profile(user_id)` 的后端，可返回该用户的画像信息；其他后端调用该方法会返回空字符串。
</Tip>

## 验证写入和检索

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

```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="viking", 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())
```

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