概述

按自然语言查询对已安装 Skill 做语义搜索。未指定 target_uri 时，接口会并行搜索当前用户私有根和账户共享根，将结果合并并按 score 降序排列。
范围说明。limit 是每个作用域的搜索上限；未传 target_uri 时两个作用域各执行一次搜索，合并后的 total 最多可能达到 2 × limit，当前实现不会在合并后再次裁剪。

请求接口

URI	`/api/v1/skills/find`
请求方法	POST
Content-Type	`application/json`
认证	`Authorization: Bearer {API_KEY}`

请求参数

参数	类型	必选	默认值	说明
`query`	string	是	—	自然语言查询文本。
`limit`	integer	否	10	每个目标作用域最多返回的命中数。
`score_threshold`	float	否	null	最低相似度阈值，低于阈值的命中不返回。
`level`	array	否	null	限定参与检索的语义层级，例如 `[0, 1]`。
`telemetry`	bool / object	否	false	true 或 `{"summary": true}` 时返回调用统计摘要。
`target_uri`	string	否	null	限定单一检索根；不传时并行搜索用户私有根和账户共享根。

响应消息

字段	类型	说明
`result.root_uris`	array	未传 target_uri 时返回的两个检索根。
`result.root_uri`	string	传入 target_uri 时返回的单一检索根。
`result.skills`	array	Skill 命中列表。
`result.total`	integer	合并后的实际命中数。
`result.skills[].name`	string	Skill 名称。
`result.skills[].uri`	string	Skill 目录 URI。
`result.skills[].description`	string	Skill 描述。
`result.skills[].score`	float	语义相似度得分。
`result.skills[].match_reason`	string	命中原因或匹配说明。
`result.skills[].level`	integer	命中的语义层级。
`result.skills[].abstract`	string	命中的摘要文本。

完整示例

curl -X POST "{BASE_URL}/api/v1/skills/find" \
  -H "Authorization: Bearer {API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "搜索互联网并汇总最新资料",
    "limit": 5,
    "score_threshold": 0.3,
    "level": [0, 1]
  }'

{
  "status": "ok",
  "result": {
    "root_uris": [
      "viking://user/alice/skills",
      "viking://agent/skills"
    ],
    "skills": [
      {
        "type": "skill",
        "name": "search-web",
        "uri": "viking://user/alice/skills/search-web",
        "root_uri": "viking://user/alice/skills/search-web",
        "skill_md_uri": "viking://user/alice/skills/search-web/SKILL.md",
        "description": "搜索互联网中的最新信息",
        "tags": ["search"],
        "allowed_tools": ["web"],
        "score": 0.86,
        "match_reason": "语义与搜索、最新资料高度相关",
        "level": 0,
        "abstract": "name: search-web\ndescription: 搜索互联网中的最新信息"
      }
    ],
    "total": 1
  }
}

最近更新时间：2026.07.22 18:07:44

这个页面对您有帮助吗？

有用

无用

向量数据库VikingDB

概述 #

请求接口 #

请求参数 #

响应消息 #

完整示例 #

概述

请求接口

请求参数

响应消息

完整示例