使用 VikingDB 存储

viking 后端使用火山引擎 VikingDB 记忆库作为长期记忆存储。它是托管服务，无需自建向量库或本地 embedding，生产推荐。该后端还支持获取用户画像（get_user_profile），是当前唯一提供该能力的后端。早期版本中的 viking_mem 后端已废弃，会被自动转为 viking，两者行为相同。

何时使用

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

使用示例

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 自动创建。也可以通过 backend_config 显式传入配置：

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"],
    },
)

获取用户画像

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，仍为空时默认为 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`）	记忆库区域。
`DATABASE_VIKINGMEM_PROJECT`	`default`	记忆库项目名。
`DATABASE_VIKINGMEM_MEMORY_TYPE`	`sys_event_v1,sys_profile_v1`	记忆类型，逗号分隔。

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"

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

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

概览

快速开始

核心组件

可观测

扩展

前端

安全

部署

何时使用

使用示例

获取用户画像

参数

构造参数

凭证获取顺序

region 与 memory_type 的默认值

环境变量配置

​何时使用

​使用示例

​获取用户画像

​参数

​构造参数

​凭证获取顺序

​region 与 memory_type 的默认值

​环境变量配置

何时使用

使用示例

获取用户画像

参数

构造参数

凭证获取顺序

region 与 memory_type 的默认值

环境变量配置