reindex-重建索引--向量数据库VikingDB-火山引擎

文档中心

向量数据库VikingDB

文件内容（File Contents）

reindex-重建索引

概述

/api/v1/content/reindex 接口用于对已经存储在 OpenViking 中的现有内容，重新构建语义产物和/或向量索引。这是一个运维维护接口，适用于 embedding 模型更换、向量库重刷、修复索引不一致等场景。

前置条件

完成 API 鉴权说明页面的 API Key 获取后，可调用本接口重建索引。

请求接口

URI	/api/v1/content/reindex	统一资源标识符
请求方法	POST	客户端请求类型
请求头	Content-Type: application/json	请求消息类型
	Authorization: Bearer	Bearer Token 鉴权（与 X-Api-Key 二选一）

请求参数

参数	类型	必选	默认值	备注
uri	string	是	--	要重新索引的 Viking URI HTTP 请求体不接受未知字段。`uri` 可以使用其他 content API 支持的 OpenViking 路径变量，服务端会先解析再校验。
mode	string	否	`vectors_only`	重建模式 `vectors_only`：基于当前仍可恢复的源数据重建向量库记录 `semantic_and_vectors`：先重新生成语义产物，例如.abstract.md 和 .overview.md，再基于新的语义结果重建向量。
wait	bool	否	`true`	是否等待任务完成 `true`：同步等待重建完成后再返回。 `false`：异步处理，接口立即返回任务 ID。

支持的 URI 范围：

URI	说明
`viking://`	全局
`viking://user`	用户命名空间
`viking://user/<user_id>`	特定用户
`viking://agent`	Agent 命名空间
`viking://agent/<agent_id>`	特定 Agent
`viking://resources`	资源
`viking://resources/...`	特定资源路径
`viking://user/<user_id>/memories/...`	用户记忆
`viking://agent/<agent_id>/memories/...`	Agent 记忆
`viking://agent/<agent_id>/skills`	Agent 技能
`viking://agent/<agent_id>/skills/<skill_name>`	特定技能

reindex 不支持 viking://session/...。

模式说明：

vectors_only：基于当前仍可恢复的源数据重建向量库记录，不会重写 .abstract.md 和 .overview.md。
semantic_and_vectors：先重新生成语义产物，再基于新的语义结果重建向量。对于 resource 和 skill，会刷新目录/文件语义产物，包括 .abstract.md 和 .overview.md。对于 memory，会重建当前已持久化 memory 子树的语义和向量，但不会回放历史记忆抽取顺序。语义刷新和向量重建由 reindex executor 串行编排。语义刷新阶段不会再额外向后台 embedding queue 投递自己的向量化任务；向量由 reindex 阶段统一重建，因此 wait=true 表示等待 reindex 操作本身完成。

响应消息

字段	参数说明
status	请求状态，成功为 `"ok"`，失败为 `"error"`
result	成功时返回的数据对象
result.status	同步完成时为 `"completed"`，后台执行时为 `"accepted"`
result.uri	解析路径变量后的请求 URI
result.mode	实际执行的 reindex 模式
result.object_type	推断出的目标类型，例如 `resource`、`skill`、`memory`、`user_namespace`、`agent_namespace`、`skill_namespace` 或 `global_namespace`
result.scanned_records	被检查的记录或语义源数量
result.rebuilt_records	成功重建的向量记录数量
result.unsupported_records	因没有可用向量来源而跳过的记录数量
result.failed_records	重建失败的记录数量
result.duration_ms	同步执行耗时，单位毫秒
result.warnings	可恢复的单条记录级 warning
result.task_id	后台任务 ID，仅 `wait=false` 时返回
time	请求耗时（秒）
error	失败时返回的错误对象
error.code	错误码字符串，常见值见下表
error.message	可读的错误描述

常见错误码：

error.code	说明
UNAUTHENTICATED	缺少 API Key 或 API Key 无效
PERMISSION_DENIED	权限不足（需要 root/admin 权限）
INVALID_ARGUMENT	无效参数
INVALID_URI	无效的 Viking URI 格式
CONFLICT	同一 URI 和 owner 已有正在运行的 reindex 任务

完整示例

示例一：同步重建向量索引

curl -X POST https://xxx/api/v1/content/reindex \
  -H "X-Api-Key: your-api-key" \
  -H "X-OpenViking-Account: default" \
  -H "Content-Type: application/json" \
  -d '{
    "uri": "viking://resources",
    "mode": "vectors_only",
    "wait": true
  }'

执行成功返回：

HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "ok",
    "result": {
        "uri": "viking://resources",
        "mode": "vectors_only",
        "status": "completed",
        "object_type": "resource",
        "scanned_records": 120,
        "rebuilt_records": 118,
        "unsupported_records": 2,
        "failed_records": 0,
        "duration_ms": 1284,
        "warnings": []
    },
    "time": 0.1
}

示例二：异步重建语义与向量索引

curl -X POST https://xxx/api/v1/content/reindex \
  -H "X-Api-Key: your-api-key" \
  -H "X-OpenViking-Account: default" \
  -H "Content-Type: application/json" \
  -d '{
    "uri": "viking://agent/default/skills",
    "mode": "semantic_and_vectors",
    "wait": false
  }'

执行成功返回：

HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "ok",
    "result": {
        "uri": "viking://agent/default/skills",
        "mode": "semantic_and_vectors",
        "object_type": "skill",
        "status": "accepted",
        "task_id": "task_xxx"
    },
    "time": 0.1
}

可使用返回的 task_id 查询后台任务：

curl -X GET https://xxx/api/v1/tasks/task_xxx \
  -H "X-Api-Key: your-api-key" \
  -H "X-OpenViking-Account: default"

Reindex 后台任务的 task_type 为 admin_reindex，resource_id 等于请求中的 uri，也可以这样列出：

GET /api/v1/tasks?task_type=admin_reindex&resource_id=viking://resources

任务记录保存在内存中，可能过期，也会在服务重启后丢失。

行为说明

Reindex 是非破坏式的，采用重建/覆盖写入，不需要先 drop 向量集合。
对 viking:// 发起 reindex 时，会向下分发到支持的顶层命名空间，并显式排除 session。
命名空间级 reindex，例如 viking://user 或 viking://agent/default，会继续传播到其支持的子内容类型。
如果只是 embedding 模型或向量索引需要刷新，应使用 vectors_only。
如果语义产物本身也需要重建，再做重向量化，应使用 semantic_and_vectors。
同一个 URI 和 owner 同时只能运行一个 reindex 任务。对同一目标的并发请求会返回 conflict。
对 resource 文件，文本文件在没有 summary 时可以使用文件正文；非文本文件需要已生成的 summary 或已有向量记录 fallback，否则会计为 unsupported。

当前限制

Reindex 会使用当前系统中"尽可能可恢复"的输入进行重建，不保证所有场景都能逐字节回放历史当时的 embedding 输入。
Memory 的 semantic reindex 基于当前已持久化的 memory 树，不会重建最初按时间顺序执行的记忆抽取流水线。

最近更新时间：2026.06.02 16:07:52

这个页面对您有帮助吗？

有用

无用

向量数据库VikingDB

示例一：同步重建向量索引 #

示例二：异步重建语义与向量索引 #

示例一：同步重建向量索引

示例二：异步重建语义与向量索引