文档中心

向量数据库VikingDB

请输入

会话 (Sessions)

commit_session-提交会话

概述

/api/v1/sessions/{id}/commit 接口用于提交会话。
提交后，系统会先完成消息归档（Phase 1），随后在后台异步执行摘要生成与记忆提取（Phase 2）。因此，该接口是把会话消息正式沉淀为长期上下文的关键步骤。

前置条件

完成 "数据库访问使用说明" 页面的 API Key 获取后，可调用本接口提交会话。通常你需要先向该会话写入至少一条消息。

请求接口

URI

/api/v1/sessions/{id}/commit
统一资源标识符。

请求方法

POST
客户端对服务器请求的操作类型。

请求头

参数	值	说明
Content-Type	`application/json`	请求消息类型
Authorization	`Bearer {api_key}`	鉴权
X-OpenViking-Agent	`{agent_id}`	Agent ID

路径参数

参数	类型	必填	说明
`session_id`	string	是	要提交的 Session ID。Session 必须存在且属于当前认证用户。

请求参数

参数	类型	必填	说明
`keep_recent_count`	integer	否	默认 0，范围 0–10000。按消息条数保留最新消息；0 表示全部归档。仅在未启用 Turn 保留模式时生效。
`retention_mode`	string 或 null	否	当前仅支持 `turn_budget`。启用后按逻辑 Turn 和 token 预算保留上下文。
`keep_recent_turn_count`	integer	否	范围 0–10000；Turn 模式默认 3。传入时必须同时设置 `retention_mode=turn_budget`。
`retained_message_token_budget`	integer	否	最小值 1；Turn 模式默认 12000。保留的原始消息与 checkpoint 共用该预算。
`min_raw_tail_steps`	integer	否	范围 0–10000；Turn 模式默认 1。至少保留的最新原始 Assistant Step 数。
`extraction_metadata`	object 或 null	否	本次 Commit 的记忆抽取覆盖配置。目前支持 `event.tags`。

extraction_metadata 参数

参数	类型	必填	说明
`event`	object 或 null	否	事件记忆的单次抽取覆盖配置。
`event.tags`	string[] 或 null	否	本次抽取生成或更新的事件记忆标签。每项必须是严格的 `key=value` 字符串。

响应消息

字段	类型	说明
`result.session_id`	string	Session ID。
`result.status`	string	`accepted` 表示 Phase 2 已入队；`skipped` 表示没有可归档内容。
`result.task_id`	string 或 null	后台记忆抽取任务 ID；跳过提交时为 null。
`result.archive_uri`	string 或 null	本次归档 URI；跳过提交时为 null。
`result.archived`	boolean	是否实际产生归档。
`result.reason`	string	仅跳过时返回：`no_messages` 或 `all_within_keep_window`。
`result.trace_id`	string	本次提交链路的追踪 ID。
`result.estimated_active_tokens`	integer	Turn 保留计划估算的活跃 token 数；非 Turn 模式通常为 0。
`result.budget_exceeded`	boolean	Turn 保留计划是否仍超过预算。

常见错误码

error.code	说明
UNAUTHENTICATED	缺少 API Key 或 API Key 无效
PERMISSION_DENIED	API Key 权限不足
NOT_FOUND	指定会话不存在
PROCESSING_ERROR	会话归档提交失败

完整示例

curl -X POST 'http://127.0.0.1:1933/api/v1/sessions/support-agent-20260821/commit' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: your-user-key' \
  -d '{
    "keep_recent_count": 0,
    "extraction_metadata": {
      "event": {
        "tags": ["team=support", "channel=web"]
      }
    }
  }'

执行成功返回：

"status": "ok",
  "result": {
    "session_id": "support-agent-20260821",
    "status": "accepted",
    "task_id": "1d7a7707-b15b-44e6-9bb2-45bfa9cebb45",
    "archive_uri": "viking://user/default/sessions/support-agent-20260821/history/archive_001",
    "archived": true,
    "trace_id": "trace-8c6747",
    "estimated_active_tokens": 0,
    "budget_exceeded": false
  }
}

参数、示例与排错补充

返回参数描述不完整：返回结构采用统一包装：status 为 string，result 为 object/array/null，telemetry 为 object/null，error 为 object/null；业务子字段的类型和层级与成功示例保持一致。
返回参数描述不完整：返回字段 result.status 已按响应示例补充类型和层级；公共包装字段为 status:string、result:object|array|null、telemetry:object|null、error:object|null。
标识型参数缺少获取规则：agent_id 在 OpenViking 控制台的 Agent 接入页创建或选择 Agent 后复制；请求头 X-OpenViking-Agent 必须传该值，不能使用 Agent 名称代替。
标识型参数缺少获取规则：会话 id/session_id 从创建会话接口的 result.id（或记忆库 AddSession 返回值）取得，也可由列出会话接口查询；不要把示例 ID 用于生产请求。
错误码原因或处理建议缺失：错误处理建议：UNAUTHENTICATED：检查并重新生成 API Key；PERMISSION_DENIED：确认 Agent/账号对目标 URI 有权限；INVALID_ARGUMENT：按参数表检查类型、范围和必填项；NOT_FOUND：确认 URI 或资源 ID 存在；INTERNAL：记录 request ID 后重试，持续失败时提交工单。

最近更新时间：2026.09.03 14:54:52

这个页面对您有帮助吗？

有用

无用

向量数据库VikingDB

概述 #

前置条件 #

请求接口 #

URI #

请求方法 #

请求头 #

路径参数

请求参数 #

extraction_metadata 参数

响应消息 #

常见错误码 #

完整示例 #

参数、示例与排错补充 #

概述