add_resource-导入资源--向量数据库VikingDB-火山引擎

文档中心

向量数据库VikingDB

资源（Resources）

add_resource-导入资源

概述

/api/v1/resources 接口用于向 OpenViking 导入一个资源（文档、网页、代码仓库等），并触发内容解析和索引处理。资源导入后可被 Agent 检索和引用。

资源来源支持两种方式：通过 temp_file_id 引用已上传的临时文件（推荐），或通过 path 指定远程 HTTP(S)/Git URL。出于安全限制，接口不允许直接指定服务器本地文件路径。

前置条件

完成 API 鉴权说明页面的 API Key 获取后，可调用本接口导入资源。如需上传本地文件，请先调用 /api/v1/resources/temp_upload 获取 temp_file_id。

请求接口

URI	/api/v1/resources	统一资源标识符
请求方法	POST	客户端对服务器请求的操作类型
请求头	Content-Type: application/json	请求消息类型
	Authorization: Bearer {api_key}	鉴权
	X-OpenViking-Agent: {agent_id}	Agent ID

请求参数

参数	类型	必选	默认值	备注
temp_file_id	string	必选	--	临时文件 ID 通过 `/api/v1/resources/temp_upload` 上传文件后获得。
to	string	否	自动生成	资源目标 URI 格式为 `viking://resources/<path>`，指定资源在存储系统中的路径。若不指定，系统自动生成 URI。不能与 `parent` 同时使用。
parent	string	否	--	父级 URI 指定资源存储到某个父目录下，自动生成子 URI。不能与 `to` 同时使用。
reason	string	否	`""`	导入原因用于记录和监控，描述本次资源导入的用途。
instruction	string	否	`""`	处理指令提供额外提示，指导系统如何解析和整理资源内容。
wait	bool	否	false	是否等待处理完成 `true`：等待内容解析和索引处理完成后再返回。 `false`（默认）：提交任务后立即返回 URI，后续由系统在后台处理。
timeout	float	否	null	等待超时时间（秒）仅当 `wait=true` 时生效。`null` 表示不限超时。
strict	bool	否	false	是否启用严格模式严格模式下解析错误会导致整体失败。
source_name	string	否	原始文件名	资源来源名称用于展示和标识。未指定时，若通过 `temp_file_id` 导入，默认使用上传时的原始文件名。
ignore_dirs	string	否	--	忽略的目录名列表逗号分隔的目录名，解析时跳过这些目录。仅对目录类型资源有效。
include	string	否	--	包含文件的匹配规则仅解析匹配该规则的文件，例如 `*.md`。仅对目录类型资源有效。
exclude	string	否	--	排除文件的匹配规则跳过匹配该规则的文件，例如 `node_modules/**`。仅对目录类型资源有效。
directly_upload_media	bool	否	true	是否直接上传媒体文件 `true`：将媒体文件（图片等）直接上传存储，不做额外处理。
preserve_structure	bool	否	--	是否保留目录结构导入目录类型资源时是否保留原始层级结构。
watch_interval	float	否	0	自动监控间隔（分钟） `> 0`：创建或更新监控任务，按指定间隔自动重新处理资源。 `= 0` 或 `< 0`：不创建监控任务；若已存在监控任务则取消。 `watch_interval > 0` 时必须同时指定 `to` 参数。若目标 URI 已有活跃监控任务，会返回 `CONFLICT` 错误，需先将 `watch_interval` 设为 `0` 取消后再重新创建。
telemetry	bool / object	否	false	是否返回调用统计信息 `true` 或 `{"summary": true}`：在响应中包含操作耗时等汇总信息。

响应消息

字段	参数说明
status	请求状态，成功为 `"ok"`，失败为 `"error"`
result	成功时返回的数据对象
result.status	处理状态，成功为 `"success"`
result.errors	处理过程中产生的错误列表
result.source_path	服务端实际处理的源文件路径。远程 URL 会先下载到临时文件后再处理。
result.meta	资源元信息，例如 `content_type`、`format` 等
result.root_uri	资源的正式访问地址，格式为 `viking://resources/<path>`。可用于后续检索、更新或删除该资源。
result.temp_uri	本次处理过程中生成的临时资源地址
error	失败时返回的错误对象
error.code	错误码字符串，常见值见下表
error.message	可读的错误描述
telemetry	调用统计信息，例如接口耗时（仅当请求参数 `telemetry=true` 时返回）

常见错误码：

error.code	说明
UNAUTHENTICATED	缺少 API Key 或 API Key 无效
PERMISSION_DENIED	尝试使用本地文件路径、无效的临时上传文件，或 API Key 权限不足
INVALID_ARGUMENT	参数错误，例如同时指定了 `to` 和 `parent`，或 `watch_interval > 0` 时未指定 `to`
CONFLICT	目标 URI 已存在活跃的监控任务
PROCESSING_ERROR	资源解析或索引处理失败

完整示例

示例一：上传本地文件并导入资源

先上传临时文件，再通过 temp_file_id 导入：

# 第一步：上传临时文件
curl -X POST https://xxx/api/v1/resources/temp_upload \
  -H "Authorization: Bearer {api_key}" \
  -H "X-OpenViking-Agent: {agent_id}" \
  -F "file=@my_document.md"

# 返回：{"status":"ok","result":{"temp_file_id":"upload_abc123def456.md"}}

# 第二步：导入资源
curl -X POST https://xxx/api/v1/resources \
  -H "Authorization: Bearer {api_key}" \
  -H "X-OpenViking-Agent: {agent_id}" \
  -H "Content-Type: application/json" \
  -d '{
    "temp_file_id": "upload_abc123def456.md",
    "reason": "导入外部文档"
  }'

执行成功返回：

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

{
    "status": "ok",
    "result": {
        "status": "success",
        "errors": [],
        "source_path": "/tmp/openviking/upload/upload_abc123def456.md",
        "meta": {},
        "root_uri": "viking://resources/my_document",
        "temp_uri": "viking://temp/default/05090742_9cf1f8/my_document"
    }
}

示例二：从远程 URL 导入资源

curl -X POST https://xxx/api/v1/resources \
  -H "Authorization: Bearer {api_key}" \
  -H "X-OpenViking-Agent: {agent_id}" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "https://example.com/assets/product-image.webp",
    "to": "viking://resources",
    "reason": "导入外部文档"
  }'

执行成功返回：

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

{
    "status": "ok",
    "result": {
        "status": "success",
        "errors": [],
        "source_path": "/tmp/tmpabcd1234.webp",
        "meta": {
            "content_type": "image",
            "format": "webp"
        },
        "root_uri": "viking://resources/tmpabcd1234_webp",
        "temp_uri": "viking://temp/default/05090739_45e02e/tmpabcd1234_webp"
    }
}

远程 URL 资源会被下载到服务端临时路径，最终 root_uri 可能按解析后的临时文件名自动生成。

执行失败返回（参数错误）：

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "status": "error",
    "error": {
        "code": "INVALID_ARGUMENT",
        "message": "watch_interval > 0 requires 'to' to be specified"
    }
}

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

这个页面对您有帮助吗？

有用

无用

向量数据库VikingDB

示例一：上传本地文件并导入资源 #

示例二：从远程 URL 导入资源 #

示例一：上传本地文件并导入资源

示例二：从远程 URL 导入资源