You need to enable JavaScript to run this app.
文档中心
向量数据库VikingDB

向量数据库VikingDB

请输入
  • 文档首页
    • 向量数据库VikingDBOpenViking ContextAPI 文档数据库访问检索（Retrieval）find-语义搜索
复制全文
下载 pdf
我的收藏
检索（Retrieval）
find-语义搜索
复制全文
下载 pdf
我的收藏
find-语义搜索

概述

根据查询文本或图片查找相关记忆、资源与技能。适合已能明确描述目标的查询。也支持只提供过滤条件查询索引中的记录，此时不进行语义相似度计算。

前置条件

完成 "数据库访问使用说明" 页面的 API Key 获取后，可调用本接口发起语义搜索。

请求接口

URI

/api/v1/search/find

统一资源标识符

请求方法

POST

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

请求头

Content-Type: application/json

请求消息类型

Authorization: Bearer {api_key}

API Key 鉴权

请求参数

参数

类型

必填／默认值

说明

query

string

否，空字符串

查询文本。通常与 image_url 至少提供一个；纯过滤查询例外，见下文。

image_url

string

否

查询图片。支持 HTTP(S) URL、可访问的 viking:// 图片 URI、data:image/... Base64 数据。HTTP 不接收调用方本地文件路径。

target_uri

string 或 string[]

否，空字符串

一个目录 URI，或多个目录组成的数组。
省略时使用当前身份的默认检索范围。

context_type

string 或 string[]

否

memory、resource、skill。多个值可用数组或逗号分隔字符串，例如 ["memory","resource"]；多个类型取并集。

limit

integer

否，10

本次返回的结果数量上限。建议使用正整数；不应将 0 当成跨模式通用的“无限制”约定。

node_limit

integer

否

limit 的兼容参数。与 limit 同时提供时，以 node_limit 为准；新接入建议只传 limit。

score_threshold

number

否

最低相关性分数；不指定时使用检索器默认行为。分数不代表概率，阈值应结合实际语料和模型调试。

filter

object

否

索引字段过滤表达式。与 context_type、tags、时间条件按 AND 合并。格式示例见下文；可用字段及操作符以存储后端支持为准。

tags

string[]

否

按标签精确过滤，格式为 key=value，例如 ["project=atlas","stage=production"]。多个标签按 AND 匹配。

since

string

否

时间下界，包含边界。支持 ISO 8601、YYYY-MM-DD 或相对时间。

until

string

否

时间上界，包含边界。支持格式同 since。

time_field

string

否，updated_at

时间条件作用的字段：updated_at 或 created_at。
未设置时间上下界时不产生时间过滤。

level

integer、string 或 integer[]

否

检索的内容层级：0 摘要、1 概览、2 详细内容。可传 2、"0,1,2" 或 [1,2]。它控制候选层级，不控制响应正文长度。

read_content

boolean

否，false

为命中项读取正文，成功时增加 content。按调用者权限读取；单条读取失败时仍保留命中项，可能没有 content。

include_provenance

boolean

否，false

请求检索过程信息。当前 find 通常不生成分查询过程记录，设为 true 也不保证返回 provenance。

telemetry

boolean 或 object

否，false

true 或 {"summary":true} 请求运行统计；对象当前只支持 summary。返回于响应顶层 telemetry。

query 为空、没有 image_url 时，必须有有效过滤条件。filter、context_type、tags、since/until 可以构成过滤条件；仅指定 target_uri 或 level 不足以启动纯过滤查询。纯过滤结果的 score 为 0，不适合用相关性阈值筛选，也不承诺按创建或更新时间排序。
标签会统一转为小写并去除整个标签前后的空白；同一个 key 重复出现时保留最后一个值。每个标签须恰好包含一个等号，key 与 value 均不能为空。find/search 对非法标签报参数错误。标签不沿父目录自动继承，只匹配记录自身已建立索引的标签。
相对时间支持整数加单位：s（秒）、m（分钟）、h（小时）、d（天）、w（周）。例如 since="2h"、until="30m" 表示当前时间前两小时至前三十分钟。仅日期的下界为当日 00:00:00，上界为当日 23:59:59.999999，均按 UTC；无时区的 ISO 时间也按 UTC 解释。建议明确写时区，例如 2026-09-20T09:00:00+08:00。下界晚于上界会报错。
filter 示例：{"op":"must","field":"context_type","conds":["resource"]}。复杂条件可写成 {"op":"and","conds":[条件一,条件二]}。优先使用 context_type、tags、since/until 等专用字段，避免依赖后端内部字段。

响应消息

字段

类型

说明

status

string

请求成功时为 ok。

result.memories

object[]

记忆命中项。

result.resources

object[]

资源命中项。

result.skills

object[]

技能命中项。

result.total

integer

三组数组实际返回的条目数之和，不是检索范围内所有匹配记录的总数。

命中项.uri

string

命中内容的 URI，可用于后续读取。

命中项.context_type

string

memory、resource 或 skill。

命中项.level

integer

命中层级：0、1、2。

命中项.score

number

相关性分数；纯过滤查询为 0。

命中项.abstract

string

内容摘要。

命中项.tags

string[]

标签，没有标签时为空数组。

命中项.content

string

read_content=true 且读取成功时提供。

常见错误码

error.code

说明

UNAUTHENTICATED

缺少 API Key 或 API Key 无效

PERMISSION_DENIED

API Key 权限不足

INVALID_ARGUMENT

查询参数非法，例如时间过滤格式错误

完整示例

示例1：文本检索并读取正文 

curl --request POST \
  'https://api.vikingdb.cn-beijing.volces.com/openviking/api/v1/search/find' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {api_key}' \
  --data '{
  "query": "Atlas 项目的发布流程",
  "target_uri": "viking://resources/projects/atlas",
  "context_type": "resource",
  "limit": 5,
  "level": 2,
  "read_content": true
}'

执行成功返回：

{
  "status": "ok",
  "result": {
    "memories": [],
    "resources": [
      {
        "uri": "viking://resources/projects/atlas/release.md",
        "context_type": "resource",
        "level": 2,
        "score": 0.83,
        "abstract": "Atlas 发布检查与回滚步骤。",
        "tags": [
          "project=atlas"
        ],
        "content": "# 发布流程\n\n1. 完成发布前检查。\n2. 分批发布并检查错误率。\n3. 出现异常时恢复上一稳定版本。"
      }
    ],
    "skills": [],
    "total": 1
  }
}

示例2：检索多个目录 

curl --request POST \
  'https://api.vikingdb.cn-beijing.volces.com/openviking/api/v1/search/find' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {api_key}' \
  --data '{
  "query": "发布回滚流程",
  "target_uri": [
    "viking://resources/projects/atlas",
    "viking://resources/runbooks"
  ],
  "limit": 5
}'

{
  "status": "ok",
  "result": {
    "memories": [],
    "resources": [
      {
        "uri": "viking://resources/projects/atlas/release.md",
        "context_type": "resource",
        "level": 2,
        "score": 0.83,
        "abstract": "Atlas 发布检查与回滚步骤。",
        "tags": [
          "project=atlas"
        ]
      },
      {
        "uri": "viking://resources/runbooks/rollback.md",
        "context_type": "resource",
        "level": 2,
        "score": 0.79,
        "abstract": "服务回滚前的检查项和恢复步骤。",
        "tags": [
          "topic=rollback"
        ]
      }
    ],
    "skills": [],
    "total": 2
  }
}

示例3：使用图片检索 

curl --request POST \
  'https://api.vikingdb.cn-beijing.volces.com/openviking/api/v1/search/find' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {api_key}' \
  --data '{
  "image_url": "viking://resources/design/query.png",
  "target_uri": "viking://resources/design",
  "limit": 5
}'

{
  "status": "ok",
  "result": {
    "memories": [],
    "resources": [
      {
        "uri": "viking://resources/design/login-screen.png",
        "context_type": "resource",
        "level": 2,
        "score": 0.88,
        "abstract": "登录页面设计图，包含账号输入框和主登录按钮。",
        "tags": [
          "page=login"
        ]
      }
    ],
    "skills": [],
    "total": 1
  }
}

示例4：组合字段过滤与创建时间 

curl --request POST \
  'https://api.vikingdb.cn-beijing.volces.com/openviking/api/v1/search/find' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {api_key}' \
  --data '{
  "query": "发布流程",
  "target_uri": "viking://resources/projects/atlas",
  "filter": {
    "op": "must",
    "field": "context_type",
    "conds": [
      "resource"
    ]
  },
  "time_field": "created_at",
  "since": "2026-09-01T00:00:00+08:00",
  "until": "2026-09-20T23:59:59+08:00",
  "limit": 5
}'

{
  "status": "ok",
  "result": {
    "memories": [],
    "resources": [
      {
        "uri": "viking://resources/projects/atlas/release.md",
        "context_type": "resource",
        "level": 2,
        "score": 0.83,
        "abstract": "Atlas 发布检查与回滚步骤。",
        "tags": [
          "project=atlas"
        ]
      }
    ],
    "skills": [],
    "total": 1
  }
}

参数、示例与排错补充

  • 数值边界限制缺失：limit 取值范围为 [1, 100]。
  • 可选参数缺少默认行为：score_threshold 不传时不按固定分数阈值裁剪，仍受 limit 等召回参数限制。
  • 可度量参数缺失单位或影响：score_threshold 范围 [0.0,1.0]，值越大表示相关性门槛越高、返回结果通常越少。
  • 数值边界限制缺失：score_threshold 取值范围为 [0.0, 1.0]，值越大，保留结果的相关性要求越高。
  • 时间型参数格式不明：since 支持相对时间（如 30m、2h、7d）或绝对日期 YYYY-MM-DD；绝对日期按 UTC 的当日 00:00:00 解释。
  • 时间型参数格式不明：until 支持相对时间（如 30m、2h、7d）或绝对日期 YYYY-MM-DD；绝对日期按 UTC 的当日结束时间解释。
  • 返回参数描述不完整：返回结构采用统一包装：status 为 string，result 为 object/array/null，telemetry 为 object/null，error 为 object/null；业务子字段的类型和层级与成功示例保持一致。
  • 返回参数描述不完整：返回结构采用统一包装：status 为 string，result 为 object/array/null，telemetry 为 object/null，error 为 object/null；业务子字段的类型和层级与成功示例保持一致。
  • 标识型参数缺少获取规则：agent_id 在 OpenViking 控制台的 Agent 接入页创建或选择 Agent 后复制；请求头 X-OpenViking-Agent 必须传该值，不能使用 Agent 名称代替。
  • 错误码原因或处理建议缺失：错误处理建议：UNAUTHENTICATED：检查并重新生成 API Key；PERMISSION_DENIED：确认 Agent/账号对目标 URI 有权限；INVALID_ARGUMENT：按参数表检查类型、范围和必填项；NOT_FOUND：确认 URI 或资源 ID 存在；INTERNAL：记录 request ID 后重试，持续失败时提交工单。
最近更新时间：2026.09.22 22:12:21
这个页面对您有帮助吗？
有用
有用
无用
无用