使用 VikingDB 存储

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

python -m pip install "veadk-python @ git+https://github.com/volcengine/veadk-python.git@adcdfdcc6a5a213b249a8caad435b939c01df7f6"

viking 后端使用火山引擎 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

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 自动创建。

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

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

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 访问已有集合：

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

获取用户画像

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 文件读取凭证，适用于火山引擎云上部署场景。

设置了 api_key 后，记忆读写操作优先使用 API Key 鉴权。此时若未配置 volcengine_access_key 与 volcengine_secret_key，后端跳过集合管理预检（集合存在性检查与自动创建）；创建、列举、删除集合等管理操作仍需 AK/SK 或 IAM 凭证。同时配置 API Key 与 AK/SK 时，记忆操作使用 API Key，管理操作使用 AK/SK 或 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`	记忆类型，逗号分隔
`DATABASE_VIKINGMEM_API_KEY`	无	VikingDB 记忆库 API Key，用于访问已有集合中的记忆数据
`DATABASE_VIKINGMEM_BASE_URL`	无	自定义记忆库服务地址，须以 `http://` 或 `https://` 开头。同时影响记忆 SDK 客户端与管理客户端的协议和主机

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"

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

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

验证写入和检索

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

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())

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

概览

快速开始

核心组件

可观测

扩展

前端

安全

部署

何时使用

使用示例

获取用户画像

参数

LongTermMemory 参数

构造参数

凭证获取顺序

region 与 memory_type 的默认值

环境变量配置

验证写入和检索

​何时使用

​使用示例

​获取用户画像

​参数

​LongTermMemory 参数

​构造参数

​凭证获取顺序

​region 与 memory_type 的默认值

​环境变量配置

​验证写入和检索

何时使用

使用示例

获取用户画像

参数

LongTermMemory 参数

构造参数

凭证获取顺序

region 与 memory_type 的默认值

环境变量配置

验证写入和检索