search-上下文感知搜索--向量数据库VikingDB-火山引擎

文档中心

向量数据库VikingDB

请输入

检索（Retrival）

search-上下文感知搜索

概述

/api/v1/search/search 接口用于执行带会话上下文和意图分析的搜索。
与 find 相比，search 可以结合指定 session_id 对 Query 进行上下文增强，更适合对话式检索和复杂任务搜索。

前置条件

完成 API 鉴权说明页面的 API Key 获取后，可调用本接口发起上下文感知搜索。如需结合会话上下文，请确保目标会话已存在。

请求接口

URI

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

请求方法

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

请求头

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

请求参数

参数	类型	必选	默认值	备注
query	string	是	--	搜索查询字符串
target_uri	string	否	`""`	将搜索范围限制在指定 URI 前缀下
session_id	string	否	--	会话 ID，用于上下文感知搜索
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.query_plan	查询计划与扩展查询信息
result.total	总结果数
result.*[].uri	命中上下文的 URI
result.*[].abstract	L0 摘要
result.*[].score	相关性分数
telemetry	调用统计信息，仅当 `telemetry=true` 时返回
error	失败时返回的错误对象
error.code	错误码字符串
error.message	可读的错误描述

常见错误码

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

完整示例

示例一：结合会话上下文搜索

curl -X POST `https://xxx/api/v1/search/search` \
  -H "Authorization: Bearer {api_key}" \
  -H "X-OpenViking-Agent: {agent_id}" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "best practices",
    "session_id": "abc123",
    "since": "2h",
    "time_field": "updated_at",
    "limit": 10
  }'

执行成功返回：

{
  "status": "ok",
  "result": {
    "memories": [],
    "resources": [
      {
        "uri": "viking://resources/docs/oauth-best-practices/",
        "context_type": "resource",
        "is_leaf": false,
        "abstract": "OAuth 2.0 best practices for login pages...",
        "score": 0.95,
        "match_reason": "Context-aware match: OAuth login best practices"
      }
    ],
    "skills": [],
    "query_plan": {
      "expanded_queries": [
        "OAuth 2.0 best practices",
        "login page security"
      ]
    },
    "total": 1
  }
}

示例二：不传会话，仅做增强搜索

curl -X POST `https://xxx/api/v1/search/search` \
  -H "Authorization: Bearer {api_key}" \
  -H "X-OpenViking-Agent: {agent_id}" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "how to implement OAuth 2.0 authorization code flow"
  }'

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

这个页面对您有帮助吗？

有用

无用

向量数据库VikingDB

概述 #

前置条件 #

请求接口 #

URI #

请求方法 #

请求头 #

请求参数 #

响应消息 #

常见错误码 #

完整示例 #

示例一：结合会话上下文搜索 #

示例二：不传会话，仅做增强搜索 #

概述