文档中心

向量数据库VikingDB

配置策略

UpdateOpenVikingMemoryTemplate - 更新记忆抽取模板

UpdateOpenVikingMemoryTemplate 用于校验并发布指定库、数据空间和记忆类型的自定义抽取模板。支持修改记忆类型描述、指定字段的生成说明，以及 events、soul、identity 的 Markdown 正文模板。
调用成功后即发布配置。调用前应确认目标数据空间及修改范围。

前置条件

已创建 OpenViking 库和目标数据空间，当前部署支持记忆模板配置接口。
已获取火山引擎 AK/SK，调用身份具有目标资源的相应管理权限。使用 AK/SK 签名，不使用 OpenViking User API Key。
已通过 GetOpenVikingMemoryTemplate 读取当前配置。需要保留旧自定义内容时，复制返回的 Effective，修改后整体提交为 Template。

个人版仅支持 default 数据空间；企业版配置影响所选数据空间内的所有 User 及其 Peer，不支持 User 或 Peer 单独覆盖。其他数据空间和其他记忆类型不受本次更新影响。
密钥和公共请求约定见数据库管理 API 使用说明；签名流程见API 签名调用指南。

请求接口

项目	值
Action	UpdateOpenVikingMemoryTemplate
Version	2025-06-09
请求方法	POST
公网请求地址	https://vikingdb.cn-beijing.volcengineapi.com/
Content-Type	application/json
签名 Service / Region	vikingdb / cn-beijing

POST /?Action=UpdateOpenVikingMemoryTemplate&Version=2025-06-09 HTTP/1.1
Host: vikingdb.cn-beijing.volcengineapi.com
Content-Type: application/json
X-Date: <签名生成的 UTC 时间>
X-Content-Sha256: <请求体 SHA-256>
Authorization: <火山引擎 AK/SK 签名>

请求参数

字段	类型	必填	说明
ResourceID	string	是	OpenViking 库 ID，例如 ov-example。
OpenVikingAccountID	string	否	库内已有的数据空间 ID。省略、null、空字符串或纯空白时使用 default；显式传值时去除两端空白。个人版库：个人版没有多空间，可不传此参数，或使用 default。企业版库：企业版库内可创建多个数据空间，您需要传入对应数据空间的ID（创建空间时定义的ID），不传则为 default。
MemoryType	string	是	严格小写，取值：profile、preferences、entities、events、soul、identity。
Template	object	是	待发布的开放配置，不能省略或为 null。允许空对象，但此时发布默认值副本，状态仍为 custom。

Template

字段	类型	必填	说明
description	string	否	记忆类型的抽取说明。提交时必须为非空、非纯空白字符串，最多 50,000 个 Unicode 码点。
fields	array[object]	否	字段生成说明。省略或空数组时，所有字段说明采用当前默认值。
fields[].name	string	是	该 MemoryType 允许编辑的既有字段名，不能重复。
fields[].description	string	是	字段生成说明，非空、非纯空白，最多 50,000 个 Unicode 码点。不接受 null。
content_template	string	否	仅 events、soul、identity 支持。非空、非纯空白，UTF-8 编码不超过 65,536 字节。其他类型不得提交此键，包括 null。

fields 中每一项只能包含 name、description。外层参数使用 PascalCase，Template 内使用上述小写键名；fields 必须是数组，不能改为以字段名为键的对象。

默认补齐规则

未提交的配置使用当前系统默认值补齐，不保留上一次的自定义值。

提交方式	发布结果
仅提交 description	更新类型描述；字段说明和正文模板采用当前 Defaults。
fields 仅含部分字段	提交字段采用自定义说明，其他字段采用默认说明。
fields 省略或为空数组	所有字段使用默认说明，不会删除字段。
Template 为 {}，或内容与 Defaults 完全相同	发布默认内容的自定义配置，Status 仍为 custom。
复制 Effective，修改后整体提交	保留本次提交中未修改的自定义内容，适合编辑现有配置。

需要将状态恢复为 system_default 时，请调用 ResetOpenVikingMemoryTemplate。

各类型允许编辑的字段

所有类型均支持顶层 description。下表中的字段名称填写在 fields[].name 中。各类模板下的字段策略和影响范围见：自定义记忆抽取指令。

MemoryType	允许编辑的字段说明
profile	content：画像正文
preferences	topic：偏好主题；content：偏好正文
entities	category：实体分类；name：实体名称；content：实体卡片正文
events	event_name：事件名称；summary：事件摘要
soul	core_truths：核心价值；boundaries：边界规则；vibe：沟通气质；continuity：连续性规则
identity	creature：身份类型；name：助手名称；vibe：表达气质；avatar：头像；emoji：标志 Emoji；introduction：自我介绍

长度与模板语法限制

description 和每个 fields[].description 分别计算长度，最多 50,000 个 Unicode 码点；content_template 按 UTF-8 字节计算，最多 64 KiB。
空格、换行和 Jinja 源码均计入长度。组合字符、多码点 Emoji 按实际码点数计算。
Template 序列化后的 JSON 不超过 1 MiB，服务端补齐默认值后的 YAML 也不超过 1 MiB。
description 支持非空、长度及 Jinja 语法校验，可使用 {{ language }} 表达抽取语言要求。其校验规则与正文模板不同，不保证发布时识别所有未知变量。

content_template 可用变量

MemoryType	允许引用的变量
events	event_name、goal、summary、ranges
soul	core_truths、boundaries、vibe、continuity
identity	name、creature、vibe、emoji、avatar、introduction

language 不属于 content_template 可用变量。正文模板支持以下 Jinja 子集：

if / elif / else、比较和布尔条件。
set 定义局部变量；不能覆盖该类型字段、extract_context 或 loop，变量名不能以 _ 开头。
for 遍历显式列表或元组，每个循环最多 32 项，不支持嵌套和递归。支持 loop.index、index0、first、last、length。
过滤器：default、trim、lower、upper、length；测试：defined、undefined、none、string。

仅 events 额外支持以下 extract_context 方法：

方法	用途
extract_context.get_resource_event_content(ranges, summary)	获取资源添加事件正文，可能包含资源 Markdown 链接。
extract_context.get_first_message_time_from_ranges(ranges)	获取来源消息日期。
extract_context.get_first_message_time_with_weekday_from_ranges(ranges)	获取来源消息日期和星期。
extract_context.get_event_content(ranges, summary[, ratio_threshold])	在原始对话内容与摘要之间选择正文。
extract_context.get_year(ranges)、get_month(ranges)、get_day(ranges)	获取来源消息的年、月、日。

方法只接受位置参数；首参须为 ranges，或受支持的 ranges|default('') 形式，不能自行构造或覆盖消息范围。ratio_threshold 显式传入时须为 0～1 的数字字面量，省略时为 0.2；内置模板显式传 0 时优先使用原始对话内容。
修改正文模板可以调整标题、顺序、固定文案和字段显示条件。隐藏字段不会关闭抽取或删除系统元数据、原始 Session。移除 Events 的资源分支会影响资源链接展示；保留原始对话分支时，仅修改 summary 的生成说明仍可能展示原消息。正文变化也可能影响 Events 的检索输入。

生效与并发说明

校验通过后保存并发布，返回 Status=custom。成功表示配置已发布，不表示已调用模型或生成新记忆，无需轮询 Task。
抽取任务读取数据空间配置时使用当时的模板。已开始抽取的任务使用原配置快照；已排队、尚未读取配置的任务可能使用新配置。
发布不会主动重写历史记忆。后续抽取仍可能按既有合并规则更新已有文件。
相同配置重复发布时，UpdatedAt 可能保持不变，不能以时间必须变化作为成功条件。
不提供 ExpectedVersion、ETag 或 If-Match 并发控制。UpdatedAt 不能用作服务端乐观锁；多个管理员同时编辑可能覆盖彼此修改，建议在应用侧协调发布。
请求超时或结果不明时，先调用 Get 查询当前状态和 Effective，再决定是否重试。收到 OperationConflict 时，重新读取配置并确认后重试，不自动合并或覆盖。

需要恢复此前自定义版本时，可将预先保存的完整 Effective 重新提交；需要恢复系统默认时使用 Reset。恢复模板不会撤销已生成的记忆。

响应参数

成功响应由 ResponseMetadata 和 Result 组成，没有额外的 Success 字段。失败时查看 ResponseMetadata.Error.Code、Error.Message，并保留 RequestId。

Result 字段	类型	说明
OpenVikingAccountID	string	实际更新的数据空间 ID。
MemoryType	string	本次更新的记忆类型。
Status	string	成功发布后为 custom。
UpdatedAt	string / null	自定义配置发布时间，带时区的 ISO 8601 字符串；公共响应类型允许 null，无覆盖时为空。
Defaults	object	当前部署的默认开放配置。
Effective	object	发布后完整的生效配置，包含默认补齐结果。

Defaults、Effective 包含 description、fields，以及类型支持时的 content_template；fields 为 name、description 对象数组。响应中的字段 description 类型允许 string / null，提交时须为非空字符串。应以返回的 Effective 刷新本地配置。

常见错误码

HTTP 状态码	错误码	说明及处理建议
400	InvalidParameter	参数、字段、长度或 Jinja 校验失败，或个人版选择了非 default 空间。根据 Message 修正，保留待发布内容。
400	InvalidRequest	当前内核不支持模板接口。联系维护人员确认升级。
401 / 403	AuthenticationError	签名缺失、无效或身份校验失败。检查 AK/SK、签名时间及请求内容。
403	AccessDenied	无权操作目标资源。检查授权，不自动重试写请求。
404	ResourceNotExist	库、空间或模板不存在。核对目标，不自动切换 default。
409	OperationConflict	另一模板操作占用锁。读取最新配置，确认后重试。此错误不等于版本冲突检查。
412	FailedPrecondition	存储配置损坏或当前配置不可用。联系维护人员检查。
429	QuotaExceeded	超出配额或触发限流。退避后先核对状态，再决定是否重试。
500	InternalError	服务内部异常。保留内容和 RequestId，查询状态后再处理。

公共鉴权和网关错误见数据库管理 API 使用说明。具体频率配额以服务配置为准；接口无分页参数。

完整示例

请求体

以下完整提交 events 的开放配置，将事件正文组织为名称、摘要和可选目标。模板未保留默认配置中可能包含的日期、来源对话和资源链接；需要这些内容时，请在 Get 返回的 Effective 基础上修改。

{
  "ResourceID": "ov-example",
  "OpenVikingAccountID": "default",
  "MemoryType": "events",
  "Template": {
    "description": "记录业务相关的明确事件、决定和结果，排除闲聊及未经确认的建议。",
    "fields": [
      {"name": "event_name", "description": "简短概括一个已确认的事件，使用 {{ language }}。"},
      {"name": "summary", "description": "保留参与者、日期、明确决定和结果，使用 {{ language }}。"}
    ],
    "content_template": "# {{ event_name }}\n\n## 摘要\n{{ summary }}\n\n{% if goal %}## 目标\n{{ goal }}{% endif %}"
  }
}

Python 签名调用示例

安装 volcengine 和 requests，在服务端环境配置 VOLC_ACCESSKEY、VOLC_SECRETKEY。此示例会发布配置，执行前请替换示例库 ID，并确认数据空间和模板内容。

pip install volcengine requests

import json
import os

import requests
from volcengine.auth.SignerV4 import SignerV4
from volcengine.base.Request import Request
from volcengine.Credentials import Credentials

HOST = "vikingdb.cn-beijing.volcengineapi.com"
ACTION = "UpdateOpenVikingMemoryTemplate"
BODY = {
    "ResourceID": "ov-example",
    "OpenVikingAccountID": "default",
    "MemoryType": "events",
    "Template": {
        "description": "记录业务相关的明确事件、决定和结果，排除闲聊及未经确认的建议。",
        "fields": [
            {
                "name": "event_name",
                "description": "简短概括一个已确认的事件，使用 {{ language }}。"
            },
            {
                "name": "summary",
                "description": "保留参与者、日期、明确决定和结果，使用 {{ language }}。"
            }
        ],
        "content_template": "# {{ event_name }}\n\n## 摘要\n{{ summary }}\n\n{% if goal %}## 目标\n{{ goal }}{% endif %}"
    }
}

# 只序列化一次，签名和发送使用相同的请求体。
payload = json.dumps(BODY, ensure_ascii=True, separators=(",", ":"))
query = {"Action": ACTION, "Version": "2025-06-09"}
request = Request()
request.set_method("POST")
request.set_host(HOST)
request.set_path("/")
request.set_headers({"Host": HOST, "Content-Type": "application/json"})
request.set_query(query)
request.set_body(payload)
credentials = Credentials(
    os.environ["VOLC_ACCESSKEY"],
    os.environ["VOLC_SECRETKEY"],
    "vikingdb",
    "cn-beijing",
)
SignerV4.sign(request, credentials)

response = requests.post(
    "https://" + HOST + "/",
    params=query,
    headers=request.headers,
    data=payload.encode("utf-8"),
    timeout=30,
)
result = response.json()
error = result.get("ResponseMetadata", {}).get("Error")
if not response.ok or error:
    raise RuntimeError({"http_status": response.status_code, "response": result})
print(json.dumps(result, ensure_ascii=False, indent=2))

签名 SDK 见火山引擎 Python SDK。签名与发送使用同一份 JSON 序列化结果；不要改用重新序列化的请求体。示例已完成离线语法与签名结构校验，未执行线上发布。

响应示例

Defaults 内容仅作结构示意，以实际接口返回为准。

{
  "ResponseMetadata": {
    "RequestId": "example-update-request-id",
    "Action": "UpdateOpenVikingMemoryTemplate",
    "Version": "2025-06-09",
    "Service": "vikingdb",
    "Region": "cn-beijing"
  },
  "Result": {
    "OpenVikingAccountID": "default",
    "MemoryType": "events",
    "Status": "custom",
    "UpdatedAt": "2026-09-20T08:00:00+00:00",
    "Defaults": {
      "description": "<系统默认的事件抽取说明>",
      "fields": [
        {"name": "event_name", "description": "<系统默认的事件名称说明>"},
        {"name": "summary", "description": "<系统默认的事件摘要说明>"}
      ],
      "content_template": "<系统默认的事件 Markdown 模板原文>"
    },
    "Effective": {
      "description": "记录业务相关的明确事件、决定和结果，排除闲聊及未经确认的建议。",
      "fields": [
        {"name": "event_name", "description": "简短概括一个已确认的事件，使用 {{ language }}。"},
        {"name": "summary", "description": "保留参与者、日期、明确决定和结果，使用 {{ language }}。"}
      ],
      "content_template": "# {{ event_name }}\n\n## 摘要\n{{ summary }}\n\n{% if goal %}## 目标\n{{ goal }}{% endif %}"
    }
  }
}

最近更新时间：2026.09.22 22:12:22

这个页面对您有帮助吗？

有用

无用

向量数据库VikingDB

Template #

默认补齐规则 #

各类型允许编辑的字段 #

长度与模板语法限制 #

content_template 可用变量 #

生效与并发说明 #

请求体 #

Python 签名调用示例 #

响应示例 #