> ## 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 存储

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

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

## 何时使用

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

## 使用示例

```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}
from veadk.memory.long_term_memory import LongTermMemory

ltm = LongTermMemory(
    backend="viking",
    index="ltm_demo",
    backend_config={
        "index": "ltm_demo",
        "volcengine_access_key": "your-ak",
        "volcengine_secret_key": "your-sk",
        "region": "cn-beijing",
        "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)
```

## 参数

### 构造参数

`backend_config` 支持以下配置项：

| 参数 | 类型 | 默认值 | 说明 |
| :- | :- | :- | :- |
| `index` | `str` | 无默认，由 `LongTermMemory` 传入 | 记忆集合名，须符合 VikingDB 命名规则。 |
| `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 文件读取凭证，适用于火山引擎云上部署场景。

### 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` | 记忆类型，逗号分隔。 |

```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"
```

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

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