第 9 章 · 01 基准复现与部署

第 9 章 · 01 基准复现与部署

本节摘要:漫游倒数第二站,动作 du 全盘盘点 + serve 上生产。先验收:benchmark/ 目录备好八大基准——LoCoMo 长对话记忆、tau2 多轮任务、skillsbench、RAG、longmemeval、retrieval、vectordb_perf、cuvs——每个都是可执行脚本而非纸面数字;重点复现 LoCoMo:配置模型与 root_api_key、导入数据、跑评测、LLM 裁判打分、统计核对官方的 24-57% → 80-83%。再看 observability 与 grafana 面板如何把检索轨迹变成曲线。最后上线:docker-compose(官方镜像 + Caddy HTTPS)、Helm chart 进 K8s、docs/zh/configuration 配置手册与多租户。

内容来源:原项目源码 benchmark/(locomo/、tau2/、cuvs/ 等)、README_CN.md 评测段、openviking/metrics/、openviking/observability/、examples/grafana/、docker-compose.yml、Caddyfile、deploy/helm/、docs/zh/configuration/

⚠️ 注意:LoCoMo 评测依赖多租户模式:服务端必须配置 server.root_api_key,每份样本用 sample_id(如 conv-26)当 user_id 独立存储,样本之间互不污染;数据导入用的 account 与查询用的 account 必须一致(默认 default)。复现对不上数字时,先查这两处,再查模型配置。

学习目标

1. 盘点 benchmark/ 八大基准与各自考察面,说清「脚本即结果」的复现观。
2. 走通 LoCoMo 五步复现流程,记住三组对照数字与 token/时延收益,知道 bad case 怎么归因。
3. 理解 tau2 与 LoCoMo 的分工:用户记忆与经验记忆是两类基准;数清四类记忆×三个维度的靶场覆盖。
4. 会看 grafana 演示面板:检索轨迹指标如何从 metrics 子系统流出,微观宏观两级观测怎么配合。
5. 用 docker-compose/Caddy/Helm 三种姿势完成部署,掌握多租户的 account/user 两级配置要点。

一、八大基准:脚本即结果

ls benchmark/ 的目录名就是成绩单的目录:

locomo/  tau2/  skillsbench/  RAG/  longmemeval/  retrieval/  vectordb_perf/  cuvs/  custom/
​

考察面各有分工: locomo——长对话用户记忆(第 5 章的主角,超长多轮对话后回答历史问题); tau2——多轮智能体任务(Retail/Airline 场景,考经验记忆); skillsbench——技能库场景; RAG 与 longmemeval——知识库问答与长记忆评测; retrieval——检索质量本体; vectordb_perf——向量引擎性能(第 7 章 C++ 引擎的主场); cuvs——GPU 后端基准(PRELIMINARY_RESULTS.md 记录初步数据);custom 留给自定义。README_CN 把态度写在明处:「完整结果和实验设置见评测报告,复现脚本在 ./benchmark」——官方数字全部可由仓库脚本再生,这是开源评测的诚意标准,也是本节存在的理由。

顺带留意基准目录的「对照组织法」:locomo/ 下不是一份脚本,而是按接入对象各开一个子目录——vikingbot、openclaw、mem0、supermemory、claudecode、hermes。要复现「Claude Code 57.21% → 80.32%」就进 claudecode/,要与 mem0/Supermemory 这类竞品记忆系统横向对比,同目录就有现成脚手架——评测本身也是生态位之争的公开擂台。

二、LoCoMo 复现:五步走

locomo/ 目录按接入对象分子目录(vikingbot、openclaw、mem0、supermemory、claudecode、hermes),每个目录一套同构脚本:

benchmark/locomo/vikingbot/
├── run_eval.py            # 运行 QA 评估
├── judge.py               # LLM 裁判打分
├── import_to_ov.py        # 导入数据到 OpenViking
├── import_and_eval_one.sh # 单题/批量测试脚本
├── stat_judge_result.py   # 统计评分结果
├── run_full_eval.sh       # 一键运行完整评测流程
├── data/                  # 测试数据目录
└── result/                # 评测结果目录
​

README 的前置条件很坦白:

{
  "server": {
    "root_api_key": "your-key"
  }
}
​

五步流程:第一步起服务、配模型(嵌入/VLM/裁判 LLM),开启多租户;第二步导入——每份 LoCoMo 样本是一次超长对话,import_to_ov.py 把它灌进 OpenViking,sample_id 即 user_id,评测期每题的检索互不干扰;第三步评测——逐题检索+作答(run_eval.py,或 import_and_eval_one.sh 单题调试);第四步裁判——judge.py 用 LLM 按标准答案打分(LLM-as-judge,而非字符串匹配,容忍表述差异);第五步统计——stat_judge_result.py 汇总准确率与 token 用量;赶时间的直接 run_full_eval.sh 一键串联全程。vikingbot 目录的 README 还提醒了两处坑:vikingbot 评测须配置 OpenViking 的 root 级 API KEY(默认取 server.root_api_key,也可在 bot.ov_server 单独配);查询侧 account 默认 default,若改必须与导入侧一致。对齐官方数字(README_CN 0.3.22 版评测):

同时输入 token 减少 34.3%-91.0%,查询时延降低 58.45%-66.10%。为什么三家原生分数差得远(24 到 57),接入后却挤在 80-83% 的窄带里?因为接入后决定成绩的不再是各家 Agent 的记忆实现,而是同一套外置系统(第 4 章检索+第 5 章沉淀+第 3 章分层)——上限由基准难度与检索质量共同封顶,这窄带本身就是「提升来自机制」的证据。

复现要点归纳四条:多租户必须开(root_api_key);account 全程一致;裁判模型与官方设置对齐(裁判偏严偏松直接拉分);bad case 别扔——目录里备着 locomo_bad_case_questions.csv,对着第 4 章 03 节的检索轨迹逐题查「是没检索到还是没排上来」,复现就升格成了调参实验。

tau2 同向验证经验记忆:Retail 70.94%→77.81%、Airline 54.38%→66.25%——用户记忆与经验记忆是两条独立的分数线,别混着比。tau2 考的是多轮任务里的工具调用与政策遵循(退改签、订单查询这类客服场景),OpenViking 的经验记忆(experiences 目录与 traj-exp 训练链路,第 5 章 03 节)在其中的角色是把「上一次怎么做对的」变成可检索的策略;而 skillsbench 考技能库的命中率,RAG/longmemeval 考知识库问答与超长记忆,retrieval 考检索本体质量,vectordb_perf 与 cuvs 则是第 7 章引擎的裸性能考场(索引/查询/并发三组脚本,PRELIMINARY_RESULTS.md 有初步数据)。八合一面面俱到:用户、经验、技能、知识四类记忆,准确性、性能、并发三个维度,都有独立靶场。

三、observability 与 grafana:把轨迹画成曲线

第 4 章 03 节讲过检索轨迹的可观测数据面(thinking_trace、Entering URI 日志、OpenTelemetry);指标侧的出口是 openviking/metrics/:collectors(采集)、datasources(数据源)、exporters(导出)、account_dimension(按账户维度切分),openviking/observability/ 则提供事件、上下文与 usage_audit 用量审计。Prometheus 拉走指标后,grafana 出图——examples/grafana/ 备好现成的 docker-compose、prometheus.yml 与三份面板 JSON(demo 主面板、feedback baseline、token demo):

面板上看什么?检索请求量与延迟分布(第 4 章递归轮次的真耗时)、命中率与层级分布(L0 试探/L1 确认/L2 精读各占多少——第 3 章 token 经济学的运行时证据)、队列深度与语义 DAG 进度(第 6 章入库管线的 backlog)、token 用量按账户拆账。基准告诉你「好不好」,面板告诉你「为什么」——LoCoMo 复现出差距时的第一现场就在这里。

起步姿势也现成:examples/grafana/ 下的 docker-compose.yml 拉起 grafana+prometheus 两个容器,prometheus.yml 指向 OpenViking 的 metrics 端点,面板 JSON 导入即用;grafana/ 子目录还带 provisioning 自动装载。本地演练用 docker-compose.localhost.yml 与 prometheus.localhost.yml,免去公网配置。三份面板各有侧重:demo 主面板看全链路,feedback baseline 看用户反馈基线,token demo 专门盯 token 经济学——把第 3 章的「L0 一百 token 试探」从设计变成可审计的账目。

观测三件套的分工再理一遍:应用内 tracing(第 4 章 thinking_trace)负责单次检索的逐步复盘,日志(Entering URI)负责流水审计,Prometheus+grafana 负责聚合趋势——微观可复盘、宏观可报警,缺一角都不是生产级观测。

与基准的配合关系也别错过:跑 LoCoMo 前先看面板确认队列排空(入库未完成就评测是新手第一大坑),跑完再对比 token 曲线验证「省」的半边——基准与面板一个出结论、一个出证据,合起来才是完整的复现报告。

四、部署:compose、Caddy 与 Helm

最短路径是官方 compose。docker-compose.yml 的骨架一目了然:

services:
  openviking:
    image: ghcr.io/volcengine/openviking:latest
    ports:
      - "${OPENVIKING_SERVER_PORT:-1933}:${OPENVIKING_SERVER_PORT:-1933}"
    volumes:
      - ~/.openviking:/app/.openviking        # 配置与数据全在这一个目录
    healthcheck:
      test: ["CMD", "openviking-entrypoint", "--healthcheck"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 30s
    restart: unless-stopped
  caddy:
    image: caddy:2
    ports:
      - "1934:1934"                            # 反向代理入口
​

注:1934 端口是为存量部署保留的反代入口,新部署也可直连 openviking:1933——compose 注释把这条演进史写在了配置里。

值得圈的三处:数据面收敛——~/.openviking 一个宿主目录承载配置与全部存储,备份/rsync 即迁移;healthcheck 走 entrypoint——容器自检复用与 doctor 同源的检查,编排器据此重启;Caddy 负责 HTTPS——公网部署时在 .env 里设 OPENVIKING_PUBLIC_BASE_URL=https://ov.your-domain.com 与 OV_ACME_EMAIL,Caddyfile 加域名块,80/443 端口打开,ACME 自动签证书。compose 文件顶部的注释把三种 .env 写法都给了示例:本地零配置直接 docker compose up -d、自定义端口改 OPENVIKING_SERVER_PORT、公网 HTTPS 配 BASE_URL+ACME。公网 HTTPS 不是锦上添花:上一章的 MCP OAuth、公网 Agent 接入都要求 TLS。

# .env 示例:公网 HTTPS
OPENVIKING_PUBLIC_BASE_URL=https://ov.your-domain.com
OV_ACME_EMAIL=admin@your-domain.com
​

K8s 用户走 deploy/helm/openviking chart——镜像、配置、持久卷、健康检查封装成 values,随版本升级;examples/k8s-helm 里另有带说明的部署示例。配置手册在 docs/zh/configuration/(01-server.md 那张 vectordb.backend 表的老家),模型、检索、嵌入、bot 的每一项都在册。

五、多租户:一套服务,一个团队

多租户是部署侧最后一个要点,值得单独立节。开 server.root_api_key 后,account/user 两级身份隔离贯穿整个系统:

• 存储层——第 7 章 VikingDBManagerProxy 把请求上下文绑进向量查询,search_in_tenant 按租户过滤,account A 永远搜不到 account B 的向量;
• 文件层——viking_fs 的每个操作都携带 RequestContext,viking://user/<user>/ 空间天然按用户划分;
• 观测层——metrics 的 account_dimension 把 token 用量、检索量按账户拆账,计费与配额有据可查;
• 评测层——第 5 章 LoCoMo 的「一样本一租户」(sample_id 当 user_id)正是这套机制的评测化用法:样本间零污染,才敢谈复现数字。

examples/multi_tenant 有现成示例代码。团队部署的典型拓扑:单实例 + local 向量后端起步,数据量上来后 vectordb.backend 一行切到 volcengine——第 7 章 03 节的承诺在部署侧兑现;再往后,把 MCP endpoint 开给每个成员的 coding agent,把 Web Studio 开给不写代码的同事,一台服务器就成了整个团队的共享记忆体。

💡 漫游要点:基准复现是全书唯一「动手验证」的章节,别只看数字:LoCoMo 的五步流程把第 4-5 章(检索+记忆)、第 6 章(导入管线)、第 8 章(插件接入)串成一次端到端拉练;grafana 面板把「分层加载省 token」「递归检索带语境」从论断变成曲线;部署侧则验收了第 7 章的可插拔承诺(数据一个目录、后端一行切换)。跑通本节,你就不再是读者,而是运维者。

本节要点回顾

• 八大基准:locomo(长对话用户记忆)/tau2(多轮任务经验)/skillsbench/RAG/longmemeval/retrieval/vectordb_perf/cuvs(+custom);官方数字全部有仓库脚本可复现;locomo 按接入对象分子目录,含 mem0/supermemory 竞品对照位。
• LoCoMo 脚本族:import_to_ov/run_eval/judge/stat_judge_result/run_full_eval.sh(+import_and_eval_one.sh 单题调试);五步:配模型+root_api_key → 导入(sample_id=user_id) → 评测 → LLM 裁判 → 统计;account 全程一致;bad_case 清单配合检索轨迹归因。
• 官方数字:OpenClaw 24.20→82.08、Hermes 33.38→82.86、Claude Code 57.21→80.32(三家收敛窄带=提升来自外置机制);token -34.3%~-91.0%、时延 -58.45%~-66.10%;tau2 Retail 70.94→77.81、Airline 54.38→66.25(经验记忆独立赛道)。
• 观测:metrics(collectors/datasources/exporters/account_dimension)+ observability(events/usage_audit);examples/grafana 现成 compose+prometheus+三份面板 JSON(demo/feedback baseline/token);看延迟分布、层级命中占比、队列深度、按账户 token 拆账;跑基准前确认队列排空,跑完比对 token 曲线。
• 部署:compose 用 ghcr.io/volcengine/openviking:latest,数据收敛于 ~/.openviking,healthcheck 复用 entrypoint;Caddy 2 于 1934 反代(存量兼容,新部署可直连 1933),公网设 OPENVIKING_PUBLIC_BASE_URL+OV_ACME_EMAIL 走 ACME;K8s 用 deploy/helm(examples/k8s-helm);配置手册 docs/zh/configuration;多租户=root_api_key+account/user 两级(存储/文件/观测/评测四层贯穿),LoCoMo 一样本一租户是其评测用法。

下一节:02 全书回顾:漫游上下文数据库——漫游最后一站:沿九站串讲全书,提炼 OpenViking 核心哲学四点,与 Hermes、semantica 的记忆方案做三方对照,并给出合上书之后的下一步。