实时添加会话-StreamingWrite--向量数据库VikingDB-火山引擎

文档中心

向量数据库VikingDB

会话管理

实时添加会话-StreamingWrite

接口概述

实时接收客户系统的单轮对话消息（user / assistant 角色的发言，即 message），存入对应 conversation_id 的短期记忆缓存；同时根据配置的抽取规则（每累计 N 个 token 触发，每累计 N个 message 条数触发，或超时触发），自动触发长期记忆抽取。
通过该接口，实现自动的记忆抽取、同一对话内的上下文压缩能力。

请求接口

URL	/api/memory/session/streaming_write	统一资源标识符
请求方法	POST	客户端对记忆库服务器请求的操作类型
请求头	Content-Type: application/json	请求消息类型
请求头	Authorization: HMAC-SHA256 ***	基于AK/SK生成的签名信息

请求参数

参数名称	参数类型	是否必须	参数说明
collection_name	String	否	目标记忆库的名称。
project_name	String	否	记忆库所属项目。
resource_id	String	否	记忆库唯一的资源id。可选择直接传resource_id，或同时传collection_name和project_name作为记忆库的唯一标识。
conversation_id	String	是	当前对话ID。长度要求: [1, 128]，只能使用英文字母、数字、下划线，并以英文字母开头。
messages	Array of Object	是	要添加的多轮对话消息列表。不超过100条。
extract_trigger	Object	否	触发记忆抽取的条件。
store_file	Bool	否	是否存储原始文件。默认值 False，即不存储，则原始文件仅用于抽取记忆。
metadata	Object	否	用于设定这批消息的元数据信息。
extract_memory_type	Array of String	否	此次数据写入需要抽取的记忆类型。填写事件或画像类型的名称，可以是多个值。不传时默认会抽取所有类型的记忆。
profiles	Array of Object	否	需要特别关注或更新的画像信息列表。系统会尝试将处理后的事件与这些画像关联。
ttl_absolute	Integer	否	事件记忆的过期时间，绝对时间，填写时间戳，精确到毫秒级。相对时间和绝对时间都填写时，取绝对时间；都不填写时，取记忆库的过期配置。限制: ttl_absolute - metadata.time ∈ (0, 315576000 * 1000]；如果messages中的time不为空，ttl_absolute - message.time ∈ (0, 315576000 * 1000]
ttl_relative	Integer	否	事件记忆的过期时间，相对时间，单位为秒。限制: (0, 315576000]

注意：

对于 extract_trigger, metadata, profiles 等字段，不同的请求设置不同时，以触发更新时的配置为准。
profile_type需要为extract_memory_type里画像类型的子集。
只有在 messages 中同时传入 user 和 assistant 的消息时，画像和事件才会正确归属用户和助手。接口不会仅依赖 metadata 中的 ID 进行关联；如果只传 user 消息，事件不会关联到 metadata 中的 assistant。
记忆的隔离机制：
- 事件：不同assistant、group相关的 message 生成的事件，会带上对应的标识，检索时可使用对应的参数进行过滤。
- 画像：画像的隔离分为两层：
  - group：不同group生成的画像是完全隔离的（注意，group不代表群聊，只有在需要做画像隔离时，才建议使用group）
  - assistant：如果画像选择了按照 assistant 隔离，那么在同一group下，不同 assistant 和用户的消息生成的画像是完全隔离的；如果原始消息中没有传入 assistant，那么就会生成不关联 assistant 的画像（assistant_id=""）。

响应消息

参数名称	参数类型	参数说明
code	Integer	状态码，0表示成功，其他表示错误。
message	String	返回信息，成功时通常为 "success"。
data	Object	返回的详细数据。
request_id	String	标识每个请求的唯一ID。

示例代码

Python请求

import os
import json
import time
import requests

API_KEY = os.environ.get("MEMORY_API_KEY")
url = "https://api-knowledgebase.mlp.cn-beijing.volces.com/api/memory/session/add"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

now_ts = int(time.time() * 1000)

data = {
    "collection_name": "my_first_memory_collection",  # 替换为你的记忆库名称
    "project_name": "default",
    "conversation_id": "conversation_001",
    "messages": [
        {"role": "user", "content": "今天天气怎么样？"},
        {"role": "assistant", "content": "今天天气晴朗，气温22度，非常适合外出。"}
    ],
    "extract_trigger": {
        "token_count": 3000,
        "message_count": 50,
        "wait_timeout": 86400
  }
}

response = requests.post(url, headers=headers, data=json.dumps(data, ensure_ascii=False))

print("Status Code:", response.status_code)
print("Response:", response.text)

最近更新时间：2026.03.16 17:44:35

这个页面对您有帮助吗？

有用

无用

向量数据库VikingDB

Python请求 #

Python请求