跳转到主要内容

​
检索 API（Retrieve API）

​
POST /v1/users/:user_id/streams/:stream_id/retrieve

对单个用户和流执行混合检索（Hybrid Retrieval）。

​
此路由的用途

这是运行时的主要召回路由。它融合多种检索信号，而非依赖单一搜索路径。 可用信号包括：
  • 语义相似度（Semantic Similarity）
  • 文本检索（Text Retrieval）
  • 图扩展（Graph Expansion）
  • 时间过滤（Time Filtering）
  • 组织知识（Organization Knowledge）
  • 多模态查询输入（Multimodal Query Input）

​
请求

POST /v1/users/dylan/streams/11111111-1111-1111-1111-111111111111/retrieve
Authorization: Bearer <token>
Content-Type: application/json

{
  "org_id": "default",
  "agent_id": "coding-assistant",
  "query": "What does Dylan prefer for systems work?",
  "limit": 10,
  "enable_arbitration": false,
  "min_score": 0.2,
  "graph_depth": 1,
  "start_time": "2026-03-01T00:00:00Z",
  "end_time": "2026-03-31T23:59:59Z",
  "as_of": "2026-03-25T12:00:00Z"
}

​
请求字段

FieldTypeRequired描述
querystringYes检索查询文本
limitnumberNo最大结果数，服务端有上限
enable_arbitrationbooleanNo启用仲裁检索模式
min_scorenumberNo最低分数阈值
graph_depthnumberNo图扩展深度
start_timeISO8601No有效时间下界
end_timeISO8601No有效时间上界
as_ofISO8601No事务时间时间点过滤
org_idstringNo包含组织知识范围
agent_idstringNo过滤至某个 Agent 的程序性记忆
imagestringNoBase64 图像，用于跨模态检索
audiostringNoBase64 音频，用于跨模态检索
videostringNoBase64 视频，用于跨模态检索

​
响应

{
  "stream_id": "11111111-1111-1111-1111-111111111111",
  "query": "What does Dylan prefer for systems work?",
  "results": [
    {
      "unit": {
        "id": "9db1d859-0a32-4c33-8b94-8cab9f8e0d16",
        "memory_type": "Fact",
        "content": "Dylan prefers Rust for systems work.",
        "keywords": ["rust", "systems"],
        "level": 1
      },
      "score": 0.94
    }
  ],
  "query_time_ms": 8
}

​
响应字段

Field含义
stream_id本次检索请求使用的流
query最终被嵌入和搜索的文本查询
results[].unit匹配的记忆单元视图
results[].score检索融合后的最终排名分数
query_time_ms服务端检索延迟

​
实用说明

  • 即使是多模态检索，查询文本也始终是必需的。
  • 当提供 org_id 时，共享的组织知识可以进入结果集。
  • graph_depth 允许检索通过图链接的邻居进行扩展，而不仅限于直接匹配。
  • agent_id 在你希望偏向某个 Agent 的程序性记忆时非常有用。

​
相关页面