概述

/api/v1/search/search 接口用于执行带会话上下文和意图分析的搜索，支持文本和图片查询。
与 find 相比，search 可以结合指定 session_id 对 Query 进行上下文增强，更适合对话式检索和复杂任务搜索。图片查询会跳过会话 query planning，直接执行图片检索。
search 提供两种响应模式：list 返回分组命中列表；context 在检索后选择内容详略、控制上下文预算，返回可供 Agent 使用的上下文文本。默认使用 list。
list 模式传入有效会话，并且服务端启用了意图分析时，会结合会话摘要与近期消息规划查询。没有可用会话上下文时，使用原始查询。携带图片时使用图文查询路径，不进行 list 模式的会话意图扩展。指定 session_id 不等于自动读取任意历史对话。

前置条件

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

请求接口

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

请求参数

参数	类型	必填／默认值	说明
mode	string	否，list	list 或 context。改变响应结构，调用方须按模式解析。
session	string	否	使用 context 模式时，传入 session 以标识当前检索的上文所在的会话。
query	string	否，空字符串	查询文本。通常与 image_url 至少提供一个；纯过滤查询例外，见下文。
image_url	string	否	查询图片。支持 HTTP(S) URL、可访问的 viking:// 图片 URI、data:image/... Base64 数据。HTTP 不接收调用方本地文件路径。
target_uri	string 或 string[]	否，空字符串	一个目录 URI，或多个目录组成的数组。省略时使用当前身份的默认检索范围；空字符串和 viking:// 不表示跨 User 或跨数据空间。
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。

下表字段只能在 mode="context" 时传入；在 list 中显式传入其中任一字段，包括默认值，也会校验失败。

参数	类型／默认值	说明
query_expansion	string，auto	off 或 auto。auto 在存在可用会话且服务端启用意图分析时扩展查询，否则使用原始查询。
max_tokens	integer，1600	上下文的估算 token 预算，范围 64～32000；用于裁剪内容，不是各模型 tokenizer 的精确额度承诺。
purpose	string，不指定	chat 或 coding，使用对应分类配额。
quotas	object，不指定	自定义分类配额。提供后整体覆盖 purpose 配额，未列出的分类不分配名额。各值建议使用非负整数。
detail	string 或 object，不指定	auto、abstract、overview、full；也可按类别指定 abstract/overview/full。未指定时采用默认策略；预算不足或内容不可读时可降级，甚至只保留 URI。
dedup_turns	integer，0	0～100。大于 0 且提供有效 session_id 时，记录已提供的上下文并在后续调用中暂时排除，避免连续重复。
exclude_uris	string[]，[]	最多 200 个精确 URI。按命中 URI 或去除摘要／概览后缀后的节点 URI 排除，不是目录前缀排除规则。
peer_scope	string，all	actor 或 all。actor 不额外扩展到其他 Peer；all 可补充同一 User 下其他 Peer 的记忆，仍受账号/User及资源权限边界约束。
other_peer_penalty	number 或 object，不指定	其他 Peer 记忆的排序扣分，可统一设置或按分类设置。当前值被限制在 0～1；不会授予额外权限。
rewrite	boolean 或 string，false	false、true 或 auto。true 请求模型整理召回文本；auto 由服务端配置决定。可能增加模型调用和延迟。
rewrite_max_bullets	integer，6	整理后的要点数量上限，范围 1～20。

返回参数

字段	说明
result.query_plan.reasoning	查询规划的解释文本。
result.query_plan.queries	规划后的查询数组，每项包含 query、context_type、intent、priority。不是 expanded_queries。
result.provenance	开启 include_provenance 且生成过程数据时提供的分查询记录；包含 query、matched_contexts、thinking_trace 等信息。结构可能较大，不建议直接拼接给最终用户。

context 模式返回以下字段，不返回 list 的三个分类数组或 total：

字段	类型	说明
result.entries	object[]	选入上下文的条目。
entries[].uri	string	内容来源 URI。
entries[].category	string	events、entities、preferences、experiences、resources、skills 或 memories。
entries[].score	number	原始相关性分数。
entries[].detail	string	实际采用的详略：abstract、overview、full 或 uri。
entries[].text	string	实际提供的文本。
entries[].origin	string	若提供，表示 actor_peer、self 或 other_peer。
result.rendered	string	组装后可用于 Agent 上下文的文本。
result.digest	string	开启 rewrite 后生成的精简文本；未改写或未生成有效内容时可为空。它不是内容哈希。
result.stats	object	候选、预算、查询扩展、去重、降级及改写等统计信息；字段按实际执行路径提供。

常见错误码

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

示例三：图片搜索

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": "similar poster",
    "image_url": "data:image/png;base64,...",
    "limit": 10
  }'

参数、示例与排错补充

请求参数描述不完整或有歧义：请求头必填性：Authorization 必填；Content-Type 在带 JSON 请求体时必填；X-OpenViking-Agent 在 Agent 隔离模式下必填。
数值边界限制缺失：limit 取值范围为 [1, 100]。
数值边界限制缺失：node_limit 取值范围为 [1, 100]；传入时覆盖 limit。
数值边界限制缺失：score_threshold 取值范围为 [0.0, 1.0]。
时间型参数格式不明：since 支持相对时间 30m/2h/7d 或绝对日期 YYYY-MM-DD，绝对日期按 UTC 解释。
时间型参数格式不明：until 支持相对时间 30m/2h/7d 或绝对日期 YYYY-MM-DD，绝对日期按 UTC 解释。
返回参数描述不完整：返回结构采用统一包装：status 为 string，result 为 object/array/null，telemetry 为 object/null，error 为 object/null；业务子字段的类型和层级与成功示例保持一致。
标识型参数缺少获取规则：会话 id/session_id 从创建会话接口的 result.id（或记忆库 AddSession 返回值）取得，也可由列出会话接口查询；不要把示例 ID 用于生产请求。
返回示例与返回参数说明不符：返回结构采用统一包装：status 为 string，result 为 object/array/null，telemetry 为 object/null，error 为 object/null；业务子字段的类型和层级与成功示例保持一致。
错误码原因或处理建议缺失：错误处理建议：UNAUTHENTICATED：检查并重新生成 API Key；PERMISSION_DENIED：确认 Agent/账号对目标 URI 有权限；INVALID_ARGUMENT：按参数表检查类型、范围和必填项；NOT_FOUND：确认 URI 或资源 ID 存在；INTERNAL：记录 request ID 后重试，持续失败时提交工单。

最近更新时间：2026.09.22 22:12:21

这个页面对您有帮助吗？

有用

无用

向量数据库VikingDB

概述 #

前置条件 #

请求接口 #

请求参数 #

返回参数 #

常见错误码 #

完整示例 #

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

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

示例三：图片搜索 #

参数、示例与排错补充 #

概述