find-语义搜索--向量数据库VikingDB-火山引擎

文档中心

向量数据库VikingDB

请输入

检索（Retrival）

find-语义搜索

概述

/api/v1/search/find 接口用于执行基础语义搜索。
该接口不依赖会话上下文，适合在资源、记忆或技能范围内，根据 Query 直接召回最相关的上下文结果。

前置条件

完成 API 鉴权说明页面的 API Key 获取后，可调用本接口发起语义搜索。

请求接口

URI

/api/v1/search/find
统一资源标识符。

请求方法

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

请求头

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

请求参数

参数	类型	必选	默认值	备注
query	string	是	--	搜索查询字符串
target_uri	string	否	`""`	将搜索范围限制在指定 URI 前缀下
limit	int	否	10	最大返回结果数
node_limit	int	否	--	`limit` 的 HTTP 别名，若传入则覆盖 `limit`
score_threshold	float	否	--	最低相关性分数阈值
filter	object	否	--	元数据过滤条件
since	string	否	--	时间下界，如 `2h` 或 `2026-03-15`
until	string	否	--	时间上界，如 `30m` 或 `2026-03-20`
time_field	string	否	`updated_at`	时间过滤所使用的字段，可选 `updated_at` 或 `created_at`
include_provenance	bool	否	false	是否返回 provenance / query-plan 细节
telemetry	bool / object	否	false	是否返回调用统计信息

响应消息

字段	参数说明
status	请求状态，成功为 `"ok"`，失败为 `"error"`
result	成功时返回的数据对象
result.memories	命中的记忆结果列表
result.resources	命中的资源结果列表
result.skills	命中的技能结果列表
result.total	总结果数
result.*[].uri	命中上下文的 URI
result.*[].context_type	上下文类型
result.*[].is_leaf	是否为叶子节点
result.*[].abstract	L0 摘要
result.*[].score	相关性分数
result.*[].match_reason	匹配原因
telemetry	调用统计信息，仅当 `telemetry=true` 时返回
error	失败时返回的错误对象
error.code	错误码字符串
error.message	可读的错误描述

常见错误码

error.code	说明
UNAUTHENTICATED	缺少 API Key 或 API Key 无效
PERMISSION_DENIED	API Key 权限不足
INVALID_ARGUMENT	查询参数非法，例如时间过滤格式错误

完整示例

示例一：执行基础语义搜索

curl -X POST `https://xxx/api/v1/search/find` \
  -H "Authorization: Bearer {api_key}" \
  -H "X-OpenViking-Agent: {agent_id}" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "how to authenticate users",
    "limit": 10
  }'

执行成功返回：

{
  "status": "ok",
  "result": {
    "memories": [],
    "resources": [
      {
        "uri": "viking://resources/docs/auth/",
        "context_type": "resource",
        "is_leaf": false,
        "abstract": "Authentication guide covering OAuth 2.0...",
        "score": 0.92,
        "match_reason": "Semantic match on authentication"
      }
    ],
    "skills": [],
    "total": 1
  }
}

示例二：限定搜索范围并设置分数阈值

curl -X POST `https://xxx/api/v1/search/find` \
  -H "Authorization: Bearer {api_key}" \
  -H "X-OpenViking-Agent: {agent_id}" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "API endpoints",
    "target_uri": "viking://resources/my-project/",
    "score_threshold": 0.5,
    "limit": 5
  }'

最近更新时间：2026.05.26 11:19:26

这个页面对您有帮助吗？

有用

无用

向量数据库VikingDB

概述 #

前置条件 #

请求接口 #

URI #

请求方法 #

请求头 #

请求参数 #

响应消息 #

常见错误码 #

完整示例 #

示例一：执行基础语义搜索 #

示例二：限定搜索范围并设置分数阈值 #

概述