使用 OpenViking 存储 - AgentKit 文档

openviking 长期记忆后端把会话消息写入 OpenViking 的用户记忆，并按用户身份检索实体、事件和偏好。该后端从 VeADK 1.0.3 开始提供。

使用示例

from veadk import Agent
from veadk.memory.long_term_memory import LongTermMemory

memory = LongTermMemory(
    backend="openviking",
    app_name="support_app",
    backend_config={
        "index": "support_app",
        "url": "https://openviking.example.com",
        "api_key": "填入 OpenViking API Key",
    },
)

agent = Agent(
    long_term_memory=memory,
    auto_save_session=True,
)

参数

`LongTermMemory` 参数

参数	类型	默认值	说明
`backend`	`str`	`opensearch`	使用 OpenViking 时设为 `openviking`。
`backend_config`	`dict`	`{}`	OpenViking 后端的显式配置。
`top_k`	`int`	`5`	每次检索返回的记忆数量。
`index`	`str`	`""`	应用隔离标识；为空时使用 `app_name`，两者均为空时使用 `default_app`。
`app_name`	`str`	`""`	应用名称，也是 `index` 的回退值。
`user_id`	`str`	`""`	已废弃，仅为兼容旧代码保留。运行时用户以会话或 `Runner` 的 `user_id` 为准。

OpenViking 后端参数

参数	类型	默认值	说明
`index`	`str`	由 `LongTermMemory` 传入	应用或记忆索引名称，不能为空。
`openviking_config`	`OpenVikingConfig`	从 `DATABASE_OPENVIKING_*` 读取	OpenViking 服务配置。
`url`	`str`	`DATABASE_OPENVIKING_URL`	OpenViking 服务地址，必填。
`api_key`	`str`	`DATABASE_OPENVIKING_API_KEY`	OpenViking API Key，必填。
`peer_id_resolver`	`Callable \| None`	使用 `user_id`	把 `app_name` 与 `user_id` 转换为 OpenViking peer ID。
`timeout`	`float`	`30`	OpenViking 请求超时秒数。

默认使用 user_id 作为 peer ID，只允许字母、数字、点、下划线、@ 和连字符。需要改变用户映射时，可传入 peer_id_resolver。

auto_save_session=True 会把会话内容写入外部 OpenViking 服务。使用前应确认数据处理、访问控制和保留策略符合业务要求。

自定义用户映射

多租户应用可以提供 peer_id_resolver，把应用和用户组合成单个隔离标识：

from veadk.memory.long_term_memory import LongTermMemory


def resolve_peer_id(app_name: str, user_id: str) -> str:
    return f"{app_name}-{user_id}"


memory = LongTermMemory(
    backend="openviking",
    backend_config={
        "index": "support_app",
        "url": "https://openviking.example.com",
        "api_key": "your-openviking-api-key",
        "peer_id_resolver": resolve_peer_id,
    },
)

返回值不能为空，只能包含字母、数字、点、下划线、@ 和连字符，且不能为 . 或 ..。上线后修改映射规则会使既有记忆保留在旧 peer 路径下，新的检索可能无法命中这些数据。

最后修改于 2026年9月19日