初始化
This commit is contained in:
1 parent
34474bd5fc
commit
b638b541d0
3008 files changed
+837699
No files matched your search
@@ -0,0 +1,126 @@
|
||||
# Hindsight 记忆后端接入指南
|
||||
|
||||
> Memory V2 的外部 provider。详见 `docs/MEMORY_V2_DESIGN_ZH.md`。
|
||||
|
||||
Hindsight 是带知识图谱、实体消解、多策略检索的长期记忆服务。DeerFlow 以 HTTP
|
||||
客户端方式接入一个**你自己部署**的 Hindsight Docker 实例(`local_external` 模式)。
|
||||
|
||||
DeerFlow 不负责 Hindsight 的部署与运维 —— 它只是一个 HTTP 客户端。Hindsight 不可达
|
||||
或未配置时,记忆系统自动退回纯 builtin 本地记忆,不影响任何功能。
|
||||
|
||||
---
|
||||
|
||||
## 1. 部署 Hindsight Docker
|
||||
|
||||
Hindsight 的官方镜像与部署方式请以 Hindsight 官方文档为准。典型的本地部署:
|
||||
|
||||
```bash
|
||||
# 下面的 8765 只是占位示例。端口随你的 Hindsight 实例实际暴露的来,
|
||||
# 例如映射成 9999、8888 等都行 —— deerflow 只认 config.yaml 里的 api_url。
|
||||
docker run -d \
|
||||
--name hindsight \
|
||||
-p <宿主端口>:<容器端口> \
|
||||
-v hindsight-data:/data \
|
||||
<hindsight-镜像>
|
||||
|
||||
# 确认服务可达 (端口换成你实际暴露的)
|
||||
curl http://localhost:<宿主端口>/health
|
||||
```
|
||||
|
||||
数据卷 `hindsight-data` 用于持久化记忆库,容器重建时不丢数据。
|
||||
|
||||
> **端口说明**:deerflow 是纯 HTTP 客户端,只需要把 `api_url` 指向 Hindsight 的
|
||||
> **HTTP API 端口**即可。如果你的实例同时暴露了多个端口 (例如 API 与 Web UI 各一个),
|
||||
> `api_url` 填 HTTP API 那个;Web UI 端口 deerflow 不需要。
|
||||
|
||||
---
|
||||
|
||||
## 2. 安装客户端依赖
|
||||
|
||||
DeerFlow 侧需要 `hindsight-client` Python 包(可选依赖,默认不装):
|
||||
|
||||
```bash
|
||||
cd offline-backend-20260512/backend
|
||||
uv pip install 'hindsight-client>=0.4.22'
|
||||
# 或安装 harness 的 hindsight extra:
|
||||
uv pip install -e 'packages/harness[hindsight]'
|
||||
```
|
||||
|
||||
未安装时 `HindsightProvider.is_available()` 返回 `False`,provider 不会被注册。
|
||||
|
||||
---
|
||||
|
||||
## 3. 配置 config.yaml
|
||||
|
||||
在项目根 `config.yaml` 的 `memory` 段:
|
||||
|
||||
```yaml
|
||||
memory:
|
||||
enabled: true
|
||||
provider: hindsight # 启用 Hindsight 外部 provider
|
||||
hindsight:
|
||||
mode: local_external
|
||||
api_url: http://localhost:8765 # 换成你实例实际暴露的 HTTP API 端口
|
||||
api_key: $HINDSIGHT_API_KEY # 如果你的实例需要鉴权
|
||||
bank_id_template: "deerflow-user-{user_id}"
|
||||
work_bank_id_template: "deerflow-work-{user_id}-{agent_id}"
|
||||
memory_mode: context # context / tools / hybrid
|
||||
recall_budget: mid # low / mid / high
|
||||
auto_recall: true
|
||||
auto_retain: true
|
||||
retain_async: true
|
||||
```
|
||||
|
||||
`api_key` 以 `$` 开头时按环境变量解析。把密钥放进 `.env`:
|
||||
|
||||
```
|
||||
HINDSIGHT_API_KEY=your-key
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 双 bank 隔离
|
||||
|
||||
Memory V2 用两个 bank 隔离记忆(B 方案):
|
||||
|
||||
| Bank | 模板 | 内容 |
|
||||
|---|---|---|
|
||||
| 全局 user bank | `deerflow-user-{user_id}` | 用户身份、偏好,跨 agent 共享 |
|
||||
| agent 工作 bank | `deerflow-work-{user_id}-{agent_id}` | agent 私有工作笔记 |
|
||||
|
||||
- LLM 调 `memory(target="user")` → 镜像到 user bank
|
||||
- LLM 调 `memory(target="memory")` → 镜像到 work bank
|
||||
- 自动 retain 的对话 → work bank
|
||||
- 召回时并发查两个 bank 并合并
|
||||
|
||||
模板占位符:`{user_id}` / `{agent_id}` / `{thread_id}`。
|
||||
|
||||
---
|
||||
|
||||
## 5. memory_mode 三种模式
|
||||
|
||||
| 模式 | 自动召回 | 自动写入 | 暴露工具给 LLM |
|
||||
|---|---|---|---|
|
||||
| `context` | ✅ | ✅ | ❌ LLM 看不到 Hindsight |
|
||||
| `tools` | ❌ | ❌ | ✅ `hindsight_recall` / `reflect` / `retain` |
|
||||
| `hybrid` | ✅ | ✅ | ✅ 自动 + 工具齐发 |
|
||||
|
||||
`tools` / `hybrid` 模式下,`get_available_tools` 会额外暴露 3 个 Hindsight 工具。
|
||||
|
||||
---
|
||||
|
||||
## 6. 迁移旧记忆到 Hindsight
|
||||
|
||||
P1 的迁移脚本 `scripts/migrate_memory_to_v2.py` 只迁移本地 USER.md / MEMORY.md。
|
||||
把这些记忆灌进 Hindsight bank 的步骤将在后续提供。
|
||||
|
||||
---
|
||||
|
||||
## 7. 排查
|
||||
|
||||
| 现象 | 检查 |
|
||||
|---|---|
|
||||
| 记忆没召回 | `curl api_url/health`;`memory.provider` 是否为 `hindsight`;`injection.include_hindsight` |
|
||||
| 启动日志报 "Hindsight provider 已配置但不可用" | `hindsight-client` 是否安装;`api_url` 是否配置 |
|
||||
| LLM 看不到 Hindsight 工具 | `memory_mode` 是否为 `tools` 或 `hybrid` |
|
||||
| 写入慢 | 确认 `retain_async: true` |
|
||||
Reference in new issue
Block a user