为什么选 OpenViking#

OpenViking 干的事：给 Agent 一个统一的、可检索的长期记忆库。

• 记忆、资源、技能统一用 viking:// URI 管理，像操作文件系统一样 ls、find，不是黑盒向量库
• 内容写进去时自动分级处理：L0 摘要（约 100 token）、L1 概览（约 2k token）、L2 全文，按需加载，省 token
• 检索是可观测的，能看它是沿哪条路径找到结果的
• 会话结束后自动从对话里提取偏好和经验写进长期记忆

选择在 NAS 自托管而不是用云服务，就一个理由：数据在自己手里。记忆这种东西我不想放别人服务器上。OpenViking 官方自己也要求 Docker 部署时数据全在挂载目录里，天然适合 NAS。

准备工作#

• fnOS 一台（x86_64），Docker 和 Docker Compose 可用（我这边 Docker 29.7.2 / Compose v5.5.0）
• 用 SSH 登录 NAS（fnOS 的 hy4962 用户在 docker 组，可以直接跑 docker 命令）
• 两个模型服务：
  • Embedding（向量化）：我用 SiliconFlow 的 Qwen/Qwen3-Embedding-4B（原因见下）
  • VLM（内容理解/摘要）：走我自己搭的 new-api 网关（OpenAI 兼容），模型 deepseek-v4-flash

第一步：数据目录#

部署之前先把目录结构定好，这是后面迁移最省心的一步。OpenViking 容器内所有持久状态都在 /app/.openviking 这一个目录下（配置 + workspace 数据全在里面），所以直接把 NAS 上的目录整个挂进去：

1
/vol1/1000/Docker/OpenViking/
2
├── ov.conf            # 配置（模型、存储、root key）
3
├── docker-compose.yml
4
├── data/              # workspace：文件库 + 向量库 + bot
5
└── cache/             # 模型缓存

以后换机器迁移，把这个目录整个拷走就行，数据配置模型一个不落。镜像本体在 Docker 存储里，不占这个目录。

第二步：ov.conf 和 docker-compose#

先写 ov.conf。关键三件事：server.root_api_key（容器内绑定 0.0.0.0 时必须有，否则拒绝启动）、embedding、VLM：

1
{
2
  "server": {
3
    "host": "0.0.0.0",
4
    "port": 1933,
5
    "root_api_key": "换成你自己的随机串",
6
    "cors_origins": ["*"]
7
  },
8
  "embedding": {
9
    "dense": {
10
      "provider": "openai",
11
      "model": "Qwen/Qwen3-Embedding-4B",
12
      "api_base": "https://api.siliconflow.cn/v1",
13
      "api_key": "你的 SiliconFlow key",
14
      "dimension": 2560
15
    }
16
  },
17
  "vlm": {
18
    "provider": "openai",
19
    "model": "deepseek-v4-flash",
20
    "api_base": "http://192.168.31.3:3000/v1",
21
    "api_key": "你的 new-api key"
22
  },
23
  "storage": {
24
    "workspace": "/app/.openviking/data",
25
    "agfs": { "backend": "local" },
26
    "vectordb": { "backend": "local" }
27
  }
28
}

docker-compose.yml 就一行挂载的事：

1
services:
2
  openviking:
3
    image: ghcr.io/volcengine/openviking:latest
4
    container_name: openviking
5
    restart: unless-stopped
6
    ports:
7
      - "1933:1933"
8
    volumes:
9
      - /vol1/1000/Docker/OpenViking:/app/.openviking
10
    environment:
11
      - TZ=Asia/Shanghai

踩坑记录：换 embedding 模型，服务直接拒绝启动#

这是最大的一个坑。

Embedding 模型决定向量库的坐标系，所有记忆的向量都按它生成。换模型 = 换坐标系，所以向量库必须”一个模型一个池子”。OpenViking 启动时会校验向量库记录的 embedding 元数据和当前配置是否一致，不一致直接拒绝启动，这是保护机制：

1
EmbeddingRebuildRequiredError: Existing collection embedding metadata does
2
not match current configuration. Rebuild is required...

我一开始用的 Qwen3-Embedding-0.6B（1024 维），后来想换 4B，改了配置重启，就撞上这个。而且更关键的是：

维度都变了，不是同一个坐标系的问题，是盒子尺寸都不一样了，旧向量完全没法复用。处理方式：

1. 停容器，删掉旧向量库（data/vectordb/context，备份一份再删）
2. 改 ov.conf 里 dimension: 2560
3. 启动，向量库按新模型重建
4. 已有内容重新向量化（我直接重新导入一次，173 个文件，210 秒跑完，零错误）

如果你换的是同维度的模型（比如 4B ↔ 8B，都是 2560），理论上可以设 embedding.allow_metadata_override: true 保留旧向量，但不建议，不同模型的语义空间不同，新旧向量混在一个库里检索会失真。老老实实重建最干净。

账号和权限：一个 Agent 一个用户#

OpenViking 是多租户的：account（工作区）+ user（用户）。记忆、会话按用户隔离，viking://resources 是同一工作区共享的。

实践建议：每个 Agent 一个 user 账号，各自用各自的 user key 连接，记忆互不干扰。创建用户走 Admin API（root key 调用）：

1
curl -X POST http://127.0.0.1:1933/api/v1/admin/accounts/default/users \
2
  -H "Content-Type: application/json" \
3
  -H "X-API-Key: <root-key>" \
4
  -d '{"user_id": "hermes", "role": "user"}'
5
# 返回 user_key，就是给这个 agent 用的

注意三种角色的分工：

root key 不能直接访问数据 API（返回 PERMISSION_DENIED），Agent 连接必须用 user key。

部署完成长什么样#

启动后等健康检查通过：

1
curl http://127.0.0.1:1933/health
2
# {"status":"ok","healthy":true,...}

浏览器打开 http://你的NAS-IP:1933/studio 就是 Web Studio：

给 agent 配连接时就是填这个地址 + user key。我的 Hermes 打开 OpenViking 记忆提供方配置页，ENDPOINT 填 http://192.168.31.3:1933，API KEY 填 hermes 用户的 user key，保存即可。

延伸：把 Hindsight 的记忆迁过来#

我之前用 Hindsight 给 Hermes 当记忆库，里面 570 条记忆单元 + 16 个会话全文。迁移路径是 Hindsight API 只读导出 → 转成 markdown → OpenViking 官方 API 导入，不是复制数据库文件（两家存储格式完全不兼容，Hindsight 是 PostgreSQL 图结构，OpenViking 是文件系统 + 向量库）。

导出（Hindsight 8888 端口 API）：

1
curl "http://127.0.0.1:8888/v1/default/banks/hermes/memories/list?limit=100&offset=0"

组装成 markdown（一条记忆一个标题块，保留时间/实体/来源），打包上传导入：

1
curl -X POST http://127.0.0.1:1933/api/v1/resources/temp_upload \
2
  -H "X-API-Key: <user-key>" -F "file=@hermes-hindsight.zip"
3
curl -X POST http://127.0.0.1:1933/api/v1/resources \
4
  -H "Content-Type: application/json" -H "X-API-Key: <user-key>" \
5
  -d '{"temp_file_id": "...", "to": "viking://user/hermes/resources/hindsight-import"}'

导入后 OpenViking 自动向量化 + 生成摘要，中文语义检索实测命中率不错（“欧盟人工智能法案”这类查询能稳定召回）。要说损失也有：Hindsight 的知识图谱关系边没法迁移，记忆从”图结构”变成了”可语义检索的资源库”，这是迁移的本质，不是意外丢失。

极简流程#

1. 建目录 /vol1/1000/Docker/OpenViking，写 ov.conf（root key + embedding + VLM）
2. docker compose up -d，等 /health 返回 ok
3. 客户端连接：http://NAS-IP:1933 + 一个 user key（Admin API 创建）
4. 换 embedding 模型 = 重建索引，换 VLM = 随便换

写在最后#

OpenViking 是我目前用下来最顺手的 agent 记忆方案：开源、本地数据、多租户隔离，Web Studio 能直接看记忆结构。折腾下来最大的坑就是向量模型那个，其余都挺顺的。数据全部落在 /vol1/1000/Docker/OpenViking，哪天要换机器，整个目录拷走 + docker save 镜像就完事。