文档中心

向量数据库VikingDB

资源（Resources）

add_resource- 添加资源

概述

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

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

前置条件

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

请求接口

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

请求参数

参数	类型	必选	默认值	备注
`temp_file_id`	string	是	--	临时文件 ID，和`path-or-url`二选一填写即可通过 `/api/v1/resources/temp_upload` 上传文件后获得。
`path-or-url`	string	是	--	要导入的本地路径或URL ，和`temp_file_id`二选一填写即可
`to`	string	否	自动生成	资源目标 URI 格式为 `viking://resources/<path>`，指定资源在存储系统中的路径。若不指定，系统自动生成 URI。不能与 `parent` 同时使用。
`parent`	string	否	--	父级 URI 指定资源存储到某个父目录下，自动生成子 URI。不能与 `to` 同时使用。
`reason`	string	否	`""`	导入原因用于记录和监控，描述本次资源导入的用途。
`instruction`	string	否	`""`	处理指令提供额外提示，指导系统如何解析和整理资源内容。
`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` 取消后再重新创建。
`args.feishu_access_token`	string	是	--	上传飞书文档必填， user_access_token，获取方式见上传飞书文档 OpenViking 使用该 Token 以用户身份读取飞书文档。
`args.feishu_refresh_token`	string	否	--	上传飞书文档， refresh_token，获取方式见上传飞书文档仅定时同步场景需要传入。一次性导入不建议传入，避免扩大敏感凭证保存范围。
`args.stream`	string	是	--	上传飞书项目必填，待上传的文件类型需求：feishu_project_stories 缺陷：feishu_project_issues
`args.project_keys`	string	是	--	上传飞书项目必填，所属空间
`args.user_key`	string	是	--	上传飞书项目必填，飞书项目用户 ID，获取方式见上传飞书项目
`args.branch`	string	否	--	上传代码仓库，默认使用默认分支指定导入分支，例如 `main`
`args.ref`	string	否	--	上传代码仓库 `branch` 的别名；同时提供时 `branch` 优先
`args.commit`	string	否	--	上传代码仓库固定到指定 Commit，优先级高于分支
`args.auth_config`	string	否	--	上传代码仓库私有 HTTPS 仓库认证配置
`args.auth_config.username`	string	否	--	上传代码仓库，默认`oauth2` HTTPS Basic Auth 用户名
`args.auth_config.token`	string	是	--	上传私有代码仓库必填，获取方式见上传代码仓库 Git PAT 或 Deploy Token
`args.parse_mode`	string	否	--	上传代码仓库，默认`default` 通用解析模式，代码仓库通常保持默认
`args.cloud_id`	string	是	--	上传Confluence文档必填源 Confluence 站点的 Cloud ID。可以在浏览器打开网址，查找该参数。同一个站点可以复用，不需要每次导入都获取。
`args.resources[].type`	string	是	--	上传Confluence文档必填支持 page、folder、space。
`args.resources[].id`	string	是	--	上传Confluence文档必填从 Confluence 链接中获取：页面填 `/pages/` 后的数字，文件夹填 `/folder/` 后的数字，整空间填 `/spaces/` 后的 space key，`type` 分别填 `page`、`folder`、`space`，所有 `id` 都按字符串传入
`args.auth_config.email`	string	是	--	上传Confluence文档必填源 Atlassian 账号邮箱。
`args.auth_config.api_token`	string	是	--	上传Confluence文档必填该账号的 Confluence API token。
`args.auth_config.api_token_scope`	string	否	scoped	上传Confluence文档若非 scoped API token 使用 unscoped。

注意事项：

--to、--parent、--parent-auto-create 只能选择一个。
branch 和 commit 建议二选一；同时提供时 commit 优先。
公共仓库不需要配置 auth_config。
Token 必须放在 args.auth_config 中，不能直接写成 args.token。
Token 认证只支持 HTTPS 仓库；SSH 仓库依赖 OpenViking 服务运行环境中的 SSH Key。
--include 是文件白名单，不确定文件类型时建议省略。
代码仓库默认跳过隐藏文件、二进制文件、空文件、大文件以及 .gitignore 忽略的内容。

响应消息

字段	参数说明
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` 时返回）
task_id	异步任务 ID，当请求参数 `wait=false` 时返回，用于后续查询飞书文档导入任务状态。

常见错误码：

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"
    }
}

示例三：UAT模式上传飞书文档

通过 feishu_access_token 以用户身份读取飞书文档，并导入到 OpenViking 数据库。

curl -X POST \
  "$OPENVIKING_DATA_HOST/api/v1/resources" \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "https://example.feishu.cn/docx/<DOCX_TOKEN>",
    "to": "viking://resources/example",
    "reason": "Import Feishu resource",
    "wait": false,
    "args": {
      "feishu_access_token": "<UAT>"
    }
  }'

执行成功返回：

{
  "task_id": "<TASK_ID>"
}

随后可通过任务查询接口查看导入结果：

curl \
  "$OPENVIKING_DATA_HOST/api/v1/tasks/<TASK_ID>" \
  -H "Authorization: Bearer {api_key}"

如需在请求中同步等待导入完成，可将 wait 设置为 true。执行成功返回：

{
  "status": "ok",
  "result": {
    "status": "success",
    "root_uri": "viking://resources/feishu-doc-sync-demo",
    "errors": []
  }
}

如果需要持续同步用户私有飞书文档，可以传入 feishu_refresh_token，并配置 watch_interval。

{
  "path": "https://example.feishu.cn/wiki/<NODE_TOKEN>",
  "to": "viking://resources/example",
  "watch_interval": 30,
  "args": {
    "feishu_access_token": "<UAT>",
    "feishu_refresh_token": "<REFRESH_TOKEN>"
  }
}

参数、示例与排错补充

可选参数缺少默认行为：preserve_structure 不传时默认为 false，导入结果不保留本地目录层级；需要保留时显式传 true。
返回参数描述不完整：返回结构采用统一包装：status 为 string，result 为 object/array/null，telemetry 为 object/null，error 为 object/null；业务子字段的类型和层级与成功示例保持一致。
请求示例与请求参数说明不符：path 为 string、条件必填，表示服务端可访问的源路径；它与 temp_file_id 必须且只能提供一个。
依赖或互斥参数说明不全：temp_file_id 与 path 为二选一来源参数：必须提供一个且不能同时提供。
错误码原因或处理建议缺失：错误处理建议：UNAUTHENTICATED：检查并重新生成 API Key；PERMISSION_DENIED：确认 Agent/账号对目标 URI 有权限；INVALID_ARGUMENT：按参数表检查类型、范围和必填项；NOT_FOUND：确认 URI 或资源 ID 存在；INTERNAL：记录 request ID 后重试，持续失败时提交工单。

最近更新时间：2026.10.26 15:37:23

这个页面对您有帮助吗？

有用

无用

向量数据库VikingDB

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

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

示例三：UAT模式上传飞书文档 #

参数、示例与排错补充 #

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

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

示例三：UAT模式上传飞书文档

参数、示例与排错补充