146 lines
5.2 KiB
Markdown
146 lines
5.2 KiB
Markdown
# Memory Search 上游参数增量兼容设计
|
||
|
||
## 目标
|
||
|
||
扩展 Memory Gateway 的 `POST /memories/search`，在保留现有用户鉴权、
|
||
`scope` 搜索编排、资源隔离、软删除和覆盖修改能力的前提下，支持上游
|
||
搜索接口的全部请求选项。
|
||
|
||
本次只修改 `/memories/search`，不新增 `/memories/get`，也不提供上游路径的
|
||
线协议兼容接口。
|
||
|
||
## 请求模型
|
||
|
||
保留现有字段：
|
||
|
||
- `user_id`：必填，始终用于 Gateway 用户鉴权和本地数据隔离。
|
||
- `user_key`：必填，用于 Gateway 用户鉴权。
|
||
- `conversation_id`：可选，供 `current_chat` scope 生成 session 过滤条件。
|
||
- `query`：必填。
|
||
- `scope`：保留 `current_chat`、`resources`、`all_user_memory`。
|
||
- `app_id`、`project_id`：默认 `default`。
|
||
|
||
新增或扩展字段：
|
||
|
||
- `agent_id`：可选。存在时，上游搜索使用 `agent_id`；不存在时使用
|
||
Gateway 鉴权用户的 `user_id`。请求中不会同时向上游发送两种 owner ID。
|
||
- `method`：支持 `keyword`、`vector`、`hybrid`、`agentic`，默认 `hybrid`。
|
||
- `top_k`：支持 `-1` 或 `1..100`，保留 Gateway 默认值 `8`。
|
||
- `radius`：可选，范围 `0..1`。
|
||
- `include_profile`：布尔值，默认 `true`。
|
||
- `enable_llm_rerank`：布尔值，默认 `true`。
|
||
- `filters`：可选对象，支持上游开放字段过滤 DSL，包括嵌套 `AND`、`OR`。
|
||
|
||
`agent_id` 只改变上游记忆 owner，不替代 Gateway 的 `user_id/user_key` 鉴权。
|
||
这可以防止调用者绕过 Gateway 用户体系，同时允许同一已认证用户查询被授权
|
||
使用的 agent memory。当前版本不新增 agent 权限表，因此仅校验 Gateway 用户
|
||
凭据，不声明 agent 的独立所有权关系。
|
||
|
||
## 搜索编排与过滤器合并
|
||
|
||
每一次上游 search 调用都必须透传：
|
||
|
||
- owner：`agent_id` 或 `user_id`，二选一；
|
||
- `query`；
|
||
- `method`；
|
||
- `top_k`；
|
||
- `radius`，仅在请求提供时发送；
|
||
- `include_profile`；
|
||
- `enable_llm_rerank`；
|
||
- `app_id`；
|
||
- `project_id`；
|
||
- 合并后的 `filters`。
|
||
|
||
现有 scope 继续生成内部 session 条件：
|
||
|
||
- `current_chat`：`session_id = chat:{conversation_id}`；
|
||
- `resources`：按批次生成 `session_id in [...]`；
|
||
- `all_user_memory`：不生成 session 条件。
|
||
|
||
当请求同时提供自定义 `filters` 和 scope session 条件时，使用以下结构合并：
|
||
|
||
```json
|
||
{
|
||
"AND": [
|
||
{"自定义过滤条件": "..."},
|
||
{"session_id": "scope 生成的条件"}
|
||
]
|
||
}
|
||
```
|
||
|
||
仅存在其中一个条件时直接使用该条件；两者都不存在时不发送 `filters`。
|
||
Gateway 不解析或重写自定义过滤 DSL 的内部字段，由上游执行完整校验。
|
||
|
||
`agent_id` 与所有 scope 均可组合。对于没有对应数据的组合，上游自然返回空数组；
|
||
Gateway 不额外禁止这些组合，以保持接口简单并完整透传搜索能力。
|
||
|
||
## 响应标准化
|
||
|
||
继续返回 Gateway 的统一结构：
|
||
|
||
```json
|
||
{
|
||
"results": []
|
||
}
|
||
```
|
||
|
||
每个结果新增 `memory_type`：
|
||
|
||
| 上游数组 | `memory_type` |
|
||
|---|---|
|
||
| `episodes` | `episode` |
|
||
| `profiles` | `profile` |
|
||
| `agent_cases` | `agent_case` |
|
||
| `agent_skills` | `agent_skill` |
|
||
| `unprocessed_messages` | `unprocessed_message` |
|
||
|
||
其余字段保持现状：`id`、`session_id`、`text`、`score`、`source_scope`、
|
||
`resource_id`、`resource_uri` 和 `raw`。
|
||
|
||
profile 和 agent skill 等没有 `session_id` 的结果允许返回 `null`。资源映射只对
|
||
能匹配当前用户资源 session 的结果生效，不泄露其他用户的内部资源 URI。
|
||
|
||
所有类型的结果继续按现有顺序执行：
|
||
|
||
1. 合并各 scope 的结果；
|
||
2. 应用当前用户的 memory tombstone；
|
||
3. 按 memory ID 应用当前用户的 active override；
|
||
4. 返回统一结果。
|
||
|
||
## 错误处理
|
||
|
||
- 不合法的 `method`、`top_k` 或 `radius` 由 Gateway 请求模型返回 HTTP 422。
|
||
- 上游过滤 DSL 错误和其他 HTTP 错误继续由现有 client 行为向外传播。
|
||
- 不改变当前 `current_chat` 缺少 `conversation_id` 时跳过该 scope 的行为。
|
||
- 不为 `agent_id` 引入新的数据库表或权限模型。
|
||
|
||
## 代码改动
|
||
|
||
- `core/api.py`
|
||
- 扩展 `SearchMemoriesRequest`。
|
||
- 将新增参数传给 service。
|
||
- `core/service.py`
|
||
- 扩展 `search_memories` 和 `_search_payload`。
|
||
- 合并自定义 filters 与 scope filters。
|
||
- 标准化结果时增加 `memory_type`。
|
||
- `tests/test_gateway.py`
|
||
- 验证默认参数透传。
|
||
- 验证全部自定义搜索选项透传。
|
||
- 验证 agent owner 与用户鉴权身份分离。
|
||
- 验证 filters 与 scope 条件使用 `AND` 合并。
|
||
- 验证五类结果的 `memory_type`。
|
||
- `README.md`
|
||
- 更新 `/memories/search` 参数和响应说明。
|
||
|
||
## 验收标准
|
||
|
||
1. 未提供新字段时，上游收到 `method=hybrid`、`include_profile=true`、
|
||
`enable_llm_rerank=true`。
|
||
2. 所有上游搜索选项均能通过 Gateway 请求并原样传递。
|
||
3. `top_k=-1` 被接受，`top_k=0` 和范围外值被拒绝。
|
||
4. 自定义 filters 不会覆盖 scope 的资源或聊天 session 隔离条件。
|
||
5. 设置 `agent_id` 后，上游只收到 `agent_id`，Gateway 仍使用
|
||
`user_id/user_key` 完成鉴权。
|
||
6. 每个搜索结果包含准确的 `memory_type`。
|
||
7. 现有 tombstone、override、资源 URI 隔离测试继续通过。
|