diff --git a/README.md b/README.md index 95bc3f1..f780476 100644 --- a/README.md +++ b/README.md @@ -3,12 +3,12 @@ [![CI - Lint, Tests & Adapter Build](https://github.com/matrixorigin/memory_benchmarks/actions/workflows/aml-ci.yml/badge.svg?branch=main)](https://github.com/matrixorigin/memory_benchmarks/actions/workflows/aml-ci.yml) Public memory benchmarks, an Agent Memory Leaderboard (AML) Add/Search adapter, -and a dedicated dev deployment for [Memoria](https://github.com/matrixorigin/memoria). +and deployment templates for [Memoria](https://github.com/matrixorigin/memoria). This repository helps the team evaluate how well Memoria retrieves evidence from conversation histories. It prepares public datasets, writes the original history through `/add`, queries `/search`, and records retrieval metrics and run checkpoints. -It also owns the adapter and its Aliyun dev deployment pipeline. +Deployment templates are included; live environments have their own release process. **Default mode: retrieval diagnostics.** LoCoMo and LongMemEval-S also support optional local Answer/Eval. Native evaluator parity, coding scores and official @@ -22,8 +22,9 @@ AML leaderboard scores remain separate acceptance work. See the | Try the deployed API | Adapter access key | [API quick start](#try-the-deployed-api) | | Run a benchmark in Actions | Workflow access; configured adapter access key | [Run a benchmark](#run-a-benchmark) | | Develop the adapter locally | Python 3.12+, uv, running Memoria, master key | [Local development](#local-development) | +| Reproduce a fixed deployment | Pinned mb/Memoria versions and configured backend | [Deployment and reproduction](deploy/README.md#本地复现) | | Deploy or update services | Configured deployment Secrets and Variables | [Deployment](#deploy-or-update-services) | -| Understand the design | No runtime credentials | [Competition design](agent_memory_leaderboard/docs/competition-plan.md) | +| Understand the design | No runtime credentials | [Architecture](#how-it-works) and [adapter guide](agent_memory_leaderboard/README.md) | ## How it works @@ -115,9 +116,8 @@ not automatically clean it up. | `GET /docs` | Interactive request/response documentation | Healthy probes alone do not validate authentication, model calls, or retrieval -quality. The dev deployment and seven-check live API integration smoke passed on -2026-10-06; the [acceptance record](agent_memory_leaderboard/docs/competition-plan.md#当前交付状态) -contains the actual revisions and remaining validation scope. +quality. Verify these paths against the intended environment before a benchmark; +this guide does not certify a particular deployment or official evaluation run. For the complete field contract and Python example, see [public integration](deploy/README.md#接入已部署的-addsearch). For retry and error @@ -170,8 +170,9 @@ not consume official AML Full quota. See the [benchmark workflow guide](agent_memory_leaderboard/benchmarks/CI.md) for data provenance, metric definitions, timeout and resume behavior. -Recorded self-run results and their limitations are available in -[baseline reports](agent_memory_leaderboard/benchmarks/baselines/README.md). +Keep environment-specific baseline reports, checkpoints and run notes under the +Git-ignored `var/` directory. Record the code, dataset and configuration used; do +not treat local results as official AML scores. ### Interpreting the metrics @@ -245,17 +246,14 @@ local integration smoke, benchmark commands, and a Memoria Docker Compose overla ## Deploy or update services -QA services are managed in **moi-gitops**, stack `idc`: the `aml-qa` unit owns the -adapter and the `memoria` unit owns shared Memoria. See the -[QA deployment handbook](https://github.com/matrixorigin/moi-gitops/blob/main/docs/handbooks/qa-aml-adapter.md). -The old Aliyun direct-deployment workflow has been removed. This repository's -active CI/benchmark workflows do not deploy to Aliyun or require its cluster, -SQL or Memoria administration credentials. Legacy deployment code and its -[reference guide](deploy/README.md) remain for historical reference. +See the [deployment reference](deploy/README.md) for the template layout, +configuration boundaries and Add/Search integration. The active workflows in +this repository run checks and optional QA benchmarks; they do not deploy an +application. Shared environments use their existing reviewed release process. -The adapter image build → moi-gitops image-update PR workflow is follow-up work. -ACR still hosts the application images, and the configured qwen-plus answer/judge -service still uses DashScope. These dependencies are separate from hosting QA. +Deployment plans, environment-specific acceptance records and internal run notes +are local operator material, rather than public usage documentation. Keep them +under Git-ignored `var/private-docs/`; do not link public guides to local files. ## Workflows at a glance @@ -268,13 +266,13 @@ service still uses DashScope. These dependencies are separate from hosting QA. ```text memory_benchmarks/ -├── .github/workflows/ # Offline CI, dev deployment, manual benchmark +├── .github/workflows/ # Offline CI and manual benchmark ├── agent_memory_leaderboard/ │ ├── src/ # Adapter, journal, HTTP client, shared benchmark program │ ├── benchmarks/ # Parsers, preparation, entrypoints and CI guide │ ├── scripts/ # Local launchers and Actions preparation/reporting │ ├── tests/ # Adapter and benchmark tests using simulated backends -│ ├── docs/ # Maintained design and review references +│ ├── docs/ # Public feature and experiment guides │ └── compose.adapter.yaml # Overlay for Memoria Docker Compose └── deploy/ ├── chart/ # Helm resources for Memoria and adapter @@ -289,9 +287,9 @@ when obtaining or sharing its data. ## Design and contribution -The maintained [competition design](agent_memory_leaderboard/docs/competition-plan.md) -records architecture, decisions, verified delivery status, and remaining work. -Detailed guides own operational instructions; this README is the project entrypoint. +The architecture overview above and the public adapter, deployment and benchmark +guides describe supported behavior. Keep internal plans, live acceptance records +and experiment outputs in Git-ignored local storage. Explain the design, validation evidence, and effect on API behavior or evaluation comparability in each PR. Preserve provenance and user isolation, keep gold data diff --git a/agent_memory_leaderboard/.gitignore b/agent_memory_leaderboard/.gitignore index e2afded..0054d94 100644 --- a/agent_memory_leaderboard/.gitignore +++ b/agent_memory_leaderboard/.gitignore @@ -8,3 +8,17 @@ var/ benchmarks/*/*/data/ benchmarks/*/*/results/ state/*.json + +# Local retry journals and their SQLite sidecars. +*.db +*.db-journal +*.db-wal +*.db-shm +*.sqlite +*.sqlite-journal +*.sqlite-wal +*.sqlite-shm +*.sqlite3 +*.sqlite3-journal +*.sqlite3-wal +*.sqlite3-shm diff --git a/agent_memory_leaderboard/README.md b/agent_memory_leaderboard/README.md index 9e1a78b..cefd9fe 100644 --- a/agent_memory_leaderboard/README.md +++ b/agent_memory_leaderboard/README.md @@ -59,25 +59,13 @@ It checks adapter liveness, not Memoria/database/embedding readiness. `GET /ready` checks journal readability and the upstream Memoria health endpoint, without writing memories or invoking a model. It is a dependency-availability check, not evidence that Add/Search or the embedding provider works correctly. -The deployment target is the Aliyun dev unit cluster, using a dedicated Memoria -backend and database login. Local evaluation remains available. -See [competition design](docs/competition-plan.md) for runtime scope and workload -budgets. The offline CI checks code and builds the adapter image without -publishing or deploying it. Memoria source builds run only in the dev deployment -workflow when updating Memoria in source mode, including preview. Adapter-only -updates and existing-image mode skip Memoria builds. -The [dev deployment workflow](../deploy/README.md) defaults to building Memoria -from its `main` branch; another branch, tag, commit, or existing image can be selected. -It publishes the selected images and deploys both services by digest through an -independent Pulumi stack, recording the actual source commit for each source build. -Public access requires DNS; the existing cert-manager ClusterIssuer automatically -issues and renews the TLS Secret. - -The Aliyun dev endpoint is deployed at `https://aml.cn-dev.matrixone.tech`. -See the [deployment steps and Actions inputs](../deploy/README.md#发布流程) and -[public curl/Python integration examples](../deploy/README.md#接入已部署的-addsearch). -Public clients need only the adapter API key; they do not need Memoria master, -database, or Kubernetes credentials. +For local development, configure a running Memoria service and use the adapter's +loopback endpoint. Hosted environments supply their own endpoint, capacity and +release configuration; see the [deployment reference](../deploy/README.md). +The offline CI checks code and builds the adapter without deploying it. The +manual QA benchmark calls its configured QA service and does not select or +update a deployment. Public clients use only the adapter key; database, +Kubernetes and Memoria administration credentials stay with the operators. ## Contract verification @@ -90,9 +78,9 @@ For submission, use public endpoint URLs without embedded credentials; the localhost examples below are for development. Enable authentication for Full. Configure proxy/load-balancer request timeouts for the documented 30-minute request window. `MEMORIA_TIMEOUT_SECONDS` controls each upstream call (default -120 seconds), not the total Add duration. The deployed dev endpoint has passed -the project's live integration smoke; official platform Smoke and long-request -validation remain pending. See the [current acceptance status](docs/competition-plan.md#当前交付状态). +120 seconds), not the total Add duration. A local smoke, a deployment health +check and an official AML Smoke are separate checks; keep their run records and +version bindings outside the public usage guide. Concurrent Add/Search requests can queue native Memoria calls without changing synchronous Add semantics. Set `MEMORIA_MAX_CONCURRENCY=1` and diff --git a/agent_memory_leaderboard/benchmarks/CI.md b/agent_memory_leaderboard/benchmarks/CI.md index 58776b2..8eea3d0 100644 --- a/agent_memory_leaderboard/benchmarks/CI.md +++ b/agent_memory_leaderboard/benchmarks/CI.md @@ -61,14 +61,14 @@ benchmark 请求 QA 当前部署的 Add/Search；Summary 与 JSON 记录环境 旧阿里云部署 workflow 已移除。QA 使用 `aml-qa-benchmark` 只串行本仓库的 QA 评测；moi-gitops 在另一个仓库，同名 concurrency group 也不能跨仓库互斥。 QA 评测前需要协调共享 Memoria 与 GitOps 发布；本 workflow 不宣称已自动冻结它们。 -QA gateway 初始限制一个活跃业务请求、每秒一个后端业务请求，完整历史可能明显慢于 dev。 +实际入口和后端限制以目标环境当前配置为准；运行前核对容量，不能从历史配置推断本轮能力。 并发组不阻止其他本地客户端、AML 官方任务或手工操作；GitHub 默认只保留一个 pending 运行，新 pending 可能替换旧 pending，不应同时排队多个部署／评测任务。 ## Summary 与完整报告 -已完成运行的安全聚合指标与解释见[固定基线](baselines/README.md)。完整断点仍在 -对应 Actions artifact；Git 中的聚合报告不包含数据正文、回答或可恢复的 private cache。 +具体运行的基线、版本和验收记录保存在 Git 忽略的本地 `var/` 目录或受控运行记录中。 +公开文档仅说明如何生成和解释报告，不绑定某次环境验收结果。 Summary 包含状态、评测进程耗时、写入分块数、已处理／已查询／跳过的问题数、空结果、 有证据标签的问题数、召回率、Search P50／P95、按数据集 category 分组的结果及版本。 @@ -144,24 +144,17 @@ Summary 单列 eligible／scored／pending、评分覆盖率及两类失败题 缺失时不写入记忆。准备步骤不读取模型凭据。工作流安装锁定的 evaluation extra； 适配器镜像不需要此 extra，也不需要重新部署。 -当前开发配置（2026-10-07）：回答和裁判的 MODEL 均为 `qwen-plus`，两个 BASE_URL -均为 `https://dashscope.aliyuncs.com/compatible-mode/v1`，分别配置上述两个 API_KEY -Secrets，复用已有百炼凭据。GitHub 配置已保存并回读确认；尚未验证本次凭据的模型 -调用或执行新契约基准。密钥不进入仓库或日志。 +根据所选模型服务填写上述 Variables 和 Secrets。示例配置不代表某个仓库已经配置凭据， +也不代表模型调用或完整评测已通过验证。密钥不进入仓库或日志。 -运行 `AML benchmark` 时选择 `main`、`dataset=locomo`、`mode=answer-eval`、 +运行 `QA memory benchmark` 时选择 `main`、`dataset=locomo`、`mode=answer-eval`、 `histories=1`、`top_k=100`，`runtime_label` 可留空。模型设置在 benchmark 进程中生效， 不需要重新构建或部署 Memoria／适配器。qwen-plus 为提供商可更新别名，跨日期比较 不能假定底层权重相同；长期可比实验需选择并记录可用快照版本。回答与裁判同模型的 分数用于本地迭代，不能作为独立裁判或官方评分等价性的证明。 -正式 AML 的 Answer/Eval 由平台固定，我们的配置不会替换平台模型。官方 Full checklist -写 Open-source Methods 的 Add 期望使用 `gpt-4o-mini`，商业产品无 Add/Search 模型限制； -FAQ 仍写学术榜 embedding 为 `text-embedding-v4`、LLM 组件为 `gpt-4o-mini`、reranker -不限制。两套组别名称的对应及纯存储 Add／上海 bge-m3 资格需向官方确认；不能用本地 -qwen-plus 配置推断正式参评合规。 -依据：[AML 文档](https://agentmemories.ai/zh-cn/docs)、 -[赛事 FAQ](https://agentmemoryleaderboard.ai/competition/)。 +正式 AML 的回答与评分由平台提供，本地配置不会替换平台模型。参赛组别和模型要求 +以[官方文档](https://agentmemoryleaderboard.ai/docs)为准，本地运行结果不证明正式参评合规。 全部输入（指令、角色、问题、选项／问题日期、证据）按固定 `o200k_base` 编码加 256 token 余量进行本地预算计数，上限 117760；保留完整记录的排名前缀。它不是所有 @@ -210,7 +203,7 @@ Answer/Eval 的 private cache 也受同一保留期约束，不能随报告公 报告按现有保留策略记录清理期限；120 分钟步骤被强制终止、runner 未执行 finally 时， 最终报告步骤补写未设置的保留期限，不延长已有期限。 Artifact 过期不清理 Memoria、用户库、journal 或历史快照；物理清理需要独立运维方案。 -正式评测前执行发布冻结及保留管理流程，见[比赛方案](../docs/competition-plan.md)。 +正式评测前与环境维护者协调发布冻结、版本记录和保留管理，见[部署参考](../../deploy/README.md)。 该 workflow 消耗我们自己的 embedding、数据库和 Actions 资源，不消耗 AML 官方 Full 配额。请求串行发送；限制 histories 和执行时长不等于完整的全局 QPS／token 预算。 @@ -224,10 +217,9 @@ Artifact 过期不清理 Memoria、用户库、journal 或历史快照；物理 | 作答（仅 answer-eval） | `BENCHMARK_ANSWER_API_KEY` | `AML_BENCHMARK_ANSWER_API_KEY` | | 判分（仅 answer-eval） | `BENCHMARK_JUDGE_API_KEY` | `AML_BENCHMARK_JUDGE_API_KEY` | -本地完整 QA 配置保存在私有 `var/evaluation-qa.env`（当前独立 worktree 下），权限 0600、 -Git 忽略；模型名和 base URL 也已配置。GitHub 的上述三个 Secret 已配置，模型变量沿用 -qwen-plus / DashScope。本地真实 QA 最小链路已通过；GitHub-hosted runner 的端到端执行 -需在本 PR 合入后首次运行验证，Secret 已存在不等于运行已验证。 +本地配置可保存在 Git 忽略的 `var/evaluation-qa.env`，使用仅当前用户可读写的权限； +模型名称、地址和凭据由操作者自行配置。不要将凭据是否存在写成链路验证结论， +也不要把本地 private cache 或内部验收记录加入仓库。 离线 CI 不使用任何业务 key。评测不需要 KUBECONFIG、Pulumi token、数据库密码、 Memoria master key 或 embedding key；这些由 QA 后端和 GitOps 持有。当前服务运行于 diff --git a/agent_memory_leaderboard/benchmarks/EVALUATION.md b/agent_memory_leaderboard/benchmarks/EVALUATION.md index c934769..ea9b806 100644 --- a/agent_memory_leaderboard/benchmarks/EVALUATION.md +++ b/agent_memory_leaderboard/benchmarks/EVALUATION.md @@ -41,7 +41,7 @@ flow, but the complete official judge prompts and a reproducible implementation were not found in the documentation checked on 2026-10-07. The prompts in `src/judges/` come from the public benchmark repositories, not from AML. See the [official documentation](https://agentmemories.ai/zh-cn/docs) and -[competition readiness plan](../docs/competition-plan.md#正式参评前的工作). +[deployment reference](../../deploy/README.md). ## LongMemEval answer reader diff --git a/agent_memory_leaderboard/benchmarks/baselines/2026-10-07-dev-probes.json b/agent_memory_leaderboard/benchmarks/baselines/2026-10-07-dev-probes.json deleted file mode 100644 index 6c864da..0000000 --- a/agent_memory_leaderboard/benchmarks/baselines/2026-10-07-dev-probes.json +++ /dev/null @@ -1,442 +0,0 @@ -{ - "schema_version": 1, - "official_aml_score": false, - "adapter_url": "https://aml.cn-dev.matrixone.tech", - "memoria_commit": "81c5cc6d5e86a34072ecbc1bb41979b06364e7c7", - "adapter_commit": "3048f6bab82966ee63c25fbf5f6cb51cadf87c6d", - "source_time": { - "reference_time": "2026-10-07T08:35:00+00:00", - "source_timestamps_ms": { - "old": 1661762100000, - "recent": 1791362100000, - "before_cutoff": 1698679072353, - "after_cutoff": 1698333472353 - }, - "status": "completed", - "successful_requests": 16, - "failed_requests": 0, - "route_metrics": { - "/add": { - "successful": 4, - "failed": 0, - "p50_seconds": 3.7263882500119507, - "p95_seconds": 6.325807166984305 - }, - "/search": { - "successful": 12, - "failed": 0, - "p50_seconds": 1.520124665927142, - "p95_seconds": 1.9900605829898268 - } - }, - "search_observations": [ - { - "ok": true, - "hit_sources": [ - "old" - ], - "scenario": "old-only", - "query_index": 0 - }, - { - "ok": true, - "hit_sources": [ - "old" - ], - "scenario": "old-only", - "query_index": 1 - }, - { - "ok": true, - "hit_sources": [ - "old" - ], - "scenario": "old-only", - "query_index": 2 - }, - { - "ok": true, - "hit_sources": [ - "recent" - ], - "scenario": "recent-only", - "query_index": 0 - }, - { - "ok": true, - "hit_sources": [ - "recent" - ], - "scenario": "recent-only", - "query_index": 1 - }, - { - "ok": true, - "hit_sources": [ - "recent" - ], - "scenario": "recent-only", - "query_index": 2 - }, - { - "ok": true, - "hit_sources": [ - "recent" - ], - "scenario": "mixed", - "query_index": 0 - }, - { - "ok": true, - "hit_sources": [ - "recent" - ], - "scenario": "mixed", - "query_index": 1 - }, - { - "ok": true, - "hit_sources": [ - "recent" - ], - "scenario": "mixed", - "query_index": 2 - }, - { - "ok": true, - "hit_sources": [ - "before_cutoff" - ], - "scenario": "threshold", - "query_index": 0 - }, - { - "ok": true, - "hit_sources": [ - "before_cutoff" - ], - "scenario": "threshold", - "query_index": 1 - }, - { - "ok": true, - "hit_sources": [ - "before_cutoff" - ], - "scenario": "threshold", - "query_index": 2 - } - ], - "separate_owner_scoped_explain": [ - { - "scenario": "old-only", - "stored_memories": [ - { - "source": "old", - "is_active": true, - "observed_at": "2022-08-29T08:35:00+00:00", - "created_at": "2026-10-07T08:51:20.089303+00:00", - "initial_confidence": 0.949999988079071, - "memory_type": "episodic", - "trust_tier": "T1" - } - ], - "direct_searches": [ - { - "explain": { - "path": "fulltext", - "vector_attempted": true, - "vector_hit": false, - "fulltext_attempted": true, - "fulltext_hit": true, - "graph_attempted": true, - "graph_hit": false, - "result_count": 1, - "graph_candidates": 0, - "embedding_ms": 122.00543499999999, - "vector_ms": 38.027613, - "fulltext_ms": 20.011909000000003, - "graph_ms": 18.04759, - "total_ms": 212.650844 - }, - "matched_sources": [ - "old" - ] - }, - { - "explain": { - "path": "fulltext", - "vector_attempted": true, - "vector_hit": false, - "fulltext_attempted": true, - "fulltext_hit": true, - "graph_attempted": true, - "graph_hit": false, - "result_count": 1, - "graph_candidates": 0, - "embedding_ms": 342.565548, - "vector_ms": 29.102295, - "fulltext_ms": 6.386272999999999, - "graph_ms": 0.016149, - "total_ms": 397.738195 - }, - "matched_sources": [ - "old" - ] - }, - { - "explain": { - "path": "fulltext", - "vector_attempted": true, - "vector_hit": false, - "fulltext_attempted": true, - "fulltext_hit": true, - "graph_attempted": true, - "graph_hit": false, - "result_count": 1, - "graph_candidates": 0, - "embedding_ms": 882.620948, - "vector_ms": 15.588157, - "fulltext_ms": 12.60766, - "graph_ms": 0.011793999999999999, - "total_ms": 912.343807 - }, - "matched_sources": [ - "old" - ] - } - ] - }, - { - "scenario": "mixed", - "stored_memories": [ - { - "source": "recent", - "is_active": true, - "observed_at": "2026-10-07T08:35:00+00:00", - "created_at": "2026-10-07T08:51:40.506449+00:00", - "initial_confidence": 0.949999988079071, - "memory_type": "episodic", - "trust_tier": "T1" - }, - { - "source": "old", - "is_active": true, - "observed_at": "2022-08-29T08:35:00+00:00", - "created_at": "2026-10-07T08:51:39.893981+00:00", - "initial_confidence": 0.949999988079071, - "memory_type": "episodic", - "trust_tier": "T1" - } - ], - "direct_searches": [ - { - "explain": { - "path": "hybrid", - "vector_attempted": true, - "vector_hit": true, - "fulltext_attempted": false, - "fulltext_hit": false, - "graph_attempted": true, - "graph_hit": false, - "result_count": 1, - "graph_candidates": 0, - "embedding_ms": 1102.715862, - "vector_ms": 32.869706, - "fulltext_ms": 0.0, - "graph_ms": 42.844, - "total_ms": 1178.445127 - }, - "matched_sources": [ - "recent" - ] - }, - { - "explain": { - "path": "hybrid", - "vector_attempted": true, - "vector_hit": true, - "fulltext_attempted": false, - "fulltext_hit": false, - "graph_attempted": true, - "graph_hit": false, - "result_count": 1, - "graph_candidates": 0, - "embedding_ms": 369.507558, - "vector_ms": 43.495604, - "fulltext_ms": 0.0, - "graph_ms": 0.014326, - "total_ms": 413.04346400000003 - }, - "matched_sources": [ - "recent" - ] - }, - { - "explain": { - "path": "hybrid", - "vector_attempted": true, - "vector_hit": true, - "fulltext_attempted": false, - "fulltext_hit": false, - "graph_attempted": true, - "graph_hit": false, - "result_count": 1, - "graph_candidates": 0, - "embedding_ms": 394.17120500000004, - "vector_ms": 37.6229, - "fulltext_ms": 0.0, - "graph_ms": 0.012269, - "total_ms": 431.836002 - }, - "matched_sources": [ - "recent" - ] - } - ] - }, - { - "scenario": "threshold", - "stored_memories": [ - { - "source": "after_cutoff", - "is_active": true, - "observed_at": "2023-10-26T15:17:52.353+00:00", - "created_at": "2026-10-07T08:51:49.186791+00:00", - "initial_confidence": 0.949999988079071, - "memory_type": "episodic", - "trust_tier": "T1" - }, - { - "source": "before_cutoff", - "is_active": true, - "observed_at": "2023-10-30T15:17:52.353+00:00", - "created_at": "2026-10-07T08:51:48.528960+00:00", - "initial_confidence": 0.949999988079071, - "memory_type": "episodic", - "trust_tier": "T1" - } - ], - "direct_searches": [ - { - "explain": { - "path": "hybrid", - "vector_attempted": true, - "vector_hit": true, - "fulltext_attempted": false, - "fulltext_hit": false, - "graph_attempted": true, - "graph_hit": false, - "result_count": 1, - "graph_candidates": 0, - "embedding_ms": 182.46268099999998, - "vector_ms": 36.230427000000006, - "fulltext_ms": 0.0, - "graph_ms": 19.050824000000002, - "total_ms": 237.758654 - }, - "matched_sources": [ - "before_cutoff" - ] - }, - { - "explain": { - "path": "hybrid", - "vector_attempted": true, - "vector_hit": true, - "fulltext_attempted": false, - "fulltext_hit": false, - "graph_attempted": true, - "graph_hit": false, - "result_count": 1, - "graph_candidates": 0, - "embedding_ms": 161.907535, - "vector_ms": 35.339334, - "fulltext_ms": 0.0, - "graph_ms": 0.00497, - "total_ms": 197.279082 - }, - "matched_sources": [ - "before_cutoff" - ] - }, - { - "explain": { - "path": "hybrid", - "vector_attempted": true, - "vector_hit": true, - "fulltext_attempted": false, - "fulltext_hit": false, - "graph_attempted": true, - "graph_hit": false, - "result_count": 1, - "graph_candidates": 0, - "embedding_ms": 161.897787, - "vector_ms": 40.061409, - "fulltext_ms": 0.0, - "graph_ms": 0.014516, - "total_ms": 201.989582 - }, - "matched_sources": [ - "before_cutoff" - ] - } - ] - } - ] - }, - "bounded_search_load": { - "status": "completed", - "concurrency": 2, - "qps": 1.0, - "requests": 20, - "elapsed_seconds": 32.32240654202178, - "successful_requests": 20, - "failed_requests": 0, - "p50_seconds": 2.383489375002682, - "p95_seconds": 3.836249750107527, - "successful_requests_per_second": 0.6187658079851931, - "route_metrics": { - "/add": { - "successful": 1, - "failed": 0, - "p50_seconds": 2.790696084033698, - "p95_seconds": 2.790696084033698 - }, - "/search": { - "successful": 20, - "failed": 0, - "p50_seconds": 2.383489375002682, - "p95_seconds": 3.836249750107527 - } - }, - "request_diagnostics": [ - { - "route": "/add", - "status": 200, - "reason": "unclassified", - "attempts": 1, - "retried_attempts": 0, - "elapsed_seconds": 2.7562242499552667 - }, - { - "route": "/search", - "status": 200, - "reason": "unclassified", - "attempts": 20, - "retried_attempts": 0, - "elapsed_seconds": 47.66448408016004 - } - ], - "long_request_verified": false - }, - "limitations": [ - "Separate synthetic probes; not LoCoMo scoring and not official AML Smoke.", - "Explain requests are separate reads and do not prove the path of earlier public requests.", - "Mixed old/new evidence disappears in this configuration; a global decay defect is not asserted.", - "LoCoMo ingestion uses dates in content, without AML timestamp, so this does not explain its answer score.", - "Twenty searches at one logical request/second do not establish maximum or Full capacity.", - "No successful single HTTP attempt exceeded five minutes; SLB long-request validation remains pending.", - "Synthetic memories retained for inspection; private user IDs/cleanup metadata remain in ignored local reports." - ] -} diff --git a/agent_memory_leaderboard/benchmarks/baselines/2026-10-07-locomo-qwen-plus.json b/agent_memory_leaderboard/benchmarks/baselines/2026-10-07-locomo-qwen-plus.json deleted file mode 100644 index b1ffb3f..0000000 --- a/agent_memory_leaderboard/benchmarks/baselines/2026-10-07-locomo-qwen-plus.json +++ /dev/null @@ -1,498 +0,0 @@ -{ - "schema_version": 1, - "official_aml_score": false, - "native_evaluator_equivalent": false, - "workflow_url": "https://github.com/matrixorigin/memory_benchmarks/actions/runs/37594716119", - "benchmark_commit": "003dda1c5f1681d6a307dec9203968e3168992e6", - "dataset": "locomo", - "source": { - "name": "LoCoMo-Refined", - "revision": "887091190789e8d6760e70b9edd696539923dc4f", - "url": "https://raw.githubusercontent.com/mem-eval-suite/LoCoMo_refined/887091190789e8d6760e70b9edd696539923dc4f/data/raw/locomo_refined.json", - "sha256": "1aef6da702087d72515d1b9224f0956a2fbab415c11936253bf7d967d3cf8c17", - "bytes": 2745985, - "histories": 10, - "evidence_unit": "dialogue" - }, - "histories": [ - "conv-26" - ], - "top_k": 100, - "runtime_label": "Memoria 81c5cc6 digest16d7eefa; adapter digestc273b960; observed 2026-10-07", - "contract": { - "dataset_sha256": "1aef6da702087d72515d1b9224f0956a2fbab415c11936253bf7d967d3cf8c17", - "conversations": [ - "conv-26" - ], - "adapter_url": "https://aml.cn-dev.matrixone.tech", - "top_k": 100, - "runner_version": 2, - "ingestion_version": "label-free-exact-hash-v1", - "mode": "answer-eval", - "evaluation": { - "answer_model": "qwen-plus", - "answer_base": "https://dashscope.aliyuncs.com/compatible-mode/v1", - "judge_model": "qwen-plus", - "judge_base": "https://dashscope.aliyuncs.com/compatible-mode/v1", - "encoding": "o200k_base", - "input_budget": 117760, - "output_tokens": 1024, - "prompt_version": "memory-answer-v1", - "scorer_version": "local-dataset-judge-v1", - "temperature": 0, - "token_accounting": "serialized-messages-plus-256-v1", - "context_selection_version": "ranked-prefix-binary-v2", - "model_retry_version": "four-attempts-backoff-v1", - "verdict_parser_version": "strict-json-with-fences-v2", - "native_evaluator_equivalent": false - }, - "kind": "locomo" - }, - "checkpoint_status": "completed", - "completed_add_chunks": 28, - "elapsed_seconds": 919.14, - "metrics": { - "evaluation_eligible_questions": 87, - "evaluation_coverage": 1.0, - "answer_failed_questions": 0, - "judge_failed_questions": 0, - "evaluation_pending_questions": 0, - "scored_questions": 87, - "mean_local_judge_score": 0.5632183908045977, - "mean_token_f1": 0.2673781001571264, - "mean_bleu1": 0.17731611303672598, - "mean_budget_evidence_recall": 0.8023255813953488, - "attribution_audited_questions": 87, - "ambiguous_evidence_records": 0, - "unmapped_evidence_records": 0, - "processed_questions": 138, - "evidence_recall_at_k": { - "1": { - "questions_with_evidence": 86, - "mean_evidence_recall": 0.37209302325581395, - "all_evidence_hit_rate": 0.36046511627906974 - }, - "5": { - "questions_with_evidence": 86, - "mean_evidence_recall": 0.5726744186046512, - "all_evidence_hit_rate": 0.5348837209302325 - }, - "10": { - "questions_with_evidence": 86, - "mean_evidence_recall": 0.6482558139534884, - "all_evidence_hit_rate": 0.6046511627906976 - }, - "20": { - "questions_with_evidence": 86, - "mean_evidence_recall": 0.6715116279069767, - "all_evidence_hit_rate": 0.627906976744186 - }, - "50": { - "questions_with_evidence": 86, - "mean_evidence_recall": 0.7412790697674418, - "all_evidence_hit_rate": 0.7093023255813954 - }, - "100": { - "questions_with_evidence": 86, - "mean_evidence_recall": 0.8023255813953488, - "all_evidence_hit_rate": 0.7906976744186046 - } - }, - "searched_questions": 87, - "skipped_questions": 51, - "empty_results": 0, - "mean_returned_records": 100.0, - "questions_with_evidence": 86, - "evidence_audited_questions": 87, - "questions_with_unmatched_gold": 1, - "mean_evidence_recall": 0.8023255813953488, - "all_evidence_hit_rate": 0.7906976744186046, - "search_p50_seconds": 0.9332325589999755, - "search_p95_seconds": 2.949654119999991 - }, - "categories": { - "2": { - "evaluation_eligible_questions": 20, - "evaluation_coverage": 1.0, - "answer_failed_questions": 0, - "judge_failed_questions": 0, - "evaluation_pending_questions": 0, - "scored_questions": 20, - "mean_local_judge_score": 0.55, - "mean_token_f1": 0.21955918180549033, - "mean_bleu1": 0.13135805858432054, - "mean_budget_evidence_recall": 1.0, - "attribution_audited_questions": 20, - "ambiguous_evidence_records": 0, - "unmapped_evidence_records": 0, - "processed_questions": 20, - "evidence_recall_at_k": { - "1": { - "questions_with_evidence": 20, - "mean_evidence_recall": 0.65, - "all_evidence_hit_rate": 0.65 - }, - "5": { - "questions_with_evidence": 20, - "mean_evidence_recall": 0.925, - "all_evidence_hit_rate": 0.9 - }, - "10": { - "questions_with_evidence": 20, - "mean_evidence_recall": 0.975, - "all_evidence_hit_rate": 0.95 - }, - "20": { - "questions_with_evidence": 20, - "mean_evidence_recall": 0.975, - "all_evidence_hit_rate": 0.95 - }, - "50": { - "questions_with_evidence": 20, - "mean_evidence_recall": 1.0, - "all_evidence_hit_rate": 1.0 - }, - "100": { - "questions_with_evidence": 20, - "mean_evidence_recall": 1.0, - "all_evidence_hit_rate": 1.0 - } - }, - "searched_questions": 20, - "skipped_questions": 0, - "empty_results": 0, - "mean_returned_records": 100.0, - "questions_with_evidence": 20, - "evidence_audited_questions": 20, - "questions_with_unmatched_gold": 0, - "mean_evidence_recall": 1.0, - "all_evidence_hit_rate": 1.0, - "search_p50_seconds": 0.9177461240000184, - "search_p95_seconds": 2.3784355290000576 - }, - "3": { - "evaluation_eligible_questions": 7, - "evaluation_coverage": 1.0, - "answer_failed_questions": 0, - "judge_failed_questions": 0, - "evaluation_pending_questions": 0, - "scored_questions": 7, - "mean_local_judge_score": 0.7142857142857143, - "mean_token_f1": 0.16760437508336667, - "mean_bleu1": 0.10099067612723774, - "mean_budget_evidence_recall": 0.75, - "attribution_audited_questions": 7, - "ambiguous_evidence_records": 0, - "unmapped_evidence_records": 0, - "processed_questions": 7, - "evidence_recall_at_k": { - "1": { - "questions_with_evidence": 6, - "mean_evidence_recall": 0.0, - "all_evidence_hit_rate": 0.0 - }, - "5": { - "questions_with_evidence": 6, - "mean_evidence_recall": 0.25, - "all_evidence_hit_rate": 0.16666666666666666 - }, - "10": { - "questions_with_evidence": 6, - "mean_evidence_recall": 0.4166666666666667, - "all_evidence_hit_rate": 0.3333333333333333 - }, - "20": { - "questions_with_evidence": 6, - "mean_evidence_recall": 0.5, - "all_evidence_hit_rate": 0.5 - }, - "50": { - "questions_with_evidence": 6, - "mean_evidence_recall": 0.5833333333333334, - "all_evidence_hit_rate": 0.5 - }, - "100": { - "questions_with_evidence": 6, - "mean_evidence_recall": 0.75, - "all_evidence_hit_rate": 0.6666666666666666 - } - }, - "searched_questions": 7, - "skipped_questions": 0, - "empty_results": 0, - "mean_returned_records": 100.0, - "questions_with_evidence": 6, - "evidence_audited_questions": 7, - "questions_with_unmatched_gold": 0, - "mean_evidence_recall": 0.75, - "all_evidence_hit_rate": 0.6666666666666666, - "search_p50_seconds": 0.9915763409999272, - "search_p95_seconds": 1.463357535 - }, - "1": { - "evaluation_eligible_questions": 10, - "evaluation_coverage": 1.0, - "answer_failed_questions": 0, - "judge_failed_questions": 0, - "evaluation_pending_questions": 0, - "scored_questions": 10, - "mean_local_judge_score": 0.5, - "mean_token_f1": 0.1819066291347538, - "mean_bleu1": 0.11494722453267159, - "mean_budget_evidence_recall": 0.8, - "attribution_audited_questions": 10, - "ambiguous_evidence_records": 0, - "unmapped_evidence_records": 0, - "processed_questions": 10, - "evidence_recall_at_k": { - "1": { - "questions_with_evidence": 10, - "mean_evidence_recall": 0.075, - "all_evidence_hit_rate": 0.0 - }, - "5": { - "questions_with_evidence": 10, - "mean_evidence_recall": 0.225, - "all_evidence_hit_rate": 0.1 - }, - "10": { - "questions_with_evidence": 10, - "mean_evidence_recall": 0.275, - "all_evidence_hit_rate": 0.1 - }, - "20": { - "questions_with_evidence": 10, - "mean_evidence_recall": 0.325, - "all_evidence_hit_rate": 0.1 - }, - "50": { - "questions_with_evidence": 10, - "mean_evidence_recall": 0.5, - "all_evidence_hit_rate": 0.4 - }, - "100": { - "questions_with_evidence": 10, - "mean_evidence_recall": 0.8, - "all_evidence_hit_rate": 0.8 - } - }, - "searched_questions": 10, - "skipped_questions": 0, - "empty_results": 0, - "mean_returned_records": 100.0, - "questions_with_evidence": 10, - "evidence_audited_questions": 10, - "questions_with_unmatched_gold": 1, - "mean_evidence_recall": 0.8, - "all_evidence_hit_rate": 0.8, - "search_p50_seconds": 0.7971748809999326, - "search_p95_seconds": 5.029391450999924 - }, - "4": { - "evaluation_eligible_questions": 50, - "evaluation_coverage": 1.0, - "answer_failed_questions": 0, - "judge_failed_questions": 0, - "evaluation_pending_questions": 0, - "scored_questions": 50, - "mean_local_judge_score": 0.56, - "mean_token_f1": 0.31756828321258174, - "mean_bleu1": 0.2188586736858274, - "mean_budget_evidence_recall": 0.73, - "attribution_audited_questions": 50, - "ambiguous_evidence_records": 0, - "unmapped_evidence_records": 0, - "processed_questions": 50, - "evidence_recall_at_k": { - "1": { - "questions_with_evidence": 50, - "mean_evidence_recall": 0.365, - "all_evidence_hit_rate": 0.36 - }, - "5": { - "questions_with_evidence": 50, - "mean_evidence_recall": 0.54, - "all_evidence_hit_rate": 0.52 - }, - "10": { - "questions_with_evidence": 50, - "mean_evidence_recall": 0.62, - "all_evidence_hit_rate": 0.6 - }, - "20": { - "questions_with_evidence": 50, - "mean_evidence_recall": 0.64, - "all_evidence_hit_rate": 0.62 - }, - "50": { - "questions_with_evidence": 50, - "mean_evidence_recall": 0.705, - "all_evidence_hit_rate": 0.68 - }, - "100": { - "questions_with_evidence": 50, - "mean_evidence_recall": 0.73, - "all_evidence_hit_rate": 0.72 - } - }, - "searched_questions": 50, - "skipped_questions": 0, - "empty_results": 0, - "mean_returned_records": 100.0, - "questions_with_evidence": 50, - "evidence_audited_questions": 50, - "questions_with_unmatched_gold": 0, - "mean_evidence_recall": 0.73, - "all_evidence_hit_rate": 0.72, - "search_p50_seconds": 0.9332325589999755, - "search_p95_seconds": 2.51959695000005 - } - }, - "source_attribution": { - "mapped_records": 8700, - "ambiguous_records": 0, - "unmapped_records": 0 - }, - "diagnostic_bucket_counts": { - "full_budget_evidence_judge_correct": 43, - "full_budget_evidence_judge_incorrect": 25, - "missing_budget_evidence_judge_correct": 5, - "missing_budget_evidence_judge_incorrect": 13, - "no_gold_evidence_labels_judge_correct": 1 - }, - "diagnostic_question_ids": { - "full_budget_evidence_judge_correct": [ - "conv-26#q0000", - "conv-26#q0005", - "conv-26#q0006", - "conv-26#q0010", - "conv-26#q0011", - "conv-26#q0012", - "conv-26#q0013", - "conv-26#q0015", - "conv-26#q0020", - "conv-26#q0021", - "conv-26#q0031", - "conv-26#q0034", - "conv-26#q0035", - "conv-26#q0044", - "conv-26#q0045", - "conv-26#q0046", - "conv-26#q0057", - "conv-26#q0065", - "conv-26#q0066", - "conv-26#q0070", - "conv-26#q0071", - "conv-26#q0076", - "conv-26#q0078", - "conv-26#q0080", - "conv-26#q0081", - "conv-26#q0082", - "conv-26#q0085", - "conv-26#q0086", - "conv-26#q0091", - "conv-26#q0094", - "conv-26#q0095", - "conv-26#q0096", - "conv-26#q0099", - "conv-26#q0102", - "conv-26#q0108", - "conv-26#q0110", - "conv-26#q0111", - "conv-26#q0112", - "conv-26#q0113", - "conv-26#q0115", - "conv-26#q0117", - "conv-26#q0119", - "conv-26#q0122" - ], - "full_budget_evidence_judge_incorrect": [ - "conv-26#q0003", - "conv-26#q0008", - "conv-26#q0019", - "conv-26#q0022", - "conv-26#q0025", - "conv-26#q0026", - "conv-26#q0027", - "conv-26#q0029", - "conv-26#q0033", - "conv-26#q0048", - "conv-26#q0050", - "conv-26#q0056", - "conv-26#q0060", - "conv-26#q0063", - "conv-26#q0067", - "conv-26#q0068", - "conv-26#q0075", - "conv-26#q0077", - "conv-26#q0079", - "conv-26#q0083", - "conv-26#q0084", - "conv-26#q0092", - "conv-26#q0101", - "conv-26#q0116", - "conv-26#q0126" - ], - "missing_budget_evidence_judge_correct": [ - "conv-26#q0002", - "conv-26#q0007", - "conv-26#q0073", - "conv-26#q0090", - "conv-26#q0127" - ], - "missing_budget_evidence_judge_incorrect": [ - "conv-26#q0028", - "conv-26#q0049", - "conv-26#q0069", - "conv-26#q0072", - "conv-26#q0089", - "conv-26#q0098", - "conv-26#q0103", - "conv-26#q0104", - "conv-26#q0105", - "conv-26#q0114", - "conv-26#q0118", - "conv-26#q0120", - "conv-26#q0124" - ], - "no_gold_evidence_labels_judge_correct": [ - "conv-26#q0024" - ] - }, - "evaluation_failures": [], - "request_diagnostics": [ - { - "route": "/add", - "status": 200, - "reason": "unclassified", - "attempts": 28, - "retried_attempts": 0, - "elapsed_seconds": 446.279112673 - }, - { - "route": "/add", - "status": 503, - "reason": "write_not_readable", - "attempts": 5, - "retried_attempts": 5, - "elapsed_seconds": 45.629824593999956 - }, - { - "route": "/search", - "status": 200, - "reason": "unclassified", - "attempts": 87, - "retried_attempts": 0, - "elapsed_seconds": 105.47749603799934 - } - ], - "limitations": [ - "One complete history; not a representative estimate of all AML dimensions.", - "qwen-plus is a mutable alias and is used for both answering and judging.", - "Prompt/rubric and lexical scoring are maintained by this project.", - "Exact-content provenance cannot identify rewritten memories.", - "Budget-evidence presence does not establish sufficient semantic context.", - "Native dataset scores and official AML scores are not reproduced.", - "No raw memory, question text, reference answer, prediction or credentials included." - ] -} diff --git a/agent_memory_leaderboard/benchmarks/baselines/README.md b/agent_memory_leaderboard/benchmarks/baselines/README.md deleted file mode 100644 index 25d2fe2..0000000 --- a/agent_memory_leaderboard/benchmarks/baselines/README.md +++ /dev/null @@ -1,23 +0,0 @@ -# Recorded self-run baselines - -These reports contain aggregate metrics, nonsecret configuration, source IDs and -synthetic probe observations. Full datasets, retrieved text, gold answers, model -predictions, private cache and credentials are excluded. - -| Report | Evidence | -|---|---| -| [LoCoMo / Qwen Plus, 2026-10-07](2026-10-07-locomo-qwen-plus.json) | [Actions run](https://github.com/matrixorigin/memory_benchmarks/actions/runs/37594716119): one complete history, 87 scored text questions, 100% coverage; local judge 49/87, Recall@100 0.8023 | -| [Dev probes, 2026-10-07](2026-10-07-dev-probes.json) | Four source-time scenarios and 20 bounded Search calls, followed by separate owner-scoped Explain reads | - -These are self-run diagnostics, not AML scores or native evaluator equivalents. -The judge and answer model both use the mutable `qwen-plus` alias. One history -does not represent the full benchmark or all AML capability dimensions. Gold -source presence does not guarantee sufficient answer context. - -Reproduce the baseline with **Actions → AML benchmark**, `main`, `locomo`, -`answer-eval`, `histories=1`, `top_k=100`, and the recorded model/prompt/budget -configuration. Reproduction also requires the recorded deployed service versions; -the workflow always calls the current service and does not select a past image. -Use the [workflow guide](../CI.md), [pinned local data commands](../textual/locomo_refined/README.md) -and [design/acceptance plan](../../docs/competition-plan.md#干净端到端基线2026-10-07) -for details, diagnostic interpretation and pending work. diff --git a/agent_memory_leaderboard/docs/competition-plan.md b/agent_memory_leaderboard/docs/competition-plan.md deleted file mode 100644 index 015bf93..0000000 --- a/agent_memory_leaderboard/docs/competition-plan.md +++ /dev/null @@ -1,1213 +0,0 @@ -# AML 文本赛道：共建方案与工作计划 - -## 工作范围 - -团队在 [matrixorigin/memory_benchmarks](https://github.com/matrixorigin/memory_benchmarks) 共建参评适配、评测和部署工程，基于同事现有实现继续开展工作。本文是后续方案与设计决策的维护入口；更新有效章节，区分已实现、待实施和验证证据，不记录中间讨论。 - -根目录 [README](../../README.md) 是新成员的项目入口，沿用英文，集中说明用途、当前架构、 -公网 Add/Search 最小示例、手动评测及部署步骤、数据集支持范围和指标语义。 -运维凭据／发布细节由 `deploy/README.md` 维护，评测参数／产物／保留规则由 -`benchmarks/CI.md` 维护，本文维护设计及验收状态。首页支持表区分可执行检索、接口诊断、 -未取得数据和未接入原生评分；不以数据集目录存在或 workflow 成功表述正式 AML 分数。 - -此前独立的 Memoria `feat/aml-text-adapter` 分支、`aml-local-client` 和相关优化／评测计划停止推进。已有代码、PR、文档和结果保留为参考，不删除或关闭；不以完成旧计划或迁入旧实现作为新项目的前置条件。后续是否采用其中的代码或用例，由新项目的具体任务决定。 - -## QA 复用与评测负载边界 - -目标部署位置为 `~/moi/moi-gitops` 管理的 IDC QA 环境。复用既有 Memoria -和 MatrixOne，只新增 `memory_benchmarks` 的 Add/Search 适配服务及独立 journal PVC、 -认证和 Ingress；共享 Memoria 更新由 GitOps 管理。benchmark runner 按需在本地或 Actions 执行。 -GitOps 配置已通过 [moi-gitops PR #810](https://github.com/matrixorigin/moi-gitops/pull/810) 合入 main； -合并提交为 `048fff0e3f5eede4c1a21ed4efbe396068de1028`。独立 worktree 为 `~/moi/moi-gitops-qa-aml`。 -共享 QA Memoria 已于 2026-10-08 升级至 0.5.2，源码为准备部署时最新 main `6247235e27bc62898b122473dafae084bea61c80`； -复用现有密钥、embedding 和已存在的 `memoria_shared` / `mem_u_*` 数据库。 -配置显式启用多库模式，避免引用已不存在的旧 `moi_memoria` 库或触发 legacy 迁移。 -QA 适配器已部署，真实 Add/Search、幂等重放、未认证 401 和跨用户隔离检查通过。 -工作站访问 QA HTTPS `/health`、`/ready` 均为 200；未据此宣称已验证独立公网网络。 -共享注册用户由 54 增至 56（两个人工验收身份），API key 仍为 10；未替换原有运行密钥。 -跨仓库镜像 PR 发布入口仍待实施；benchmark workflow 仅访问 QA，旧阿里云 dev 直部署 workflow 已移除。 -QA 发布入口应构建适配层镜像后向 GitOps 提 PR， -不把旧阿里云直部署 workflow 的 kubeconfig 换成 QA，也不在 benchmark 仓库复制共享 Memoria 的数据库或主密钥。 -Pulumi scoped preview 因无关 catalog 的输出 checksum 漂移而拒绝发布；首次更新采用 -仅针对两个已审核 Deployment 的资源版本校验 JSON patch，随后同步 Pulumi 状态。 -合并后的标准 GitOps 发布已将 QA Memoria 同步至上述固定镜像，版本 0.5.2、Pod Ready， -真实 Add/Search、重放幂等及跨 owner 隔离再次通过。标准发布操作整个 idc stack， -首次合并发布的 [Pulumi Up](https://github.com/matrixorigin/moi-gitops/actions/runs/37757891714) 已结束， -因 `moi-zhongding/moi-catalog` CrashLoopBackOff、等待 Ready 超时而失败。Memoria 与适配器 -已完成更新并通过上述验收；服务验收与整轮工作流结果应分别判断。 -scoped Actions deploy 尚未独立验收，不能据标准全栈发布推断其已通过。 -日常发布须使用包含 QA 覆盖配置的 main 版本；重跑旧提交可能回退共享 Memoria 的镜像。 -详细部署、接入和验收依据见 GitOps `docs/handbooks/qa-aml-adapter.md`。 -后文阿里云 dev 的部署记录仍属于已有环境，应与 QA 区分。 - -### 资源归属与发布链路 - -```mermaid -flowchart LR - B["memory_benchmarks 手动发布"] --> I["构建适配层镜像并记录 digest"] - I --> PR["向 moi-gitops 提 PR"] - PR --> R["Preview / Review / 合并"] - R --> G["moi-gitops: Pulumi Up / idc"] - G --> A["aml-qa 适配服务"] - C["本地 / benchmark Actions / AML"] --> N["QA NGINX Ingress + TLS"] - N --> A - A --> J["独立 journal PVC"] - A --> M["现有 QA Memoria"] - M --> D["现有 MatrixOne"] - M --> E["现有 embedding 服务"] -``` - -| 项目 | 部署设计 | -|---|---| -| 发布配置所有者 | `moi-gitops`；同一 Kubernetes 资源只由该项目管理 | -| Stack / unit | `idc` / 独立 unit `aml-qa`，依赖现有 `memoria` unit，先完成后端发布 | -| Namespace | `moi-aml-qa`，不将适配器混入已有 `moi-qa` release | -| 应用 | 新增原生可选组件 `aml-adapter`，独立 chart / Helm release | -| Memoria 连接 | 已验证 `http://moi-memoria.moi-memoria.svc.cluster.local:8100`，使用原生 Memoria-Owner 认证 | -| 数据库、embedding | 由现有 Memoria 管理；适配器不注入数据库密码或 embedding key | -| 数据身份 | `MEMORIA_NAMESPACE=aml-qa-v1`，结合 run-scoped user 产生隔离 owner；不代表资源隔离 | -| 应用规格 | 初始 1 Pod、1 worker；CPU request 250m / limit 1，内存 request 256Mi / limit 1Gi，按观测调整 | -| journal | 新建 5Gi RWO PVC，storageClass 根据 QA 实际配置选择；Recreate，保留 PVC 并记录备份/回滚操作 | -| 镜像 | `registry.cn-hangzhou.aliyuncs.com/moc-pub/plugin:aml-memory-adapter-YYYYMMDD-SHORTSHA`；部署按 `repository@sha256:...` 固定 | - -GitOps 分支已新增 `aml-adapter` unit 组件、配置模型、chart source、 -部署与 preview 入口及 values 合并支持。适配器 chart 从当前已验证 Deployment / -Service / Ingress 配置整理而来，仅包含适配器资源；不直接接管 dev 中同时包含 -Memoria 的完整 chart，也不为此新建一套 Memoria 或数据库初始化任务。 - -**待实施的发布入口**：`memory_benchmarks` 新 workflow 仅手动发布已审核的 main 版本：构建适配层镜像、 -推送、记录 source SHA / digest / 构建链接，再向 GitOps 发布分支创建英文 PR。 -目标分支须核实仓库默认分支及团队约定；现有 `up.yaml` 支持 main/dev 并映射至 idc。 -不直接提交目标分支、不自动合并、不从该仓库执行 `kubectl apply` 或 `pulumi up`。 -首次 GitOps PR 增加组件和 unit；日常镜像 PR 仅修改 -`values/idc/aml-qa/aml-adapter.yaml` 的镜像及版本记录。 - -### Ingress、域名与证书 - -拟定外部基础地址： - -```text -https://aml-qa.moi.shanghai.idc.matrixorigin.cn:30443 -``` - -该地址从工作站访问 HTTPS 健康和就绪检查均已通过；独立公网可达性、长请求链路仍待验证。`values/idc/qa/moi-core.yaml` -中已有 QA 入口使用 HTTPS `:30443`；Ingress host 字段只填域名，不包含协议或端口。 -如果外部网络已具备标准 443 映射，验收后可使用不带端口的基础地址。 -不自动沿用阿里云 dev 的域名、DNS IP、ClusterIssuer 或已有 Eval Key 绑定。 - -Ingress 规划： - -- namespace 为 `moi-aml-qa`，`ingressClassName: nginx`，host 为上述域名。 -- 独立 Service ClusterIP 80 → gateway 8080 → loopback adapter 8000；Memoria 只通过集群内地址访问。 -- `/add`、`/search`、`/health`、`/ready` 使用原始路径，精确路由，不增加统一前缀或 rewrite。 - Add/Search 保持应用 Bearer 认证，不接入浏览器 SSO，也不公开 Memoria 管理路径。 -- 保留 Authorization / JSON body；不缓存 Add/Search，不启用代理层上游重试。 -- read/send timeout 初始沿用 1800 秒、body-size 64MiB、关闭请求缓冲；对整个网络链路 - 核实超时上限，Ingress 参数不能证明前置 NAT/LB/代理允许长请求。 -- `/health` 保持轻量存活探针；`/ready` 检查 journal 与上游健康。正式验收另做真实 - 数据库写入和检索，避免把 `/ready=200` 当成数据库可写证明。 - -TLS 复用 `values/idc/moi-tls.yaml` 中现有 `dnspod` ClusterIssuer、 -`*.moi.shanghai.idc.matrixorigin.cn` 泛域名证书及自动续签链路。 -`moi-aml-qa` 匹配既有 replicator 的 `moi-.*` 规则；Ingress 引用本 namespace 中 -实际同步成功的 `moi-wildcard-tls`。发布前检查证书 Ready、SAN 覆盖、有效期和 -secret 同步，不将私钥提交 Git，不另建 ACME 账号或重复签发控制器。 - -DNS 核实该域名是否已由现有泛解析覆盖；未覆盖时新增 A/CNAME，指向 QA Ingress -实际对外入口。不能照抄阿里云 dev 的 `47.97.230.53`，也不能将 ClusterIP 或 -Pod IP 写入公网 DNS。须从本地和 GitHub-hosted runner 所在网络验收 DNS、 -`:30443` 连通性和公开受信任 TLS；若仅内网可达，先补外部入口再作为 AML 地址。 - -### Secret 与 workflow 权限 - -| 使用位置 | 所需凭据 | 配置方式 | -|---|---|---| -| memory_benchmarks 镜像构建 | ACR push 凭据 | GitHub Actions Secret，尽可能限定镜像仓库权限 | -| memory_benchmarks → GitOps PR | 跨仓库 GitHub App installation token；无法使用时采用受限 PAT | 对目标仓库授予分支写入与 PR 权限；修改 workflow 文件时按实际权限要求单独处理 | -| GitOps 部署 | 既有 idc 集群身份与 Pulumi 凭据 | 沿用 `moi-gitops` 既有环境配置，不复制到 benchmark 仓库 | -| QA 适配器 | 独立 ADAPTER_API_KEY | 在 GitOps 私密配置中管理，渲染为 namespace 内 Secret | -| QA 适配器 → Memoria | 现有 Memoria 可用的 owner/master credential | 按现有认证方式核实；只将必需字段安全注入本 namespace，不复制整份 QA Secret | -| 本地 / benchmark runner | QA adapter key；Answer/Eval 模型 key | QA 使用独立仓库 Secret `AML_QA_ADAPTER_API_KEY`；模型 key 不注入适配服务 | - -普通单仓库 `GITHUB_TOKEN` 不能假定拥有另一个私有仓库的写权限。 -Secrets 不写入明文 values、PR body、镜像层或 artifact；沿用 Pulumi encrypted -config / namespace Secret 管理。Kubernetes Secret 不支持跨 namespace 引用， -须在 `moi-aml-qa` 安全注入所需 Memoria 凭据，不能直接引用 `moi-memoria` 中的 Secret。 - -### 负载保护、冻结与版本记录 - -- 初期启用一个活跃业务请求的 admission gate，并对适配器发往 Memoria 的请求 - 支持可配置速率上限，QA 验收初始建议每秒 1 个后端 HTTP 请求；这不是每秒 - 1 个 Add 批次。根据真实业务指标逐步提高。worker=1 本身不提供请求串行保证。 - GitOps 分支已通过独立 NGINX gateway 实现这些保护，QA 使用同步到 ACR 的固定镜像以避免运行时拉取 Docker Hub；过载返回 429 / Retry-After， - 不改 AML JSON 请求/响应格式。 -- benchmark workflow 仅使用 QA 固定地址和独立 adapter key；旧阿里云部署 workflow 已移除。 - 不提供 dev 选项，不注入旧环境的 key；结果记录 adapter - digest、共享 Memoria digest、数据哈希和实际模型配置。 -- GitHub concurrency group 只在同一仓库内生效，不能靠两个仓库写同名 group 实现 - benchmark 与 GitOps 发布互斥。最低方案为 GitOps 侧可检查的持久冻结状态：评测 - 前先冻结并确认没有在途部署，再启动；评测结束由责任人确认后解除。 -- 既有 `up.yaml` 在合并到 main/dev 后执行整个 idc stack。实施时须增加只含 AML - 资源变更的 preview 审核，冻结期间拒绝变更适配器及其共享 Memoria 依赖；不能 - 只在 memory_benchmarks 中设置一个变量就宣称 GitOps 发布已被阻止。 -- QA 日常发布可能更新共享 Memoria 或 embedding。正式 AML Full 前需协调这些 - 依赖的版本冻结；若无法协调，应采用独立服务/资源，而不能把共享 QA 视作固定版本。 -- 首次 QA 使用全新 journal 和运行用户，不把 dev journal、旧断点或旧主密钥直接 - 复制过去。切换后运行真实验收；回滚保留 journal，回退上一适配器 digest，并核实 - journal schema 的向后兼容性。清理评测数据不得影响正常 QA 用户。 - -### 实施顺序与验收 - -1. **只读预检**：核实 QA kube context、Memoria Service/版本/认证/API、数据库可写、 - 存储类/配额、IngressClass/入口/端口、TLS secret、目标 GitOps 分支和现有凭据。 -2. **GitOps 基础 PR**：新增 `aml-adapter` 组件、独立 `aml-qa` unit、Deployment / - Service / PVC / Secret / Ingress 和环境覆盖；preview 确认没有计划替换现有 - QA Memoria、MatrixOne 或业务资源；本次另外允许更新共享 Memoria 镜像与显式多库配置， - 其余 QA 业务资源应保持不变。 -3. **发布入口 PR**：在 memory_benchmarks 增加构建镜像并向 GitOps 提 PR 的 workflow； - 接入 QA benchmark 目标选择、来源记录、限速/并发保护及 GitOps 冻结检查。 -4. **基础验收**：Pod/PVC Ready；域名+TLS 正常；未授权 Add/Search 401；真实 Add - 成功后 Search 可读；相同 request_id 重试幂等；原始 JSON 契约不变。 -5. **容量验收**：先 18 条消息 / 2 题最小样例，再一段完整 LoCoMo；观察 QA 业务 P95、 - 数据库/应用/embedding 指标后扩容。长请求 >5 分钟、发布排空和 journal 持久性 - 单独在受控条件验证，不用高负载掩盖基础可用性问题。 -6. **目标切换**：验收通过后更新本地配置、workflow 和官方登记地址（若已有绑定需重绑）。 - 原 dev 环境保持至切换确认；停用旧资源与数据清理作为独立操作，不随新部署执行。 - -### 实际请求放大与规模 - -当前 runner 按历史、Add 批次和问题串行执行，适配器在一个 Add 内逐条写入记忆。 -每个成功的新记忆分片正常执行一次 store、一次 GET 读回、一次 Search 可见性校验； -题目检索另发 Search。因此不能把一次 Add HTTP 请求等同于一次数据库 INSERT。 -Memoria 内部还会执行索引、检索及统计等操作，下面计数是 Memoria HTTP 调用的 -正常成功路径下限，不是 SQL 条数；重试、恢复、初始化与后台任务另计。 - -2026-10-08 对本地已下载的固定版本 LoCoMo-Refined / LongMemEval-S，使用当前 -label-free renderer、UTF-8 分片规则和 batches 代码离线统计： - -| 范围 | Add 批次 | 写入记忆分片 | 文本问题 | Memoria HTTP 调用下限 | -|---|---:|---:|---:|---:| -| LoCoMo 第一段完整历史 | 28 | 419 | 87 | 1,344 | -| LoCoMo 全量 10 段历史 | 399 | 5,882 | 861 | 18,507 | -| LongMemEval-S 第一段历史 | 69 | 550 | 1 | 1,651 | -| LongMemEval-S 全量 500 段历史 | 34,019 | 246,755 | 500 | 740,765 | - -调用下限按 `3 × 记忆分片数 + 文本问题数` 计算。LoCoMo 全量另外跳过 521 道 -多模态题；第一段历史跳过 51 道。LongMemEval 的一条历史本身包含很多会话， -题目数量不能作为写入规模的代理。 - -1024 维 float32 embedding 的裸向量容量，LoCoMo 全量约 24 MB，LongMemEval-S -全量约 1.01 GB；它们不含正文、数据库向量实际编码、索引、元数据、日志、冗余及 -其他表，不代表实际磁盘占用。当前每次新运行生成新的用户身份，重复实验会累计数据； -保留策略字段不等同于已实现物理删除。 - -### 复用条件与运行边界 - -- 仓库的 `charts/memoria/values.yaml` 默认单副本、CPU limit 1、内存 limit 2Gi； - `values/idc/memoria.yaml` 指向共享 `moi-memoria` / `moi_memoria`。这些是配置证据， - QA 已验证使用 0.5.2、多库 `memoria_shared` / `mem_u_*` 和真实读写；数据库余量及当前业务负载仍待观测。 -- 独立 adapter namespace 和 run-scoped owner 隔离数据身份，不隔离 Memoria 的 CPU、 - 内存、连接池、数据库计算、存储 I/O 或 embedding 服务额度。 -- 先核实 QA Memoria 的 owner 认证、metadata、query/search API 和镜像版本兼容性。 - 健康接口返回 200 不足以证明数据库读写成功；须真实 Add/Search 验收。 -- 初始仅允许一轮评测运行，采用串行、限速方式，从 18 条消息的最小链路测试扩展到 - LoCoMo 一段完整历史；记录业务 P95、数据库 CPU/内存/连接/慢查询、Memoria - 资源与错误率、embedding 延迟，结合 QA 原有基线决定是否扩大。 -- 当前普通 runner 串行但没有显式 QPS 上限，也不能阻止其他客户端或官方评测并发。 - QA gateway 已限制一个活跃 Add/Search 和每秒一个后端业务请求；跨仓库评测互斥和 Actions 目标选择尚未完成。 -- 长时间全量 LongMemEval-S、并行跑多个数据集、官方 Full，须在验证余量后安排 - 维护窗口或隔离资源。独立 Memoria 实例能隔离应用资源，复用同一个数据库实例 - 仍会共享数据库资源；真正的容量隔离还需数据库租户/计算资源限额或独立实例。 -- 本地 Answer/Eval 的模型调用直接访问模型提供方，不直接增加 Memoria 数据库读写； - retrieval-only 则会去掉模型等待间隔，可能使题目检索阶段请求更密集。 - -### QA benchmark 配置与最小验收 - -手动 **QA memory benchmark** 仅在 main 执行，固定访问 QA，不再提供阿里云 dev 选项。 -旧阿里云直部署 workflow 已移除，PR／push 不会从本仓库部署到该集群。 -固定地址与独立 QA key 配套使用，不注入旧 dev key。当前账号无 GitHub Environment 管理权限，采用独立命名的仓库 Secret -`AML_QA_ADAPTER_API_KEY`，已从 QA runtime Secret 安全配置；不复制后端 Master Key、 -数据库、embedding、kubeconfig 或 Pulumi 凭据。 - -`profile=histories` 保留原有完整历史评测。`profile=minimal` 仅支持 LoCoMo、histories=1： -先核验原始固定数据，再提取首个完整会话与原始顺序中证据全在此会话的前两道文本题。 -日期、正文和说话人不变，记录原始和派生文件 SHA256。该档用于连接、认证、写入、检索和 -可选作答／判分验收，不代表完整历史，不作为算法质量基线。 - -2026-10-08 从本地运行当前分支的相同 prepare / execute / summary 路径，访问 QA HTTPS： -18 条消息、1 个 Add 批次、2 道文本题完成，Search 无空结果，证据召回率 1.0。 -qwen-plus 回答／判分均成功，评分覆盖率 1.0；本地 judge 为 1 对 / 1 错，Token F1 -约 0.5208、BLEU-1 约 0.4154。以上是两题最小链路结果，不是 AML 官方分数或完整质量基线。 -原始数据、模型正文、可恢复 cache 和密钥留在忽略的 var 目录。 - -Summary 与 JSON 记录目标、URL、profile、数据哈希、范围和可选后端版本备注。 -`runtime_label` 仍是操作者提供、未经自动在线验证的记录；本次验收备注来自实际 Deployment -镜像 digest。GitHub-hosted runner 的网络路径需要合入 main 后手动选择 QA 验证，不能用 -本地通过代替。QA 并发组只串行本仓库评测，不与 moi-gitops 跨仓库互斥；发布仍需协调。 - -首次 Actions 建议 minimal + locomo + retrieval；成功后可用 answer-eval 或 -histories=1 的完整历史。完整历史预计至少约 1,344 个后端请求，初始 1 RPS 限制下仅 -请求调度下限约 22.4 分钟，真实耗时还包含 embedding、SQL、模型和重试。 - -## 参评赛道与多模态边界 - -本项目参评范围为 **Textual Memory（文本记忆）**。AML 官方将文本、代码、多模态 -作为独立评测类型；文本赛道关注长对话、跨会话事实、多跳关系、时间、个性化、规则、 -记忆治理及 Streaming，图像／Base64 内容数组属于多模态赛道。 -范围依据：[AML 官方文档与参赛说明](https://agentmemories.ai/zh-cn/docs)，2026-10-06 核对。 - -当前不增加图片存储、视觉模型或图文检索。公开 LoCoMo-Refined 同时含多模态题目， -本项目的文本诊断按原始 `is_multi_modality` 标记跳过这部分题目，单独报告跳过数量， -不计作文本检索失败、不进入召回率分母。该公开数据筛选是本地评测的实现，不能据此 -认定完全复现 AML 内部选题或评分；正式文本 Full 的任务范围以官方配置为准。 -后续评测扩展仅纳入文本任务和文本能力回归，不要求多模态或代码赛道能力。 - -参赛组别与模型要求仍需按最新官方材料对齐。2026-10-07 核对时，官方 Full checklist -已写 Open-source Methods 的 Add 阶段期望使用 `gpt-4o-mini`；赛事 FAQ 仍采用 -学术／工业分类，学术榜 embedding 指定 `text-embedding-v4`，LLM 组件指定 -`gpt-4o-mini`，reranker 不限制；开放权重模型建议工业榜。 -不能继续笼统写“模型规则完全未出现”，也不能自行将两套组别名称等同。上海 bge-m3 -的正式参评资格、纯存储且不调用 LLM 的 Add 是否适用该要求，仍需官方明确；当前 -运行配置是开发验证配置，不作为合规确认。[官方文档](https://agentmemories.ai/zh-cn/docs)、 -[赛事 FAQ](https://agentmemoryleaderboard.ai/competition/) - -## 历史阿里云 dev 部署参考 - -本节保留既有部署工程和历史验收依据；旧直部署 workflow 已移除，相关旧 workflow -操作步骤不再适用。当前 QA 的有效配置、发布归属和 benchmark 入口以前述 QA 章节为准。 -服务已迁移至 QA IDC；ACR 镜像和 qwen-plus / DashScope 模型依赖继续使用。 - -CI/CD、Memoria 部署模板和自动证书配置已合入 `memory_benchmarks` 的 `origin/main`。 -**Memoria 与适配器已部署到阿里云 dev，公网 HTTPS 和真实 Add/Search 最小联调通过。** -具体运行、实际 SHA／digest 和剩余验收范围见[当前交付状态](#当前交付状态)。 -部署操作、Actions 参数及可复制的公网 curl／Python 示例见 -[发布与接入说明](../../deploy/README.md#发布流程)和[Add/Search 接入](../../deploy/README.md#接入已部署的-addsearch)。 - -### 完成状态 - -| 部分 | 代码／配置状态 | 已执行的工作 | 待验证／待完成 | -|---|---|---|---| -| 离线 CI | 单个 `checks` job 执行 Ruff、pytest、Helm lint／template、适配器镜像构建、Go Pulumi 检查；八个健康探针用例；不构建 Memoria | PR #9 的 CI 通过，pytest 为 280 passed、1 warning；Helm 检查及适配器镜像构建通过 | 当前提交以 PR checks 为准；CI 不推送镜像或部署 | -| benchmark workflow | 手动选择 LoCoMo／LongMemEval-S、固定数据校验、Answer/Eval、Summary 与 artifact；Recall@K 及逐题审计 | 新契约 LoCoMo 首个完整历史：28 Add／87 Search／87 判分全部完成；自建 judge 56.32%，Recall@100 80.23% | 扩大无标签基线、人工抽查裁判与失败样本；无正式 AML 分数 | -| dev CD | main 手动 preview／deploy、冻结检查、单项更新选择；独立 build／deploy runner；自动部署默认关闭 | 首次完整 CD 及固定镜像单项更新成功，适配器 Pod 保留 | 新版源码模式端到端发布仍待验收 | -| Memoria 部署 | 源码／现成镜像模式、分支选择、版本记录及数据库／embedding 配置 | main 源码产物以固定 digest 更新成功，新 Pod Ready，单项更新保留适配器 | 源码构建与部署的 runner 磁盘预算、未知写入恢复仍待验收 | -| Add/Search 部署 | Deployment、Service、journal PVC 和 `/ready` | PVC Bound；公网真实 Add/Search 七项最小联调通过 | 持久性、未知写入恢复及容量仍待验收 | -| 数据库 | 专用用户／角色／共享库初始化及动态用户库授权 | 权限边界、共享及用户 schema 初始化、真实写入／检索通过 | 恢复及保留期限／物理清理仍待验收 | -| GitHub 配置 | 运行凭据／环境变量配置，上海 embedding key 为必填 | 本次部署验证集群、Pulumi、ACR、数据库及应用认证链路 | 未来凭据轮换与权限变更重新验收 | -| HTTPS | Ingress、Certificate 和证书 Ready 等待 | DNS 与入口匹配，证书 Ready，公网健康检查和 Add/Search 通过正常 TLS 校验 | 真实 SLB 长请求超时仍待验收 | - -已有完整构建验证见 [Actions run 37452656686](https://github.com/matrixorigin/memory_benchmarks/actions/runs/37452656686)，对应 `c54dc53`，2026-10-06 检查和当时的 Memoria 源码构建 job 均通过，pytest 为 154 passed、1 warning。当前离线 CI 只保留 `checks`，Memoria 源码构建由发布 workflow 执行，后续提交的验证以对应 PR checks 为准。上述离线记录本身不证明上线；实际发布证据见当前交付状态。 - -交付范围包括 `.github/`、`deploy/`、`/ready`、测试和本目录方案文档；后续变更继续通过 PR -交付到 `origin/main`。实际 dev 配置、凭据和本地运行产物排除提交。 - -## 本地质量闭环与诊断设计 - -实现与操作说明统一见[评测与诊断](../benchmarks/EVALUATION.md)；Actions 配置见 -[benchmark workflow](../benchmarks/CI.md)。以下能力已合入 `origin/main`（PR #9），首个 -无标签契约的真实端到端小集已完成，见下文；不能以旧运行结果作为新契约的验收证据。 - -### 输入隔离与来源归属 - -runner version 2 只写入原始文本、角色、speaker 和来源日期；不把来源 ID、gold、 -`answer_` session 标签、QA 摘要或 judge 规则写入记忆。LME 使用中性本地 session ID， -映射不进入 Add/Search。共享纯函数保留原适配器的 role/time header 和 UTF-8 分片规则， -由此生成本地 SHA256 来源 manifest。wire 请求／响应字段和后端存储语义不变。 - -检索结果按完整内容 hash 匹配。无法匹配或多个来源存在相同内容时，不猜测归属， -不计来源命中，并单独报告 unmapped／ambiguous 数。一个 LME session 内重复文本仍 -可唯一归属该 session。该诊断方法适用于当前保留原文的 Memoria 适配器；改写型记忆 -系统必须另行实现可靠的来源归属，不能直接把 hash 不匹配等同于检索失败。 - -脱敏、改写或多消息合块实验的前置任务是稳定 memory ID 到 request／message／part -及 source-unit 集合的私有映射，包含恢复与生命周期；合块允许多个来源。当前未实现 -该映射，不以 hash 方案支持所有粒度实验。诊断映射不得进入比赛 Search 返回或模型 -可见正文。LoCoMo 两名 human speaker 原始无 role 标注，均以 user 写入并保留姓名； -不将任意一人标为 AI assistant，其他数据集显式角色按原值保留。 - -新契约拒绝旧标签运行的 resume，使用新的 run UUID；旧结果可读，但不与新输入 -直接做算法优劣比较。gold 异常标签仍原样披露，不在这轮自动修正。 - -### 可选 Answer/Eval - -默认 retrieval 仅调用 Add/Search。answer-eval 为 LoCoMo／LongMemEval-S 增加独立的 -OpenAI-compatible 回答／裁判客户端，凭据不经过适配层。模型、endpoint、temperature、 -prompt/scorer version、token encoding、输入／输出预算进入运行契约；密钥不进入报告。 -gold 只进入评分器／裁判，不进入回答模型。按 LME 问题类别使用不同的本地 rubric， -LoCoMo 显示 Token F1 与 BLEU-1；本地 judge 明确不宣称原生评分器等价或官方 AML 分数。 -原生 evaluator 对齐和正式模型资格确认仍是独立验收项。 - -本地开发回答与裁判均选择百炼北京端点 -`https://dashscope.aliyuncs.com/compatible-mode/v1` 的 `qwen-plus`，便于复用已有服务。 -GitHub Actions 的 4 个模型／端点 Variables 与 2 个 API_KEY Secrets 已于 2026-10-07 -配置并回读确认，密钥不入库；示例 env 同步该非秘密配置。未因此执行真实模型验证或 -建立质量基线。该配置仅作用于 benchmark 进程，不改变已部署 Memoria、embedding -或官方 Answer/Eval，也无须重新部署服务。下一次小集选择 answer-eval、LoCoMo -1 个完整历史、Top K 100。回答与裁判同模型仅用于本地诊断，不证明独立评分或官方 -等价；qwen-plus 是可更新别名，跨日期算法对比需固定可用快照及其他实验变量。 - -预算为包含指令、角色、问题、选项／问题日期、证据的整个回答输入，上限 117760， -按固定 o200k_base 加 256 token 余量计数；它是本地近似，不保证等于任意模型的实际 -chat template/tokenizer。保留完整证据排名前缀，不跳过较大前置记录挑选后面的证据。 -报告预算内来源召回和上游 token usage；实际输入超过预算时失败。实际 usage 在响应后 -取得，因此此检查不能避免所有超限调用成本。正式可比基线前仍需确认模型计数契约。 - -上下文使用二分前缀与完整请求计数缓存，将编码次数降为 O(log N)；最终仍核验完整 -请求，不假定各记录 BPE token 可简单相加。选择、重试、解析版本写入 evaluation -契约；旧 answer-eval 断点不跨版本混用，retrieval 契约不变。 - -回答／裁判的网络错误与 429／5xx 最多尝试 4 次，退避 0.5／1／2 秒，429 数字 -Retry-After 上限 30 秒。严格 JSON 裁判支持完整代码块；无效返回、截断、预算超限 -或重试耗尽按题记录 answer_failed／judge_failed 并继续，认证／地址错误 -401／403／404／405 及存储／程序异常仍停止整轮。失败题保留 pending 可续跑，已保存 -回答的 judge 重试不重复生成答案，也不重复 Add／Search；成功题跳过。 - -有待评失败题时最终 partial 且退出码 1。Summary 显示 scored／eligible／pending、 -评分覆盖率和两类失败数；覆盖率排除多模态、missing-gold skip。均值按各指标有效值 -统计，judge 失败仍可保留有效词法分数，不把模型故障计成错误答案，也不隐藏覆盖缺口。 - -回答正文及检索上下文只存 private cache，用于 judge 失败后的续跑；artifact 只保存 -答案 hash、数值指标与安全诊断。CI private cache 在 artifact root 外，不上传。 -本地 pending 续跑需要保留该 cache，CI artifact 本身不包含完整 Answer/Eval 恢复材料。 -缓存、backend/journal 都受作业保留要求约束，不依赖 artifact 过期完成清理。 - -### 重试观测与增量断点 - -每个 Add/Search HTTP attempt 都记录固定状态／原因码、耗时、是否重试和请求标识 hash， -不持久化 headers、原始 payload、响应正文或异常文字。Summary 展示中间尝试，便于 -定位恢复后的 503；不因记录了 503 就推断索引延迟或未知写入。重试集合、最多六次尝试 -和相同 Add request_id 的恢复语义保持原状。 - -当前原因码仍依赖固定状态／文案，未知文案计 unclassified；新增机器可读 code 是 -独立兼容性任务，本次不改变官方错误响应契约。 - -每题独立文件使用私有权限与原子替换，运行中 header 不再包含不断增长的 questions； -最终报告合并一次，保留现有读取方式。resume／硬中断 Summary 合并完整题目文件； -请求日志可修复尾部撕裂写。Search 完成先落 pending 断点，回答缓存成功后才进入 judge； -进程在模型结果持久化前中断仍可能重做该模型调用。 - -### 时间回归与容量工具 - -`src.probes` 默认只生成计划，不发送请求；显式 execute 才运行隔离的合成用例。 -时间用例带实际 AML 毫秒 timestamp，覆盖旧、近期、新旧混合和 T1 假设阈值两侧。 -可选直接 owner-scoped Explain 只保存允许的路径 flags、数量和时延；它是另一次请求， -不宣称必然与此前公开 Search 同路径。不修改 observed_at 或置信度衰减行为。 - -容量工具限制逻辑请求数、并发、QPS、输入字节和调度时长，报告各 route 延迟及错误。 -逻辑 QPS 不包含内部重试，调度到期不取消已在途的写入。DB／模型压力、物理存储增长 -需要配合基础设施指标另行测量。只有实际一次成功 HTTP attempt 超过五分钟，才标记 -长请求链路验证通过；多次短重试累计超时不计通过。 - -验收状态：新契约已完成 LoCoMo 首个完整历史、四组时间探针和 20 次低负载 Search。 -这不代表最大容量、未知写入恢复、长请求或正式 AML 验收通过。后端幂等契约、 -embedding 实际 token 上限、原生评分和正式验收继续按 Issue #1 推进。 - -离线验证：完整 pytest 280 passed、1 warning（既有 Starlette 弃用警告），Ruff 与 -actionlint v1.7.7 通过；相较原有 179 项增加 101 项。专项用例覆盖六个新增核心模块 -的边界、模型失败隔离与续跑，以及 Summary 覆盖率； -CI 安装锁定的 evaluation extra，以 --no-sync 保留测试依赖。使用模拟 HTTP 和本地 -确定性编码，不将离线通过当作真实 embedding／模型质量或 SLB 容量的证据。 - -### 干净端到端基线（2026-10-07） - -[Actions run 37594716119](https://github.com/matrixorigin/memory_benchmarks/actions/runs/37594716119) -在 `main@003dda1` 执行 `locomo / answer-eval / histories=1 / top_k=100`，完整历史为 -`conv-26`。数据 revision／SHA256 固定于 `ci-datasets.json`；输入不含诊断来源标签。 -Memoria 为 `81c5cc6`，适配器为 `3048f6b`，实际 digest 见官方接入材料；评测前后 -Pod UID 与镜像保持一致、Ready 且重启次数为 0。回答／裁判均使用 `qwen-plus`， -temperature=0，prompt `memory-answer-v1`，scorer `local-dataset-judge-v1`。 -该 alias 可变化，同模型裁判也可能有偏好，不能当作不可变的长期基准。 - -| 指标 | 结果与分母 | -|---|---| -| 执行状态／耗时 | completed，919.14 秒，约 15.32 分钟；不含准备和安装 | -| Add／Search | 28／28 批次、87／87 道文本题成功；51 道多模态题跳过 | -| 判分覆盖率／模型失败 | 87／87，100%；answer_failed=0，judge_failed=0，pending=0 | -| 自建 judge 通过率 | 49／87，56.32%；不是 AML 或原生 evaluator 分数 | -| Token F1／BLEU-1 | 0.2674／0.1773；项目词法实现，范围 0–1、越大越好 | -| Recall@100／全部证据命中率 | 80.23%／79.07%；86 道有正证据标签的问题 | -| Recall@1／5／10／20／50 | 37.21%／57.27%／64.83%／67.15%／74.13% | -| 预算内召回 | 80.23%；所有题目均保留 100 条记录，没有因预算删去证据 | -| 上下文 token | 本地估算 4881–6612；上游实际 prompt 为 4917–6700，均低于 117760 | -| 来源匹配 | 8700／8700 条返回记录匹配；ambiguous=0、unmapped=0 | -| 空结果／gold 标注异常 | 0／1；`conv-26#q0028` 的原始合写证据标签保留计分 | -| Search P50／P95 | 0.93／2.95 秒 | - -28 个成功 Add 之前共发生 5 次 HTTP 503，涉及 4 个逻辑批次，全部经原样重试恢复。 -安全诊断均为 `write_not_readable`，对应写入返回后 GET 回查未找到记录；不是 -`write_outcome_unknown` 或 `write_not_searchable`。这已缩小排查范围，但不能据此 -确认 embedding 故障、数据库一致性根因或需要改变重试策略。 - -失败诊断以“标注证据是否进入预算”分组：68 道题全部标注证据可见，其中 judge -通过 43、未通过 25；18 道题缺部分或全部标注证据，其中通过 5、未通过 13； -另 1 道无正证据标签的题通过。优先人工核查那 25 道题，区分回答错误、缺少标注 -之外的衔接上下文、时间表达／列表要求及裁判误判。标注来源出现不保证事实足够， -也不能将其全部归因于 LLM 或裁判；CI artifact 未保存原始回答，不能宣称已完成人工复核。 -需要审查实际生成文本时，在受控环境保留 private cache，或明确标记为复现实验。 - -此结果建立一个历史的项目内部基线，不能证明总体比赛质量，也不能与旧标签输入 -直接比较算法提升。尚无根据全局修改 Memoria 算法或开启 reranker。 -聚合指标、配置、失败分组题目 ID 见 -[固定基线报告](../benchmarks/baselines/2026-10-07-locomo-qwen-plus.json)；原始报告与 -断点在该 Actions artifact，按既有 30 天保留策略管理，不提交数据正文、gold 或回答。 - -### 时间与低负载探针验收（2026-10-07） - -LoCoMo 结束后串行执行 `src.probes`，使用全新用户及合成文本。时间探针的旧、近期、 -新旧混合和阈值两侧四组共 4 Add／12 Search，16 次请求全部成功。其独立 Explain -复查只读取对应 owner；观察结果如下： - -| 场景 | 公网 Search 的来源命中 | 独立 Explain 复查 | -|---|---|---| -| 旧记忆单独存在 | 3／3 次命中旧记忆 | 3／3 为 fulltext，混合路径无结果后回退 | -| 近期记忆单独存在 | 3／3 次命中近期记忆 | 未额外 Explain | -| 新旧混合 | 3／3 只返回近期，含一次旧文本精确查询 | 3／3 为 hybrid，旧记忆仍 active；observed_at 为 2022 年、created_at 为本次写入时间 | -| T1 假设阈值两侧 | 3／3 只命中较新一侧 | 3／3 为 hybrid，两个原始记录仍 active | - -源码按部署的 `81c5cc6` 核对：混合检索按 observed_at 计算时间与置信度，在 -`MIN_CONF=0.05` 下过滤；混合结果非空时不会进入后续全文回退。该组合与复查结果 -一致，确认当前配置存在历史来源在新旧混合时不可见的适配风险。独立 Explain 是另一次 -读取，不声称它必然复现此前每个公网请求的路径，也不据此认定通用 Memoria 衰减设计错误。 -LoCoMo runner 的日期仅进入正文，没有发送 AML timestamp；这项风险不能用于解释 -本轮 LoCoMo 的 56.32% judge 分数。 - -下一项时间实验应在适配边界比较“来源时间”与“置信度年龄”的解耦，保持原始时间 -进入证据和 metadata、用于日期理解与时序推理，不丢弃或改造原始时间。冻结其他 -条件后重复上述回归；在实验通过前不全局关闭 Memoria 衰减，也不把该风险标为已修复。 - -低负载 Search 探针配置为 concurrency=2、逻辑 QPS 上限 1、20 次 Search，加 1 次 -seed Add；全部成功、无重试，Search P50／P95 为 2.38／3.84 秒，总耗时 32.32 秒。 -该 QPS 是调度上限，实际完成吞吐约 0.62 Search／秒（含 seed 时间），不是最大容量。 -没有单次成功请求超过 5 分钟，SLB 长请求验收仍待完成。合成记忆保留在隔离用户下 -供复查，私有清理清单位于 ignored probe 报告，不以本次成功声称完成物理清理。 - -诊断工具已修复 `safe_explain` 遗漏合法 `hybrid` 路径的问题；仅补安全输出白名单， -不修改检索、时间或 Add/Search wire 契约。新增 8 个路径白名单回归用例，完整 pytest -288 passed、1 个既有 warning，Ruff 通过。安全聚合结果见 -[探针报告](../benchmarks/baselines/2026-10-07-dev-probes.json)。 - -## 源码导航 - -| 入口 | Review 内容 | -|---|---| -| [离线 CI](../../.github/workflows/aml-ci.yml) | 触发条件、依赖锁定、检查／构建步骤和独立于发布凭据的运行范围 | -| [旧 dev 发布参考](../../deploy/README.md) | 分支限制、并发、Secret 使用、镜像 digest、preview／deploy、证书等待及临时文件清理 | -| [Memoria 来源配置](../../deploy/memoria-source.json)、[镜像选择与记录](../../deploy/scripts/memoria_image.py)、[构建 Dockerfile](../../deploy/docker/memoria.Dockerfile) | 默认 main、分支／tag／commit 选择、实际 SHA 与 digest、编译器／运行镜像和构建缓存 | -| [Pulumi 程序](../../deploy/pulumi/main.go)、[配置模板](../../deploy/pulumi/Pulumi.new-dev.example.yaml)、[私有配置生成](../../deploy/scripts/dev_config.py) | 目标集群、私有标识、独立 stack、资源所有权、DSN 编码、Secret 传播、PVC 保护与 Helm 依赖 | -| [更新范围选择](../../deploy/scripts/deployment_target.py)、[Pulumi 配置选择](../../deploy/pulumi/selection.go)、[选择回归用例](../../deploy/tests/test_deployment_target.py) | 首次完整发布、未选应用版本／配置保留、共享凭据与 chart 变动检查、构建后复查 | -| [Memoria 模板](../../deploy/chart/templates/memoria.yaml) | 镜像入口、非 root／只读文件系统、显式多库、共享库连接与授权、模型环境变量及健康探针 | -| [适配器模板](../../deploy/chart/templates/deployment.yaml)、[Service](../../deploy/chart/templates/service.yaml) | 单副本 Recreate、journal 挂载、Secret checksum、请求结束与重启行为 | -| [Ingress](../../deploy/chart/templates/ingress.yaml)、[Certificate](../../deploy/chart/templates/certificate.yaml) | NGINX 路由、长请求配置、TLS Secret 名和现有 ClusterIssuer 的引用 | -| [集群检查](../../deploy/scripts/preflight.py) | API Server／UID 校验、权限与存储检查、域名范围和 Issuer Ready 条件 | -| [数据库初始化](../../deploy/scripts/bootstrap_db.py) | 管理员配置解析、专用用户／角色的权限、重复执行和凭据保留 | -| [GitHub 配置脚本](../../deploy/scripts/configure_github.py) | 固定仓库和目标集群、stdin 上传及错误输出中的凭据保护 | -| [适配器源码](../src/app.py) | 新增 `/ready` 的开销、失败行为和健康状态语义 | -| [冻结检查](../../deploy/scripts/deployment_guard.py)、[Helm 渲染](../../deploy/scripts/render_chart.py)、[ready 用例](../tests/test_ready.py) | 冻结输入校验、两组非秘密渲染配置，以及健康／失败返回码 | -| [发布操作说明](../../deploy/README.md) | 必填配置、执行步骤、外部依赖和验收流程 | - -Review 使用源码、部署模板、非秘密配置及已记录的执行证据。管理员 `.env`、`deploy/.runtime.env` 和 kubeconfig 包含真实凭据，不纳入方案或 Review 产物。 - -### Review 重点 - -1. **工作流能否执行**：Actions 表达式、依赖／版本、Go 编译、镜像构建、digest 传递和 Pulumi 参数是否一致。离线 CI 及首次完整 CD 的镜像发布、digest 传递和 Pulumi 执行已通过，实际版本见当前交付状态。 -2. **发布范围是否正确**：只操作指定 unit 集群及独立 stack；集群身份检查、应用 namespace、共享资源引用和删除保护是否完整。 -3. **Memoria 能否启动并供适配器调用**：固定镜像是否具备普通 `/v1/memories` 路径所需的 owner、metadata 和 query 能力；运行参数、schema 初始化、数据库角色权限和 embedding 环境是否满足该版本。 -4. **状态与恢复是否可靠**：SQLite 单写者、PVC 绑定／权限、Recreate、发布中断、凭据更新及已有 journal 的保留；确认 `protect` 不等价于备份或恢复方案。 -5. **公网链路是否成立**：域名、DNS solver 范围、Certificate／Secret／Ingress 关联和 Ready 等待；SLB 与 NGINX 的真实长请求限制仍需验收。 -6. **验证边界是否清楚**：`/ready` 只覆盖 journal 可读及上游健康接口；新数据库登录成功不证明 Memoria 迁移或 Add/Search 可用。既有比赛质量／幂等问题按下文独立跟踪。 - -### 部署架构 - -```mermaid -flowchart LR - AML["AML 客户端"] -->|HTTPS| NG["现有 NGINX 与应用 Ingress"] - subgraph APP["已部署：aml-memory-benchmarks namespace"] - A["Add/Search：aml:80"] --> M["Memoria：aml-memoria:8100"] - A --> J["journal PVC：20Gi"] - C["应用 Certificate 与 TLS Secret"] - end - NG --> A - M --> DB["现有 MatrixOne：专用共享库与动态用户库"] - M --> EMB["上海 BAAI/bge-m3 服务"] - CM["现有 cert-manager 与 ClusterIssuer"] --> C - C --> NG -``` - -Memoria 默认从源码 `main` 分支构建，由本项目 CD 部署，也可指定分支、tag、commit 或现成镜像；源码构建、镜像推送、dev 部署及公网 Add/Search 最小联调已通过。构建适配由本仓库 Dockerfile 完成，运行问题驱动的 Memoria 两项修复已另行合并并部署，见后文。数据库引擎、模型服务、NGINX 和证书控制器是既有基础设施。详细设计和资源边界见下文，具体配置与操作见发布说明。 - -## 当前工程与职责 - -同事原始审查版本为 `b037c42`；当前评测代码为 `origin/main@003dda1`，运行结果分别 -关联各自的 benchmark commit 和实际后端镜像。完整逐项结论见 -[Issue #1 当前核实结论](review-issue-1.md)，不将旧版问题列表直接当作当前任务状态。 - -| 部分 | 职责与当前状态 | -|---|---| -| `memory_benchmarks/agent_memory_leaderboard` | 已有 FastAPI Add/Search、SQLite 幂等 journal、隐私保护、断点执行、多数据集解析和检索诊断 | -| Memoria | 作为记忆存储与检索后端；当前适配器调用普通 `/v1/memories` 接口 | -| 自建质量评测 | 已实现 Answer/Eval、Recall@K、预算内证据、模型失败隔离及评分覆盖率；真实基线与官方评分分别验收 | -| AML 平台 | 调度参评接口并统一回答、评分；本次没有运行官方评测 | - -以现有 FastAPI 适配器为后续工作基础。协议适配、数据集执行、评测和报告在本项目维护；只有新项目确认需要后端能力或修复时，才安排相应 Memoria 修改。当前并未切换到此前 Memoria `/aml/*` 路由，也未迁入其来源策略、原子幂等或邻接补全。 - -## 已确认问题与实施顺序 - -详细事实、条件与 review 表述修正见 [Issue #1 核实结论](review-issue-1.md)。该文档是核实记录，不代表其中建议已实施。 - -1. **接收实际运行材料**：确认同事使用的 Memoria commit／镜像、模型与配置、失败状态及完整性汇总。私人结果被 gitignore 排除，clone 缺少结果不能证明从未运行。 -2. **保证输入与写入可信**：隔离模型可见的诊断 ID／答案来源标签；核查来源时间触发的过滤；处理不确定且未提交写入的恢复，以及 token／字节边界。需逐项确认实现位置与验收条件，不通过等待后盲目重发保证幂等。 -3. **建立本项目质量闭环**：Answer/Eval、Recall@K、预算内证据、失败与时延汇总已合入；在真实 Memoria 和 embedding 环境建立固定小集基线。按数据集选择适用评分规则；模型可见输入不含 gold 或诊断标签。 -4. **按失败原因做实验**：一次改变一个因素，对照粒度／邻接／排序，再决定 options、rerank 或 query rewriting。检索到更多内容、填满预算或具备更多模块均不能单独作为质量提升证据。 -5. **完成容量与正式验收**：测量写入吞吐，核查批量接口语义与重试，验证部署、认证、数据清理和公网可达性；核对组别与冻结契约，再安排官方 Smoke／Full。 - -## 评测与方案边界 - -- 旧 Memoria 分支的 LoCoMo 150 题和七维开发结果属于旧路径与已记录镜像，不作为本项目成绩。采用旧用例或工具后也须通过本项目重新运行。 -- 同事 README 记录过无 embedding 的真实 HTTP smoke，且存在重复运行失败；尚不能据此认定 embedding 质量、稳定性或正式部署完成。 -- 来源时间、接收时间与事件时间须区分。普通 Memoria 路径中的年龄过滤可能使历史来源无法通过 Add 探针；最终处理设计在对应修复任务中明确，不能仅靠返回后重排解决。 -- 超时不证明未提交，回查暂时为空也不证明旧调用不会迟到提交。写入恢复必须说明幂等边界和重复处理。 -- 自动 Judge 需保留逐题证据与争议，不能用一个未经验证的裁判分数代替可信质量结论。 -- 正式模型、预算、排序、重试和配额按 AML 所选组别的有效契约核对；开发配置和自建 Answer/Eval 不自动等价于官方评测。 - -## 运行与发布方案 - -### 部署范围 - -**部署目标是阿里云 dev unit 集群，CI/CD 全部维护在 `memory_benchmarks`。** 本地 Compose 继续用于开发。本项目部署专用 Memoria 和 Add/Search 适配器，使用独立数据库登录用户与专用数据库；公网由目标集群现有 NGINX Controller 和 Kubernetes Ingress 接入。生产 `memoria-website` 的 Memoria／MatrixOne 不作为评测后端。 - -| 位置 | 当前职责 | -|---|---| -| `memory_benchmarks/agent_memory_leaderboard` | 维护 FastAPI Add/Search、幂等 journal、数据集执行、评测和报告 | -| `memory_benchmarks/.github/workflows/aml-ci.yml` | 离线 lint、既有单元／契约测试和 Docker 构建检查；不推送镜像或触发部署 | -| `deploy/README.md` | 旧阿里云 dev 发布参考；活动 workflow 已移除 | -| `memory_benchmarks/deploy` | 独立 Go Pulumi project、Helm chart、集群检查及一次性数据库初始化脚本 | -| 阿里云 dev unit | 运行独立 Memoria 和适配器；复用现有 MatrixOne、CSI 与 NGINX | -| 本地 Memoria 和 MatrixOne | 独立评测后端；通过已有 Compose 或明确配置的开发实例运行 | -| `memoria-website` | 继续承担生产网站与原服务的职责；本项目没有新增发布流程或共享 Ingress 路由 | - -### 阿里云环境与资源所有权 - -2026-10-06 通过 gitops 源码、Pulumi 已保存状态及用户提供的 `~/dev/unit-kubeconfig` 核对环境： - -| 项目 | 已确认事实／选择 | -|---|---| -| gitops `new-dev` | 多个 Pulumi project 的环境名；基础设施、组件、cloud-service 和 cos-resources 各自管理独立 stack | -| 控制面集群 | `cos-infrastructure/new-dev` 导出 `controller-plane-clusterID`；`cloud-service/new-dev` 已保存状态记录 `moi-main/moi-memoria`，属于 Astra 共用后端 | -| 本项目目标 | 用户提供的 **unit 集群**，与上述控制面不同；API Server 和 `kube-system` UID 固定在本项目 dev 配置中 | -| 目标集群实况 | Kubernetes `v1.28.9-aliyun.1`，19 个 amd64 节点；本次未发现 Memoria Deployment | -| 公网入口 | 现有 `nginx` IngressClass，`kube-system/nginx-ingress-lb`，当前公网 IP `47.97.230.53` | -| 持久存储 | 已确认 `alicloud-disk-essd-pl0`，WaitForFirstConsumer；journal 使用 20Gi RWO PVC | -| 数据库服务 | dev `freetier-01`，有 `proxy:6001` Service；运行 DSN 配置为 `proxy.freetier-01.svc.cluster.local:6001` | - -采用 **`MatrixOneCloud/memory-benchmarks/new-dev`** 独立应用 stack，namespace 为 `aml-memory-benchmarks`；该 stack 尚未初始化。首次 preview／deploy 使用 upsert 创建 stack。该 stack 管理 Memoria、适配器、运行／拉取 Secret、journal PVC、Service、可选 Ingress 和应用 Certificate。集群、数据库引擎、NGINX、公网负载均衡器及 cert-manager／ClusterIssuer 由现有基础设施／运维管理。应用 workflow 直接部署本项目，不触发整套 gitops `cloud-service/new-dev` 发布，不接管共享资源。 - -### 数据库、认证与模型 - -现有 dev MatrixOne 租户内使用独立 **SQL 登录用户** `aml_memoria`、角色 `aml_memoria_role` 和共享库 `aml_memoria`。运行用户名显式选择该角色；不新建整个 MatrixOne account。管理员凭据仅用于本地初始化。角色拥有共享库及其表的权限，并具有 `CREATE DATABASE ON ACCOUNT *`，以支持 Memoria 动态创建用户库。新库及表由创建时的运行角色拥有，不授予 `accountadmin`、全局表读写或租户级删库权限。权限模型见 [MatrixOne GRANT](https://docs.matrixorigin.cn/en/v26.3.0.13/MatrixOne/Reference/SQL-Reference/Data-Control-Language/grant/)。 - -专用用户、角色和数据库已创建，并通过该用户完成登录及库名回查。运行密码、独立 Memoria master key 和适配器 API key 位于 gitignore 排除的 `deploy/.runtime.env`，权限 `600`。管理员配置保留在用户指定文件，仅用于一次性初始化，不进入 Pod 或持续发布 Secret。数据库初始化不删除既有数据、不重设既有用户密码；恢复使用同一份凭据文件。 - -Memoria 内部 Service 为 `aml-memoria:8100`；适配器使用该 Memoria 的 master key，并为 AML 用户映射稳定 owner。master key 与 AML 对外 API key 相互独立；向 AML 平台提供适配器 key。调用者携带 `Authorization: Bearer ` 并提交 `user_id`；适配器对 `[namespace, user_id]` 做稳定哈希，以内部 `Memoria-Owner` 认证和 `X-User-Id` 调用 Memoria。无需预注册 Memoria 用户或逐用户生成 API key；首次需要用户存储时由 DbRouter 按需创建用户库。SQL 运行用户仍须由部署初始化脚本预先准备。Add/Search 应保持相同 `user_id`；重试不能改变 owner 前缀或用户标识。 - -接入说明以公网 Add/Search 为最小客户端边界，提供 curl 和 Python 标准库示例、请求字段及 -响应结构。普通客户端只持有适配器 key，不持有 Memoria master key、数据库或集群凭据。 -示例使用随机用户隔离演示数据，不自动清理；完整 `src.smoke` 才额外访问内部 Memoria， -执行认证范围核对和测试记忆逻辑停用。示例用于接口联调，不替代正式 AML 重试、超时和评测契约。 - -#### 数据库模式与部署兼容性 - -源码基线 `matrixorigin/memoria@e180dff` 的自动迁移是既有设计：[PR #178](https://github.com/matrixorigin/memoria/pull/178) 实现旧配置的拓扑检测与迁移，[PR #188](https://github.com/matrixorigin/memoria/pull/188) 明确将全新环境切到多库，并包含对应测试。比赛工程应适配这一设计，不修改 Memoria 启动语义来维持当前模板的单库假设。 - -| 控制项 | 当前上游语义 | -|---|---| -| `MEMORIA_MULTI_DB=1/true` | 直接按多库启动，跳过旧库自动检测／迁移 | -| `MEMORIA_MULTI_DB=false/0` 或未设置 | 进入自动拓扑检测；不构成强制单库开关 | -| `DATABASE_URL` | 自动检测时的旧库／初始库连接 | -| `MEMORIA_SHARED_DATABASE_URL` | 多库共享库连接；未设置时从 `DATABASE_URL` 推导为 `memoria_shared` | -| 数据库现有状态 | 全新环境进入多库；已迁移环境直接使用多库；旧数据环境先迁移再切换 | -| `MEMORIA_DB_NAME` | 数据库名称配置，不是强制单库开关 | - -已核对 `memoria-website/memoria_aws` 的部署模板：显式设置 `MEMORIA_MULTI_DB=1`，并将 `DATABASE_URL` 和 `MEMORIA_SHARED_DATABASE_URL` 配成同一共享库连接。该事实来自部署源码，不代表本次读取了线上 Pod 的实际配置。 - -部署显式设置 `MEMORIA_MULTI_DB=1`，`DATABASE_URL` 和 `MEMORIA_SHARED_DATABASE_URL` 引用同一 Secret 中的专用 `aml_memoria` 连接，避免使用默认 `memoria_shared` 或触发旧库迁移。Memoria 根据 owner 派生 `mem_u_<16位hash>` 用户库；SQL 连接持续使用专用角色，由它创建库、初始化表并获得对象所有权。初始化脚本可幂等补齐建库授权，保留现有运行密码和 API key。 - -**权限边界：** `CREATE DATABASE` 是租户级建库能力，无法仅授权 `mem_u_` 前缀。该角色可以新建其他名称的数据库；namespace／owner 哈希用于应用数据分区，不构成 SQL 名称限制。现有非授权业务库的数据仍应不可访问，计算容量和租户资源仍共用。需要硬性租户隔离时应另建 MatrixOne account；本方案不宣称已有完整租户隔离。 - -2026-10-06 已在指定 dev MatrixOne（报告版本 `v4.2.0`）幂等补齐授权，保留原凭据。使用专用角色验证共享库 `CREATE DATABASE IF NOT EXISTS`、新建临时用户库／表、CRUD、ALTER、索引和自有库删除；读取、更新及删除管理员角色创建的另一个临时库均被拒绝（错误码 `20101`）。仅使用随机命名的测试库和合成数据，结束后已清理，未读取其他业务库。该检查证明本次所测 SQL 操作和权限边界，不代表所有 Memoria 功能均已验证。 - -当前实际镜像的共享及用户 schema 初始化、首次 Add/Search 已通过真实联调，重启恢复仍须验收。权限检查不替代 HTTP 路径、embedding 或质量评测。本项目只调整比赛部署配置和初始化授权，不修改 Memoria 的数据库路由或启动语义。 - -embedding 默认沿用 gitops dev 配置：上海 OpenAI-compatible `BAAI/bge-m3`、1024 维。其网络、认证、预算及真实检索质量需要联调确认；当前发布配置不要求 LLM 或 rerank，实际 Add/Search 路径没有调用 Answer/Eval 或 Observe 抽取。镜像均固定 digest，不混用不同 embedding 模型的既有向量。 - -上海 embedding 的公网接口需要鉴权。2026-10-06 从本机以正常 HTTPS 校验向 `https://bgem3.model.shanghai.idc.matrixorigin.cn:30443/v1/embeddings` 发送单条短文本、`model=BAAI/bge-m3` 的无 key 请求，返回 HTTP `401`、`{"error":"Unauthorized"}`，约 0.071 秒。结论限定为该接口不接受匿名调用，尚未验证有效 key、1024 维输出或 dev Pod 网络。发布使用 `AML_EMBEDDING_API_KEY`，由服务维护者提供有效 key；workflow 和 Pulumi 都要求其非空，缺失时不继续发布。模型调用仍需带 key 验收，`/ready` 不替代该验收。 - -### CI/CD 凭据边界与配置 - -离线 CI 无须手工配置 Secret，也不 checkout Memoria；发布 workflow 的公开 Memoria 源码 checkout 使用 Actions 自动提供的 `GITHUB_TOKEN`。dev preview／deploy 均需要八个必需凭据：Repository Secrets `KUBECONFIG`、`PULUMI_TOKEN`、`AML_DATABASE_PASSWORD`、`AML_MEMORIA_MASTER_KEY`、`AML_ADAPTER_API_KEY`、`AML_EMBEDDING_API_KEY`，以及本仓库可访问的 Organization Secrets `NEW_ACR_USERNAME`／`NEW_ACR_PASSWORD`。来源、填写方法和当前准备状态统一列于 [发布说明的 Secrets 表](../../deploy/README.md#secrets)。 - -`KUBECONFIG` 存储用户提供的阿里云 unit 完整原始 YAML，不存本机路径或 base64；workflow 写临时文件供 Kubernetes provider 使用，结束时清理。`PULUMI_TOKEN` 映射为 `PULUMI_ACCESS_TOKEN`，只用于独立应用 stack 的 Pulumi Cloud 访问。ACR 凭据用于镜像推送并生成 namespace 内的拉取 Secret。数据库密码、master key、对外 adapter key 和 embedding key 进入 `aml-runtime`，按需供各 Pod 使用；数据库运行 DSN 使用专用用户，由 Pulumi 编码和生成。管理员数据库密码不进入持续发布。 - -环境标识使用 `AML_EXPECTED_API_SERVER`、`AML_EXPECTED_CLUSTER_UID`、`AML_DATABASE_ACCOUNT` 三个 Repository Variables，已从现有私有配置上传。仓库只提交 `Pulumi.new-dev.example.yaml`；本地实际 `Pulumi.new-dev.yaml` 被 gitignore 排除。CD 生成同一格式配置，preflight、初始化和凭据上传脚本继续读取该文件，保留集群及租户身份检查，不增加 Secret 数量。公开前仍须按基础设施披露要求检查文档和脚本中的其他环境信息。 - -2026-10-06 GitHub 名称元数据显示六个必需 Repository Secrets 均已存在，包括用户配置的 embedding key，两个组织 ACR Secrets 已对本仓库开放；当前没有缺失的必需 Secret 名称。这里只核对名称元数据，不读取密钥值，不等价于有效性或权限验证。`AML_ADAPTER_REPOSITORY`／`AML_MEMORIA_REPOSITORY` 均配置为共享 `moc-pub/plugin` 仓库，供现成镜像模式使用的 `AML_MEMORIA_IMAGE` 也已保存；源码模式与 main 默认值来自已编写的来源配置，其余非秘密参数按发布说明填写。 - -当前应用 Pulumi 只操作 Kubernetes，复用已有证书控制器与 Issuer，不将阿里云 RAM AccessKey、DNS 签发凭据或证书私钥加入本仓库 CI。DNS 凭据由基础设施管理。当前 Add/Search 发布不需要 LLM／rerank key，也不自动调用官方评测。正式参评时提供给 AML 的认证值是 adapter key，上游 Memoria master key 在内部使用。 - -### Kubernetes Ingress 公网方案 - -访问链路为 **AML → HTTPS 域名 → unit 集群 NGINX → 适配器 Service → 内部 Memoria**。本项目新增自己的 Ingress，使用 `nginx` 类；公共路由覆盖 `/add`、`/search`，对 Memoria 保留 ClusterIP 内部入口。 - -证书自动化复用现有 **cert-manager + `aliyun-prod-letsencrypt` ClusterIssuer**。已核实 cert-manager `v1.12.1` 的 controller、webhook、cainjector 均有可用副本，生产和 staging Issuer 均为 Ready；应用 CD 不安装或升级共享控制器，旧版本维护由基础设施负责人处理。Issuer 的 DNS-01 webhook 配置范围为 `cn-dev.matrixone.tech`，应用域名需位于该范围；其他域名需要提供对应的有效 Issuer。 - -启用公网时设置明确域名，并配置 DNS 指向 NGINX 公网地址。chart 声明专用 Certificate，cert-manager 自动申请、保存及续期 TLS Secret；发布等待 Certificate Ready。证书私钥由集群控制器管理，CI/CD 不负责重复签发或更新该 Secret。Let’s Encrypt 当前默认有效期为 90 天，足以覆盖一个月比赛；以真实 `notAfter` 为准并保留自动续期。[cert-manager DNS-01](https://cert-manager.io/docs/configuration/acme/dns01/)，[证书有效期](https://letsencrypt.org/docs/cert-lifetimes/) - -公网域名选定为 `aml.cn-dev.matrixone.tech`，GitHub Repository Variable `AML_PUBLIC_HOST` 已设置，A 记录已配置。部署后的公开入口为 `https://aml.cn-dev.matrixone.tech/add` 与 `https://aml.cn-dev.matrixone.tech/search`。应用 Ingress 与证书已创建，正常 TLS 校验下的公网健康检查和 Add/Search 最小联调已通过。[Kubernetes Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/) - -DNS 使用独立的 `cn-dev.matrixone.tech` 阿里云解析区域，已核对其 NS 为 `ns1.alidns.com`／`ns2.alidns.com`。域名管理员已配置 `aml` 主机的 A 记录。2026-10-06 使用公共解析器 `223.5.5.5` 的 TCP 查询返回 `NOERROR`、`47.97.230.53`、TTL 600 秒；同次只读核查的 unit NGINX LoadBalancer IP 也为 `47.97.230.53`。后续入口 IP 变化时维护该区域的记录，不在父域的其他解析系统中创建替代记录。 - -现有应用 CD 管理 Ingress 和 Certificate，cert-manager 管理 DNS-01 验证及证书续期；它们不会自动创建业务 A 记录。当前未发现 unit 集群的 ExternalDNS Deployment，A 记录由域名管理员一次性配置并维护，DNS 管理凭据不进入本项目 CI。阿里云也支持通过有权限的 CLI／API 或既有基础设施流程创建记录。[阿里云 DNS API](https://www.alibabacloud.com/help/en/dns/api-alidns-2015-01-09-adddomainrecord) - -Ingress 配置 1800 秒读／发送超时，并关闭上游自动重试。正式参评前还需核查 SLB、NGINX 控制器限制、请求体大小与整批 Add 的真实时长；不能据此声明整个链路已满足所有 AML 30 分钟请求。本项目不将控制面 `mocloud-alb` 的路由或监听器配置复制到 unit 集群。 - -### 本地运行与配置 - -现有 [Docker Compose overlay](../compose.adapter.yaml) 接入 Memoria 自身的 Compose 网络，将适配器绑定到 `127.0.0.1:8000`，通过 `http://api:8100` 调用本地后端。启动方式见 [项目 README](../README.md#docker-deployment-with-memoria)。本次没有启动本地服务或执行真实 Add/Search；运行前核对实际 `.env` 中的 Memoria URL、数据库地址及模型配置。 - -| 配置 | 用途 | -|---|---| -| `MEMORIA_URL` | 指向评测专用 Memoria，不使用生产端点 | -| `MEMORIA_MASTER_KEY` | 上游认证；沿用评测实例自身的配置，不能复用生产凭据作为默认值 | -| `ADAPTER_API_KEY` | 独立适配器认证，客户端用于调用 Add/Search | -| `ADAPTER_STATE_DIR` | 持久保存 journal 和锁文件；Compose overlay 使用 `/app/var` 命名卷 | -| `MEMORIA_NAMESPACE` | 稳定的评测 owner 前缀；同一次运行／恢复不随意更改 | -| `MEMORIA_TIMEOUT_SECONDS` | 当前默认单次上游调用 120 秒，不代表整批 Add 的总时长 | -| Memoria embedding／LLM 配置 | 配置于评测后端；质量联调与正式参评分别核对模型要求，不混用不同模型的既有向量 | - -`/health` 为异步轻量路由，直接检查事件循环存活，不占用 Add/Search 的同步线程池。`/ready` 检查 journal 可读和 Memoria `/health`，使用独立 HTTP 连接与线程容量；每个 worker 最多一个检查，并发探针直接返回 503，不排队，也不写入记忆或调用模型。ready 不能证明 master key、embedding、Add/Search 和重试恢复正确；这些能力需要真实联调验收。 - -### 离线 CI - -PR、main push 或手动触发 **CI - Lint, Tests & Adapter Build** 时，执行依赖锁定安装、Ruff、pytest、固定版本 `actionlint v1.7.7` 的 workflow YAML／Actions 表达式检查、Helm lint／template、适配器镜像构建及 Pulumi 程序编译／测试，统一在 `checks` job 中执行；适配器镜像不推送到 registry，离线 CI 不 checkout 或构建 Memoria。Helm 检查使用假镜像 digest、模型 URL 和域名，覆盖内部入口／单 worker，以及公网 Ingress／Certificate／两个 worker。workflow 不引用集群、Pulumi、ACR 或跨仓库发布 Secret，不自动运行真实 HTTP smoke、LLM 基准或官方 Smoke／Full。这里的离线指不调用真实业务／评测接口，依赖安装和本仓库 checkout 仍需要网络。 - -Memoria 是独立来源仓库，日常适配器、评测或文档变更不重复编译它。其源码构建只在 -**AML Aliyun dev deployment** 选择更新 `both`／`memoria`、且有效模式为 `source` 时执行； -`preview` 和 `deploy` 均构建并推送。仅更新适配器或使用现成镜像时跳过。 -源码构建成功并取得 digest 后才继续发布，构建失败阻止更新。若显式启用 main push -自动发布，则该发布运行也遵循此规则；普通合并触发的离线 CI 不构建 Memoria。 - -### 手动 benchmark workflow - -独立 `.github/workflows/aml-benchmark.yml` 使用 GitHub hosted runner 执行已有 -`src/benchmark.py`，手动选择 LoCoMo-Refined 或 LongMemEval-S。默认前 1 个完整历史， -允许 1–10 个历史和 Top K 1–100；不自动随 PR、push、部署或定时任务运行。 -工作流仅接受本仓库 main，固定调用 QA 入口；唯一业务凭据为已配置的 -`AML_QA_ADAPTER_API_KEY`，映射为 runner 的 `ADAPTER_API_KEY`，仅在执行步骤注入。 -不重新部署应用，不要求 SQL、master key、kubeconfig 或 Pulumi。默认 retrieval 不需要 -LLM key；选择 answer-eval 时另外提供回答／裁判模型的配置与凭据。 - -两套来源固定 revision、原始文件大小和 SHA256，先下载／验证再调用服务。 -`benchmarks/ci-datasets.json` 维护可扩展来源注册；新数据集必须补齐数据准备与指标语义， -已有解析入口不代表已具备原生质量评分。`runtime_label` 是可选的非秘密报告备注， -默认留空，不作为评测前置条件，也不选择、构建或部署后端。benchmark 请求固定公网 -Add/Search 入口当前部署的适配器及 Memoria；留空时 JSON 记录 `null`，Summary 显示 -`Not recorded`（版本未记录）。填写时最多 200 字符，不含控制字符，并明确标注为操作者 -提供、未自动验证；正式版本对比应填写实际部署的 commit／digest。报告同时保存 -benchmark commit、数据版本、选择范围和 Top K。 - -Summary 展示执行状态、完整／部分进度、耗时、证据召回率、全部证据命中率、空结果、 -平均返回证据数、Search P50／P95、逐历史和原始 category 分组；未知指标显示 N/A，有证据标签的问题才进入召回率 -分母。LoCoMo 使用消息证据，LongMemEval-S 使用 session 证据；不跨数据集直接排名， -category 也不映射为 AML 七个能力维度。retrieval 不生成答案；answer-eval 为 LoCoMo -提供 Token F1／BLEU-1，并为两套数据提供自建 judge 分数与评分覆盖率。均不作为官方 -AML 分数，未设置无基线支持的质量门槛。 - -报告生成和上传在失败时也执行，artifact 30 天保存 checkpoint、版本及证据 ID／hash， -不上传原始数据或检索正文；硬取消／整个 job 超时的最终步骤仅尽力执行。 -执行步骤上限 120 分钟、job 160 分钟，与 CD 使用相同并发组且不取消正在运行的任务； -不自动修改 AML_FREEZE。并发组不控制外部客户端／官方评测，默认 pending 队列也不保证 -保留多个待执行任务。第一版无跨 Actions run 自动续跑；重新触发生成新 UUID，原数据 -按既有保留期限管理，artifact 过期不代替后台物理清理。 -首个 LoCoMo 历史已完成真实 Actions 联调，扩大范围暴露的写入问题见下文； -使用步骤和指标定义见[benchmark 说明](../benchmarks/CI.md)。 - -执行失败报告仅对固定 HTTP 状态码和固定适配器文案做精确匹配，保存静态 -`adapter_reason_code`，区分未知写入、未可检索、上游拒绝及连接不可用。未知响应、 -非预期结构和过大响应不保存正文。上游拒绝码不能独立证明内容策略或权限问题， -需要后端证据；诊断不改变 Add/Search、重试、恢复或检索规则。 - -### 分组报告与评分审计 - -逐题报告保存 `sample_id`，Summary／JSON 按选定历史展示检索、跳过、证据标签数、 -召回、全部证据命中率、平均返回证据数和 Search P95。未执行历史保留空统计，召回为 -N/A；旧版 LoCoMo／LongMemEval 报告按原有问题 ID 兼容分组。无法归属的题目仍进入 -全局指标，单独报告未分配数量，避免静默丢失结果。分组是报告能力，不改变 Add/Search -请求或检索策略，也不改变已定义的评分分母。新报告另保存取回来源 ID 和不匹配 -gold 标签，只存 ID 不存正文或 gold answer；Summary 展示审计覆盖题数及异常题数， -原始 exact-ID 评分保留异常标签。旧报告审计不可用显示 N/A，不误报为零。 -本地完整测试为 179 passed、1 个既有依赖弃用 warning，Ruff 通过；真实首轮 artifact -按新报告程序重新汇总后，已有聚合指标保持一致，并成功恢复单历史分组。 - -Recall@K 取当前同一次 Search 回包的前 K 条，切点为 1／5／10／20／50／100 -及实际请求 Top K，限制为不超过请求值；每题保留前缀召回，汇总时展示各切点的 -有标签覆盖数、平均召回及全部命中率。逐历史及类别 JSON 也包含这些指标。 -它提供排序诊断，不发额外请求，不改变写入和检索；不把前缀统计等同于另发较小 -Top K 请求的结果或性能。旧报告无法重建前缀分数，显示不可用；混合续跑记录需 -以各切点覆盖数解释，不能悄悄把缺失指标算作零。 - -首轮运行的 87 次 Search 均返回 100 条证据，故应结合证据预算解释其召回。 -固定公开 LoCoMo 数据还存在文本题 evidence 与原始消息 ID 不完全一致的标注： -`conv-26#q0028` 的单个标签为 `D8:6; D9:17`；`conv-49#q0030` 和 -`conv-49#q0036` 各把多个 ID 合写成一个空格分隔字符串；`conv-50#q0054` -包含 `D30:05`，未与原始消息 ID 字符串匹配。当前 exact-ID 评分保留原始标注， -没有静默纠正或排除；首轮及前三历史的范围涉及第一条标注，需在结果中披露。 -后续评分规范化必须作为明确的数据解释变更，增加验证并重新建立可比基线；这些 -标注问题本身不能用于判断 Memoria 检索失败，也不等同于 gold answer 错误。 - -### 检索基线与评测扩展顺序 - -[Actions run 37467293196](https://github.com/matrixorigin/memory_benchmarks/actions/runs/37467293196) -于 2026-10-06 成功完成 LoCoMo-Refined 的首个完整历史，使用 benchmark commit -`e06fd477190cb1e7c1d716147f4171d85a342574`、`histories=1`、`top_k=100`。 -证据来自该 run 的 `selection.json` 和 `summary.json` artifact；后端标签为 -`current-dev`，不是已验证的 Memoria commit／digest，不能据此复现具体后端版本。 - -| 指标 | 本次结果 | -|---|---| -| 执行耗时，不含数据准备 | 705.34 秒，约 11 分 45 秒 | -| 已完成 Add 分块 | 28 | -| 问题记录／实际 Search／多模态跳过 | 138／87／51 | -| 具有 gold evidence 的已检索问题 | 86 | -| 平均证据召回率 | 80.23% | -| 全部证据命中率 | 79.07% | -| 空检索结果 | 0 | -| Search P50／P95 | 0.95／2.71 秒，包含重试 | - -此结果证明当前公网评测链路可完成该样本的写入与检索，并提供首个检索诊断基线。 -它不代表答案正确率、正式 AML 成绩或总体质量；一个历史的样本覆盖有限，且 Top K 100 -需要结合返回证据量／预算解释，不能只以高召回认定比赛质量。 - -#### 修复前的扩大范围结果 - -2026-10-06 使用同一公网部署串行执行两套测试。benchmark commit 均为 -`e06fd477190cb1e7c1d716147f4171d85a342574`、Top K 100；启动前只读核对 -Memoria commit `e180dff308447efb487f313187968e77323dd33f`，镜像 digest -`sha256:f4c4c21c6d1cfe8f1623f58c6b1e11df9ed0f4e0a8a00e98455dacf3852b3721`； -适配器 digest 为 -`sha256:c273b9605da1ec63f4462c8253d3254399c54ebd01a6cf55767b0105d36e4164`。 -未在评测中发布或更换后端／模型。这里记录的版本来自实际部署核查，workflow 的 -`runtime_label` 字段本身仍是未自动验证的备注。 - -| 运行 | 执行结果 | 已完成进度 | 检索诊断，仅已完成部分 | -|---|---|---|---| -| [LoCoMo，3 个历史](https://github.com/matrixorigin/memory_benchmarks/actions/runs/37470374320) | 第三个历史 Add 阶段 HTTP 503；1597.23 秒 | 77／101 个 Add 分块；145 次 Search、65 道多模态跳过；144 道有证据标签 | 平均召回 81.25%；全部命中 78.47%；空结果 0；Search P50／P95 为 1.03／2.97 秒 | -| [LongMemEval-S，1 个历史](https://github.com/matrixorigin/memory_benchmarks/actions/runs/37470782399) | Add 阶段 HTTP 403；243.51 秒 | 15／69 个 Add 分块；0 次 Search | 召回、答案质量均为 N/A | - -LoCoMo 前两个历史 `conv-26`、`conv-30` 已完成，分别检索 87／58 题，平均召回 -79.65%／83.62%；第三个 `conv-41` 仅部分写入，97 道文本题尚未查询。145 次成功 -Search 均返回 100 条。`conv-26` 首轮 80.23% 与复跑 79.65% 存在小幅变化，在未改变 -算法且仅一个重复历史的条件下，不解释为优化或退化。上述聚合值不是完整三个历史 -的成绩，不能用零 Search 判定第三个历史或 LongMemEval 检索质量。 - -**LoCoMo 写入可靠性：** 失败位置为 `conv-41/session_15/0` 的第二条消息。 -Memoria 对应日志记录 `Embedding error: error decoding response body`。 -只读 journal 显示第一条为 `stored`，第二条为 `inflight` 且无 memory ID；按精确 -`aml_write` 标记查询暂未找到记录。部署源码在持久化前计算 embedding，且 HTTP -embedding 客户端会重试发送错误、5xx 和 429，但成功状态下的响应解码错误直接返回。 -这表明存在 embedding 依赖／响应处理的可靠性缺口；现有证据没有确定具体上游响应 -为何无法解码，也不能把所有 HTTP 500 判为未提交。适配器对模糊结果停止重发是当前 -幂等保护设计，负查询本身不授权重置 journal。 - -[Memoria #275](https://github.com/matrixorigin/memoria/issues/275) 的代码核实已使用实际 -`memoria-embedding` crate 和本地 HTTP 故障服务完成：HTTP 200 响应体截断时仅请求 -一次便失败，即使第二次响应已准备为正常向量；503 后恢复的对照则请求两次并成功。 -这确认了瞬时响应体读取失败未重试的缺口。无效 JSON／不兼容 schema 同样只请求一次， -但此类持久格式错误不应一律重试。线上原始异常响应未留存，不能据此认定线上一定是 -截断。配置多个 embedding 地址时外层可切换地址；单地址直接使用该 HTTP 客户端， -没有额外的同地址响应体重试。 - -**LongMemEval 数据接收：** 失败位置为 `e47becba/session_13/0` 的第四条消息， -前三条已为 `stored`，第四条为 `pending`。对原始输入和部署版本的敏感规则进行离线 -匹配，仅该消息命中 HIGH 级 `password_assign`（字段词为 `secret`）。部署的存储入口 -会在 embedding／持久化前拒绝该规则匹配，映射 HTTP 403；这与失败位置、已接收的 -同用户消息及 journal 状态一致。进一步检查原始消息语境及实际 Rust 检测器，已确认 -这是烤排骨干腌技巧中的普通表达误报：`share a secret: **dry brining**` 被当作凭据。 -原始消息和最小普通文本 `The secret: practice every day.` 均返回 `blocked=true`、 -`password_assign`，真实格式的合成密码对照仍被拒绝，无该短语的普通文本被接受。 -[Memoria #276](https://github.com/matrixorigin/memoria/issues/276) 因此已在代码层面确认 -存在误报；仅增加单词边界不足以修复独立的 `secret:` 普通表达，需要区分语境并保留 -真实凭据保护。不能通过丢弃该消息、改写原始文本、排除历史或把 403 包装成 Add 成功 -获取“完整”基线。 - -#### Memoria 修复交付 - -两项独立修复已合并到 `matrixorigin/memoria` main；2026-10-07 已部署包含两项 -修复的 `main@81c5cc6`。部署后的相同 LoCoMo／LongMemEval 选择均已完整通过， -实际版本、结果和验收边界见下文“修复版本的线上回归”。 - -| 修复 | 设计与验证 | -|---|---| -| [PR #277](https://github.com/matrixorigin/memoria/pull/277)，`d341891` | 将 HTTP 响应体读取和 JSON 解析分开，读取失败和 JSON EOF／IO 复用原有三次尝试及退避，覆盖无 Content-Length 与 chunked 响应。JSON Syntax／Data 错误立即返回稳定分类；除 429 外 HTTP 4xx 不重试，5xx／429 仍重试。单条／批量均校验向量数量与配置维度；提供 index 时要求完整、唯一的 0..N-1 并恢复输入顺序，全部省略 index 时兼容原响应顺序。embedding crate 37 个测试通过，其中 18 个 HTTP／客户端测试覆盖恢复、耗尽、格式、认证、连接、限流及向量契约；Clippy／格式／diff 检查通过。 | -| [PR #278](https://github.com/matrixorigin/memoria/pull/278)，`cfb9866` | 仅对独立 bare `secret:` 要求行首／对象字段边界，支持 YAML 列表与引号字段；叙述中的该短语不再等同于凭据。password／passwd 保留原有无前置单词边界的检测，任意标识符的 secret 后缀继续拦截，覆盖环境变量、驼峰、下划线、连字符及 Unicode 前缀。显式凭据字段、bare `secret=` 和结构化 `secret:` 仍拦截。core crate 18 个测试通过，含 5 个回归测试函数；原始 LongMemEval 消息通过实际修复后 Rust 检测器，本地完整正文未提交；Clippy／格式／diff 检查通过。 | - -敏感规则按输入语法判断，不依赖数据集名或烹饪短语白名单。独立行的 `secret: value` -及显式别名 `Our client secret: ...` 仍保守拦截，含义模糊时并不保证所有普通表达均被接受； -不得将正则启发式表述为完整的语义凭据识别。真实 AWS key、私钥、Bearer token 与 -MEDIUM 级脱敏仍保留。PR #278 关联 #276，不自动关闭该 issue；内容策略拒绝与认证／权限 -拒绝的可操作 API 分类仍是未完成项；部署后首个历史的完整复测已通过。 - -embedding 修复重试的是写入前的向量计算。三次请求分别保留 30 秒超时，退避为 -200／400 毫秒，请求与退避预算约 90.6 秒；并发许可等待单独计时，默认最多 5 秒。 -该预算不是新增的端到端严格截止时间。错误保留 HTTP 状态与安全的超时、连接、请求体、 -响应体及 JSON 分类，不记录或回传上游正文、意外 JSON 值、请求 URL 或凭据，截短正文 -同样可能包含秘密。持续格式不兼容、维度／数量／index 不正确的响应仍失败；无 index -的提供商依赖自身返回顺序，无法验证其语义顺序。 - -没有新增记忆写入重放、原子幂等或结构化未提交状态。通用 HTTP 500 的写入结果仍需按 -既有保护处理，旧 inflight journal 不直接重置；该协议能力与瞬时响应读取／EOF 故障 -分开跟踪，#275 仍作为关联 issue 保留。原始线上异常原因尚未确定。 - -本项目发布 workflow 已将 `main@81c5cc6` 的源码构建镜像部署到 dev，目标为 -`deployment_target=memoria`，源码 SHA、构建及部署 run、镜像 digest 见“当前交付状态”。 -已使用新 run 重跑相同 LoCoMo 三个历史和 LongMemEval-S 首个历史；完整写入与检索 -结果构成该选择范围的线上恢复验收。旧 inflight journal 未重置或自动重放。 - -#### 修复版本的线上回归 - -2026-10-07 在同一公网入口串行完成两套回归，benchmark commit 为 -`9eed5b49a18313e3883e78fabec10631c16a3367`，Top K 为 100。两份报告的 `contract` -分别与各自的失败运行完全一致，包括数据 SHA256、历史 ID、入口、Top K 和 runner -版本；新执行程序增加逐题审计与排序前缀统计，没有改变该比较范围。 -使用新的随机 run ID 隔离用户及请求，没有复用部分写入、改写输入、排除阻塞消息或 -变更 gold 评分规则。评测前后只读核对的两个镜像 digest 与“当前交付状态”一致， -Pod UID 不变、Ready 且重启次数为 0；`runtime_label` 仍只是操作者备注。 - -| 运行 | 完整性 | 检索诊断 | 执行耗时 | -|---|---|---|---| -| [LoCoMo，3 个历史](https://github.com/matrixorigin/memory_benchmarks/actions/runs/37571328104) | 101／101 个 Add 批次；242／242 道文本题；跳过 104 道多模态题；报告 `completed`、无终止错误 | 241 道有证据标签；平均召回 83.61%；全部证据命中率 80.50%；空结果 0；Search P50／P95 为 0.99／2.63 秒 | 2096.29 秒，约 34.94 分钟 | -| [LongMemEval-S，1 个历史](https://github.com/matrixorigin/memory_benchmarks/actions/runs/37574166791) | 69／69 个 Add 批次；1／1 道文本题；报告 `completed`、无终止错误 | 唯一一道题的证据在第一位，Recall@1／100 均为 100%；Search 1.01 秒 | 661.05 秒，约 11.02 分钟 | - -报告确认原失败批次 `conv-41/session_15/0`、`e47becba/session_13/0` 均已完成。 -LoCoMo 的响应解码错误导致整轮中断、LongMemEval-S 原始普通文本 `secret:` 导致 -403 的误报均未复现。两个观察窗口未记录 Memoria 内部服务或 embedding 错误。 -一次成功运行不证明瞬时响应体故障不可能发生，也不代替注入故障测试、未知写入恢复 -或全部输入验收。 - -适配器访问日志分别记录 LoCoMo 11 次、LongMemEval-S 4 次 Add HTTP 503，均在既有 -有界重试后继续完成；成功的外部 Add 分别为 101／69 次，Search 为 242／1 次。 -这是 HTTP 尝试次数，不是失败批次数；完整通过不等于没有短暂不可用。现有成功 -checkpoint 不保存中间重试原因，访问日志也只有状态码，不能据此认定这些 503 是 -解码失败、未知写入或搜索可见性延迟。应补充安全的重试原因与次数观测后定位， -避免仅依据状态码修改重试或 journal 幂等语义；本轮没有确认新的代码 bug。 - -| LoCoMo 返回前缀 K | 1 | 5 | 10 | 20 | 50 | 100 | -|---|---|---|---|---|---|---| -| 平均证据召回率 | 43.12% | 60.51% | 67.88% | 72.03% | 78.22% | 83.61% | - -三个历史 Recall@100 分别为 `conv-26` 80.23%、`conv-30` 83.62%、`conv-41` -86.60%。旧运行只有前两个历史，81.25% 不能与新三个历史的 83.61% 直接当作 -算法提升比较；限制为共同的 144 道有证据题时，本次为 81.60%。单次轻微变化不作为 -检索算法优化结论。242 道文本题均已审计，其中 `conv-26#q0028` 仍含已披露的 -不匹配 gold 标签 `D8:6; D9:17`，保留 exact-ID 计分，不静默修正或排除。 - -LongMemEval-S 的 100% 只对应一道题，不能代表 500 题或全部能力。上述均为检索 -证据指标，没有执行 Answer/Eval、AML 官方 Smoke／Full 或生成官方分数。 -上述回归使用的旧 runner 将 `[dialogue:ID]` 写入正文；LongMemEval-S 报告中可见 -`answer_` 来源 ID，这类答案来源标签会进入 embedding 和后续可见证据。因此本轮 -是可靠性回归及现有输入下的检索诊断，尚不是无标签泄漏的质量基线；不能推断高分 -必然由标签造成。质量调优前须外置诊断映射，保持合法来源时间和角色，再重新建立 -输入一致的基线，不能直接混合比较清除标签前后的分数。 -完整报告和证据 ID／hash 位于各 run 的 `aml-benchmark--1` artifact， -按既有 30 天期限保留；后台数据仍须执行既定清理。 - -**来源时间验收范围：** 当前公开数据 runner 只在正文保存会话日期，不发送 AML -`timestamp`，因此上述数据集运行不能证明时间戳适配正确。额外隔离合成探针分别使用 -2023-05-08 与当前 Unix 毫秒时间，两组 Add／Search 均为 200 并返回测试事实；只读 -核对旧时间保存为 `observed_at=2023-05-08`，创建时间为实际接收时间。验证 owner 后已 -逐条停用两条合成记忆。当前路径没有复现旧时间直接阻塞 Add 的推测，不据此修改 -Memoria 衰减逻辑，也不宣称覆盖所有检索模式／配置。 - -源码核对表明，当前部署及 Issue #1 原评论引用的 Memoria 版本，都在混合检索结果 -为空后继续执行全文回退；普通无过滤 Search 也可能走图路径。因此原评论中根据 -`MIN_CONF=0.05` 直接推断 Add 会持续失败的论证不完整，应收紧为混合候选过滤的 -条件风险。混合结果非空时不一定触发全文回退，仍需验证混合新旧证据、不同 query、 -阈值两侧和 Explain 路径。单个旧时间探针成功不证明全部时间策略正确；不能据此 -全局关闭衰减。详见 [Issue #1 时间结论](review-issue-1.md#对历史来源时间评论的更正)。 - -上述失败运行使用 PR 前的执行程序，没有新逐题审计和 Recall@K 前缀字段。可从 artifact -恢复逐历史指标，无法从仅有 ID／hash 的旧记录反推排序前缀。诊断文件不提交原始正文 -或密钥。数据按既有保留期限管理，artifact 到期不等于后台数据已物理删除。 - -后续按以下顺序推进，不为每套数据集另建 workflow： - -模型可见的诊断／答案来源 ID 已移出，保留外部审计映射；旧带标签的结果用于运行 -诊断，不作为正式质量基线。新契约的真实质量结果与后续顺序见“正式参评前的工作”。 - -1. **继续验证写入可靠性与可恢复性**：PR #277／#278 已在固定小集完成线上回归； - 补充安全的中间重试原因与次数观测，定位可恢复 503，并在扩大范围时继续验证 - embedding 格式与稳定性。固定选择的完整接收不代表任意输入均已验收。 - 未知写入的自动恢复需要后端原子幂等或可信的未提交状态契约，不能按通用 5xx 或 - 等待时长盲目重发。数据接收保留安全边界，不在 runner 中默默洗掉阻塞输入。 -2. **保留已完成的扩展小集基线**：LoCoMo 前 3 个历史及 LongMemEval-S 首个历史 - 已全部写入、执行所有文本题且报告完整；保留版本、数据校验值、指标和 run 链接， - 后续比较使用相同选择及评分口径，再扩大样本。 - -3. **扩大现有 LoCoMo 覆盖**：保持后端与配置固定，在已通过的 3 个历史基础上扩至 5 个，查看 - 不同历史和类别结果；再评估全 10 个历史。当前 Execute 限时 120 分钟，扩大前需核对 - 写入量和实际耗时，不能把单历史时长视为全量保证。以固定样本做后续变更对照。 -4. **扩大已接入的 LongMemEval-S**：首个历史已完整通过；同一 workflow 选择 - `longmemeval`，后续扩至 `histories=10`。每个历史只有一道问题，1 或 10 个历史主要用于 - 初步验证，不能代表完整 500 题质量或覆盖全部能力；正式基线需后续扩展样本范围。 -5. **质量评分验收**：Answer/Eval 已接入，固定回答模型、提示词、证据预算和裁判规则， - 使用原数据已有 gold answer／evidence 评分，保持 gold 不进入 Add/Search。 - 同时比较 Recall@K、预算内证据、答案质量和时延；不把证据召回率当作答案分数。 -6. **补有针对性的回归样本**：多用户隔离、幂等重试、时间顺序／事实更新、跨会话聚合及 - 无答案场景应形成固定小集，复用现有契约测试并补齐实际缺口。它们是本项目开发测试， - 不宣称等价于 AML 七维官方评测。 -7. **按需要扩展数据集**：BEAM 可作为后续长历史评测，先选短历史并限定预算，再接入 - Actions；PersonaMem-v2 等需明确所测能力和原生评分。ScriptMem 等原始数据未取得的 - 数据集暂不新增可运行选项。公开数据准备、样本选择和评分定义完成后再扩展入口。 - -### dev CI/CD - -发布流程选择 Memoria 来源并在源码模式下 checkout、记录实际 commit；核对 kubeconfig 的 API Server、集群 UID、权限和 StorageClass，再运行离线检查、构建及推送适配器与所选 Memoria 镜像，然后 preview／up 独立 Pulumi stack。benchmark workflow 手动入口仅接受本仓库 main 分支，Memoria 来源 ref 可以独立选择；main push 自动部署默认关闭，通过 `AML_DEV_CD_ENABLED=true` 显式开启。preview 会发布镜像并可能初始化空的 Pulumi stack，但不创建 Kubernetes 应用资源。发布任务串行执行，不中断正在进行的 dev 发布。 - -#### 独立应用更新 - -手动发布增加 `deployment_target=both|memoria|memory_benchmarks`，默认 `both`。 -`memory_benchmarks` 指本项目提供的 AML Add/Search 适配器。首次部署选择 `both`； -后续可单独更新任一服务，`preview` 和 `deploy` 使用相同选择逻辑。 - -未选应用的实际镜像 digest、来源元数据和应用配置从当前 Helm release 读取； -核对 Deployment 镜像后保存非凭据配置快照。Pulumi 以已部署 values 为基础，只替换所选 -应用的字段，保留另一项及共享配置。仅更新 Memoria 时保留适配器连接 URL 和 key 引用； -仅更新适配器时跳过 Memoria checkout／构建，并以 `reuse` 记录原来源。首次环境没有完整 -release 时拒绝单项更新，不根据旧 Variable 猜测当前版本。 - -共享数据库连接、master key、adapter key 和 embedding key 若有变动，要求选择 `both`。 -未选 Deployment 的旧 manifest 与当前 chart 使用旧 values 的渲染结果必须一致，避免 -chart 改动意外更新另一项。构建完成后、Pulumi 操作前复查快照；变化时停止并要求重新运行。 -快照权限为 `600`，不含原始运行凭据，忽略提交并在 workflow 结束清理。共享 Ingress／证书 -等 Helm 配置在单项更新时保留，变更时使用 `both`。独立更新无需新增 Secret。 - -所有模式仍使用同一 Pulumi stack、namespace 和 Helm release，保留串行发布与冻结规则； -自动发布启用后仍默认更新两项。独立更新控制应用版本和配置，不使用 Pulumi resource -`--target` 裁剪资源图。Memoria Recreate 期间上游会暂时不可用，适配器 Pod 保留不代表 -Add/Search 全程可用，比赛评测期间仍须冻结发布。 - -离线验证覆盖选择分支、已部署版本复用、共享凭据变更拒绝、未选应用 chart 变动拒绝、 -构建期间配置变化拒绝、首次 `both` 和 Pulumi 配置保留。真实单项部署及实际 Pod 的保留 -效果仍需在初次完整部署后验收。 - -`KUBECONFIG` Secret 使用阿里云 dev unit 的完整原始 YAML，不做 base64 编码，不填写文件路径；原有 AWS 配置不能用于该目标。工作流使用既有 `PULUMI_TOKEN`、组织 ACR Secret 和新建运行凭据。复用现有 DNS solver 时无需新增阿里云 RAM AK；域名入口解析由运维配置，证书由 cert-manager 自动管理。变量、Secret、初始化和操作步骤见 [dev 发布说明](../../deploy/README.md)。 - -Memoria 和适配器各单副本，journal 持久保存，使用 Recreate 更新以维持 journal 和 RWO 卷的单 Pod 部署约束；同一 Pod 中的多个进程可共享现有 journal 和文件锁。namespace／journal PVC 受删除保护。凭据变化通过 Secret checksum 触发重启。发布等待 Pod 就绪，ready 仅检查 journal 和上游健康接口，不等价于数据库权限、embedding、真实 Add/Search 或完整幂等恢复验收。 - -### 发布安全与工程补充 - -以下工程措施已在代码中实现；首次完整发布及最小运行联调已通过，恢复与容量等剩余验收见后文。 - -| 项目 | 当前事实 | 处理要求 | -|---|---|---| -| 发布冻结（P1） | `AML_FREEZE=true` 在任务入口及 `up` 前拒绝自动和手动部署，Pulumi 真实更新再检查 | 空值／`false` 允许，非法值拒绝继续；preview 可执行，已运行任务按下述流程处理 | -| Helm 检查（P2） | CI 和 CD 均安装 Helm 3.17.4；CI 两组 lint／template 已通过，本地 Helm 4.1.4 两组也通过 | 合成配置不含真实凭据或集群访问，不代替真实发布 | -| `/ready` 测试（P2） | 八个用例覆盖原有六种依赖状态，以及 40 个 Search 饱和时探针可用、并发 ready 不排队；本地完整 pytest 154 项通过 | 同时检查探针无鉴权、失败不泄露上游内容、journal 失败不访问上游；公网健康状态返回 200，真实故障注入仍未执行 | -| 依赖与 Action 锁定（P2） | 部署辅助依赖列出 PyPI SHA256，安装启用 `--require-hashes --only-binary=:all:`；Actions 引用完整 commit SHA | 保留对应主版本注释，更新时重新核对来源和锁定值；应用 `uv.lock`／Go `go.sum` 继续使用 | -| 环境配置公开边界（P2） | 实际 dev YAML 已忽略；公开模板使用占位符，CI 从三个非秘密 Variables 生成 | 标识已上传，不增加 Secret；继续检查其他环境信息的公开边界 | -| 初始化凭据恢复（P2） | 先查询专用用户；凭据缺失且用户存在时，生成新凭据和 DDL 前停止，并输出恢复指引 | 不重设旧密码；首次创建使用明确 CREATE USER，凭据更新原子替换，临时文件忽略；恢复行为尚未执行数据库验收 | - -冻结变量在 workflow 中使用当次解析值，入口和 `up` 前的检查不代表实时重新查询 GitHub Variable。进入正式评测前，设置冻结、关闭自动发布、取消排队的 deploy，等待已经运行的发布结束，再确认镜像 digest 和运行配置。冻结不能撤销已经开始的部署，也不能约束绕过 workflow 的手工操作；不假定修改变量能中止长时间构建中的任务。preview 可继续用于评审，但当前 preview 会推送镜像并可能初始化空 stack，不能当作完全无外部写入的检查。 - -保留 Recreate 策略。适配器已有 1800 秒终止宽限和 1740 秒 Uvicorn 优雅退出等待，Memoria 的终止宽限为 120 秒；这些配置不保证发布期间持续可用，也不保证所有在途请求完成。发布串行化只协调 CD 任务，不感知 AML 评测。正式评测期间禁止应用发布、凭据更新和手工重启；冻结不是高可用机制。 - -初始化恢复应优先保留已生效的数据库密码、master key 和 adapter key。确需轮换数据库密码时，使用管理员执行明确的密码更新，并同步 GitHub Secret 与运行实例；两种认证 key 另行管理，避免因重新初始化而意外替换。错误指引只输出恢复步骤和非秘密错误信息。 - -API 地址、集群 UID 和租户标识属于环境信息，不等同于密码泄露。私有配置与公开模板分离后，三个辅助脚本和 Pulumi 继续读取同一目标配置；公开整理不能通过删除身份检查来隐藏目标环境。 - -### 并发与上线验收 - -**worker 数量是容量参数，当前单 worker 不能直接判定为吞吐缺陷。** Add/Search 使用同步 `def` 路由，经 Starlette 线程池执行；其默认线程池容量为 40 个 token，一个进程能并发处理多个请求。journal 使用独立 SQLite 连接和请求级文件锁，支持同 Pod 多进程，但数据库写入仍有锁竞争。当前适配器资源上限为 1 CPU／1Gi，增加 worker 会增加线程、HTTP 客户端和内存，并放大后端流量。[Starlette 线程池](https://starlette.dev/threadpool/) - -默认保留单 worker，已增加 Helm `workers` 参数及正整数 schema 校验；CD 的 `AML_ADAPTER_WORKERS` 传入 Pulumi，再配置 Uvicorn `--workers`，不增加 Pod 副本数。结合总并发预算和负载测量选值，比较吞吐、P50／P95、错误率、CPU／内存、journal 锁等待、数据库及 embedding 压力后再增加，不把固定多个 worker 作为正式参评的前置要求。 - -运行验收按具体版本记录，剩余范围如下： - -1. **只读 Memoria 容器**：当前交付状态所列 SHA／digest 在 UID 1000、只读根文件系统、仅 `/tmp` 可写的条件下，启动、共享及用户 schema 初始化、健康检查和真实 Add/Search 已通过，重启恢复仍未验收。自有 Dockerfile 直接执行 `memoria serve`，日志写标准输出。未来来源版本若实测需要其他可写路径，应依据证据增加最小挂载或修正配置；不预先关闭只读限制。结论关联实际 SHA／digest，不能泛化到所有 0.5.x 镜像。 -2. **公网长请求**：核对真实 SLB 产品、80／443 listener 协议及空闲／请求超时，再核对 NGINX 和客户端。当前 Kubernetes Service 为 LoadBalancer、端口标记 TCP；这只是 Service 的传输协议，不能证明云端 listener 类型和超时值。阿里云 CLB HTTP 文档区分空闲超时默认 15 秒与请求超时默认 60 秒；CLB TCP 空闲超时默认 900 秒。默认值不能替代当前实例的实际配置。[CLB HTTP](https://www.alibabacloud.com/help/en/slb/classic-load-balancer/user-guide/add-an-http-listener-1)、[CLB TCP](https://www.alibabacloud.com/help/en/slb/classic-load-balancer/user-guide/add-a-tcp-listener) -3. **长请求验收范围**：5 分钟无中间响应的请求可作为初步检查，但不能验证 900 秒限制或接近 AML 允许上限的整批 Add。继续验证超过 900 秒、接近所选组别有效契约上限的静默请求，并核对真实整批 Add 的耗时、超时后的恢复和重复提交。流式心跳不能代替最终 JSON 响应的协议验收；共享 SLB 的修改由基础设施负责人处理。 - -以上工程补充与运行验收在正式评测前完成；它们不替代输入可信、幂等恢复与 Answer/Eval 等质量工作。 - -### 评测负载与资源边界 - -- 正常成功路径中，每个新记忆分片执行写入、ID 回读、搜索确认三次上游调用。设分片数为 M、外部 Search 次数为 Q，不计失败／恢复／重试，Memoria HTTP 请求量约为 **3M + Q**。20 条各不超过分片上限的消息约需 60 次上游调用；该数字不等于 SQL、模型计费次数或实际 QPS，长消息分片和重试会增加请求量。 -- 启用 embedding 时，写入和搜索探针均可能产生模型流量，数据库承担写入、去重和检索。实际调用量受配置、缓存与重试影响；当前适配器没有接上 Observe／LLM 抽取，不能假定每条记忆消耗一次 qwen-plus。可选 Answer/Eval 在独立 benchmark 进程中调用模型，不属于 Add/Search 后端逻辑。 -- 本地 benchmark runner 串行发送请求，但没有 QPS／token 预算或跨运行并发控制。适配器同步路由通过线程池执行，一个进程也可以同时处理不同请求；请求级 journal 锁不能控制整套评测的总负载。全局总并发、上游速率和总量预算尚未实现。[FastAPI 同步处理器](https://fastapi.tiangolo.com/async/#path-operation-functions) -- owner 前缀隔离的是数据范围。共享数据库计算资源或同一模型账户时仍会竞争资源；独立 database 或新建模型 key 不自动提供独立容量。 -- 开发阶段一次运行一个任务，从小集开始记录分片数、写入吞吐、Search P50／P95、错误／429、数据库等待、模型 token／额度和数据增长。停止条件依据评测实例的预算和实测确定，不推测一个未经验证的安全 QPS。 -- 保留 journal 支持同一请求恢复；数据清理覆盖 Memoria 记录、journal 与其他产物。逻辑删除、独立 owner、持久卷均不能代替物理保留期限与清理方案。 - -### 正式参评前的工作 - -先建立无来源标签泄漏的固定小集 Answer/Eval 基线，再按失败样本决定检索、排序、 -证据上下文或评分侧的优化。自建 Answer/Eval 使用项目自己维护的提示词和 rubric， -并未取得 AML 完整判分提示词，不承诺复现官方或数据集原生评分器。相同流程结构 -不能保证分数等价；固定模型、数据、预算及提示词版本后用于项目内部比较。 - -实施顺序为：LoCoMo 首个完整历史的端到端基线；补 LongMemEval-S 完整历史；扩大 -LoCoMo 历史覆盖与不同类别诊断；再按预算接入 BEAM 等现有文本解析器。所有实验 -串行进行，复用同事的下载／转换脚本和共享 runner，不重复开发已有入口。 -遇到未知写入、embedding 格式或内容策略阻塞时，先定位和修复可靠性问题，再比较质量。 - -正式 Full 前仍须确认模型和组别契约，并验收容量、重启／重试恢复、公网长请求和 -物理清理。发布流程不自动启动基准或官方 Smoke／Full。 - -#### 数据准备与复现 - -完整公开数据在本地或 Actions runner 下载，继续排除 Git；提交下载／转换代码、 -固定来源 revision、原始文件字节数、SHA256、许可证说明和样本选择规则。 -LoCoMo／LongMemEval 已由 `benchmarks/ci-datasets.json` 与准备步骤实现固定下载和校验； -新增数据优先接入现有 `download.py`／`prepare.py`，明确转换版本及转换后的校验值。 -不依赖同事电脑中的 ignored 文件作为可复现交付。少量人工合成回归样例和来源 ID -选择清单可以提交；评测正文、gold、私有缓存和 key 不进入结果文档。 - -当前无需引入 OSS／S3 或 Git LFS。若上游可用性成为实际阻塞，再按许可证建立受控 -镜像，仍按校验值识别数据。数据可下载不等于已完成 Add/Search 或原生作答判分。 - -#### 官方接入材料与 Smoke - -以下是当前 QA 的申请候选材料，不表示已向平台提交或获得正式资格。Memoria／适配器 -Ready、本地 HTTPS 与真实 Add/Search 验收通过；独立公网与 GitHub-hosted runner 可达性 -仍须验证后才能提交给平台。`/ready` 不能代替官方 Smoke。 - -| 申请／绑定字段 | 已准备的内容／待完成项 | -|---|---| -| 系统／赛道 | Memoria，Textual Memory；参赛组别由负责人按官方模型要求确认 | -| 方法与代码 | [Memoria](https://github.com/matrixorigin/memoria) 与 [适配／评测仓库](https://github.com/matrixorigin/memory_benchmarks)；基于同事现有适配器，来源及改动据最终冻结代码填写 | -| Add URL | `https://aml-qa.moi.shanghai.idc.matrixorigin.cn:30443/add` | -| Search URL | `https://aml-qa.moi.shanghai.idc.matrixorigin.cn:30443/search` | -| 健康检查 | `https://aml-qa.moi.shanghai.idc.matrixorigin.cn:30443/health`；运维就绪检查为 `/ready` | -| 鉴权 | `Authorization: Bearer `；使用 QA key（CI 中名为 `AML_QA_ADAPTER_API_KEY`），通过官方凭据字段提交，不放入公开说明 | -| Memoria 版本 | 0.5.2，`6247235e27bc62898b122473dafae084bea61c80`；部署 digest `sha256:00b3fd0ab90e31beb968b2f4d8acef8bb9b99dc34ba0fdb48b33a3b8c425daa5` | -| 适配器版本 | 源码 `3048f6bab82966ee63c25fbf5f6cb51cadf87c6d`，digest `sha256:c273b9605da1ec63f4462c8253d3254399c54ebd01a6cf55767b0105d36e4164`；依据首次成功发布的 build record／推送日志及当前 Deployment，不将 benchmark checkout SHA 当作服务版本 | -| 运行配置 | QA IDC，复用共享 Memoria／数据库、独立 adapter journal、owner 隔离；embedding 为上海 `BAAI/bge-m3`，当前 Add/Search 不调用抽取 LLM；`qwen-plus` 仅用于独立的自建 Answer/Eval | -| 容量声明 | 初始建议 Add／Search 并发均为 1；这是保守接入建议，尚非最大吞吐或 Full 容量验收结论 | -| 联系人与机构 | 由负责人填写，并确认组别与允许公开展示的信息 | -| Eval Key／绑定版本 | 尚未验证可用的官方 Key 或版本绑定；不以适配器 key 替代 | - -方法说明草案：适配器按 `user_id` 映射独立 Memoria owner，跨 session 保持同一用户 -的检索范围。Add 同步写入逐条消息及必要的 UTF-8 分片，保留角色／来源时间，使用 -持久 journal 处理重试，并确认写入记录可检索后返回成功。Search 将原始问题交给 -Memoria，保留后端排序、按 ID 去重并限制 Top K，仅返回记忆证据，不生成最终答案。 -后端采用 MatrixOne 存储与上海 bge-m3 embedding；当前不使用 LLM 抽取或 rerank 服务。 -公开数据的检索／作答诊断与参赛服务分开执行，gold 和自建裁判规则不进入 Add/Search。 -最终提交时将此说明与冻结配置及两个源码版本核对。 - -接入顺序：通过官方 Evaluation Access Request 提交材料，取得 Key 并核对绑定的 -接口／版本；在无其他基准运行时启动 Textual Smoke，保存官方 Run／Job ID、阶段、 -结果和安全错误摘要。官方 Key 与 Memory System Key 是两份不同凭据。 -Smoke 当前限额为每小时 1 次、本届每赛道最多 30 次；Full 每 Key／赛道最多 2 次， -第二次距首次完成至少 30 天。申请材料截止为 2026-10-31 23:59（UTC+8），评测 -停止为 2026-11-04 23:59。规则来源：[官方文档](https://agentmemories.ai/zh-cn/docs)， -2026-10-07 核对；实际提交时再次核对。 - -当前模型资格有待明确：官方 checklist 使用 Open-source Methods／Commercial Products， -赛事 FAQ 使用学术／工业名称且列出模型限制。上海 bge-m3、纯存储 Add 是否符合拟报 -组别，应在申请中如实披露并请官方确认；不通过修改自建 judge 模型推断已符合要求。 -正式 Full 前设置 `AML_FREEZE=true`、清理排队发布并等待运行中的发布结束，再记录 -最终镜像／源码／配置；评测期间维持冻结，结束后按既定保留与清理方案处理数据。 - -### Memoria 镜像选择与源码构建 - -**默认从 `matrixorigin/memoria` 的 `main` 分支构建。** 非秘密来源配置位于 `deploy/memoria-source.json`，维护默认模式、仓库和 ref；`AML_MEMORIA_REF` 可以设定长期来源，手动发布的 `memoria_ref` 可以选择本次分支、tag 或 commit。分支选择符合日常开发需要，每次 checkout 后记录实际完整 SHA；后续构建使用这份 checkout，部署使用构建返回的镜像 digest。源码 ref 和本仓库 workflow 的 main 分支限制相互独立。 - -来源必须存在于配置的远端仓库，本地未推送修改不进入构建。Memoria 分支更新不会自行触发本仓库 workflow；手动发布或已启用的本仓库 main push 发布会读取当次来源版本。默认不增加源码仓库反向触发或定时自动发布。 - -本项目的 `deploy/docker/memoria.Dockerfile` 是源码构建入口，构建上下文为检出的 Memoria 仓库根目录。原源码 Dockerfile 默认 Rust 1.85，而当前 lock 含要求 1.88 的依赖；比赛构建采用 Rust 1.90.0，builder／runtime 同为 Debian Bookworm，并固定基础镜像 digest，避免构建器与运行环境的 glibc 差异。`cargo build --locked --release --bin memoria` 使用来源仓库的 Cargo.lock、vendored 依赖及 SQLX offline 数据；下载／编译采用缓存。运行镜像以 UID 1000 执行 `memoria serve`，日志写标准输出。该构建文件在 benchmark 仓库维护，无须修改所选 Memoria 分支；未来编译器要求变化需更新此文件。 - -离线 CI 只检查适配器镜像；Memoria 的 `linux/amd64` 源码镜像仅由 CD 按更新范围构建，并推送至指定 Hangzhou ACR 仓库。源码模式下 `AML_MEMORIA_REPOSITORY` 默认使用适配器的同一仓库，由不同项目 tag 前缀区分两个镜像；两个镜像的实际推送与 Pod 拉取已通过。只有构建成功并返回有效 digest 后才进入 Pulumi／Helm；不会把新 digest 写回 GitHub Variable。记录包含请求的 ref、实际完整 commit、构建 tag／UTC 日期、镜像 digest、构建 Dockerfile hash、benchmark commit 和 Actions run。Actions summary／artifact 保存构建信息，Pulumi output 和 Memoria Pod annotation 标记来源版本。artifact 当前保留 30 天，长期评测结果应另存版本信息。 - -当前 ACR registry 为 `registry.cn-hangzhou.aliyuncs.com`，namespace 为 `moc-pub`，repository 统一为 `plugin`。tag 采用用户指定的 `--<7 位 SHA>` 格式；project 分别为 `aml-memory-adapter` 与 `aml-memoria`，日期统一取工作流生成 tag 时的 UTC 构建日期，SHA 来自各自的实际源码版本。共享 repository 由项目前缀区分，实际部署引用为 `//@sha256:`。完整源码 SHA 仍保存在版本记录，不依赖短 SHA 追溯。ACR namespace 与 Kubernetes namespace `aml-memory-benchmarks` 是独立概念；可选现成 Memoria 镜像保留 `moc-pub/memoria` 的有效 digest 引用。完整示例和 Variable 填写规则见 [镜像名称结构](../../deploy/README.md#镜像名称结构)。 - -`main` 或其他分支在不同运行中可以更新；重放某次 preview／评测时可把实际 SHA 填入 `memoria_ref`，或改用那次镜像 digest。镜像 tag 只用于查找，实际发布与回退使用 digest；源码版本固定与最终镜像版本均可追溯。preview 后若分支改变，下一次默认分支 deploy 可能构建不同版本，需用记录的 SHA 指定相同来源。 - -保留 `image` 模式用于部署现成镜像与回退，手动 `memoria_build_mode` 可覆盖本次选择；`configured` 按 Variable 或 JSON 中默认模式执行。该模式要求 `AML_MEMORIA_IMAGE=repository@sha256:...`，跳过 Memoria checkout／构建。当前 Variable 指向 `main@81c5cc6` 的源码构建产物，digest 与构建来源见“当前交付状态”，该固定镜像的部署及上述两套完整小集 Add/Search 回归已通过。之前 gitops dev 的旧 `apiserver-20260817-a8c0397-dbfc6241` 镜像不再由此 Variable 选择，其运行兼容性未验收。 - -#### ACR 镜像发布兼容性 - -当前 Hangzhou ACR 入口拒绝 BuildKit provenance 附件使用的 -`application/vnd.oci.empty.v1+json`。发布适配器和 Memoria 时显式设置 -`provenance: false` 与 `sbom: false`，避免将这类附件随镜像推送；离线 CI 的适配器镜像构建 -使用相同设置。[Docker 构建附件说明](https://docs.docker.com/build/metadata/attestations/) - -镜像仍按 digest 部署。Memoria 来源 SHA、Dockerfile hash、镜像 tag／digest、benchmark -commit 和 Actions run 继续写入原有版本记录／镜像标签；这类记录提供版本追溯，不等同于 -签名或可验证 provenance。需要构建证明时，应在兼容的独立存储中保存，或在 registry -升级并验证附件支持后重新启用。 - -### 当前交付状态 - -**阿里云 dev 已更新为包含 PR #277／#278 的 Memoria main 源码镜像。** -[部署 run 37568843033](https://github.com/matrixorigin/memory_benchmarks/actions/runs/37568843033) -于 2026-10-07 12:07（Asia/Shanghai）成功完成，发布控制代码为 benchmark commit -`9eed5b49a18313e3883e78fabec10631c16a3367`。本次仅更新 Memoria，使用已经由 -[源码构建 run 37566751796](https://github.com/matrixorigin/memory_benchmarks/actions/runs/37566751796) -发布的固定 digest；该构建记录将 `main` 解析为下面的实际 SHA，不依赖浮动镜像 tag。 - -| 应用 | 实际版本 | -|---|---| -| 适配器 | `registry.cn-hangzhou.aliyuncs.com/moc-pub/plugin@sha256:c273b9605da1ec63f4462c8253d3254399c54ebd01a6cf55767b0105d36e4164` | -| Memoria | `registry.cn-hangzhou.aliyuncs.com/moc-pub/plugin@sha256:16d7eefa847749ffd4d61569419110a52b8de8fb78a283a8cd57df004d04ea8b` | -| Memoria 来源 | `matrixorigin/memoria`，ref `main`，实际 SHA `81c5cc6d5e86a34072ecbc1bb41979b06364e7c7` | -| Memoria 构建 tag | `registry.cn-hangzhou.aliyuncs.com/moc-pub/plugin:aml-memoria-20261007-81c5cc6` | - -两个 Deployment 均为 1/1 Ready、验收时无重启。Memoria 新 Pod UID 为 -`9d2e80a8-b759-4e30-82aa-ac2d2a3d5517`；适配器保留原 Pod UID -`3f3a7c5a-0e79-459a-957b-cae00cea7b93`、镜像及启动时间，单项更新的实际保留行为已验收。 -Ingress 为 `aml.cn-dev.matrixone.tech`，`aml-tls` Certificate Ready，正常 HTTPS -证书校验下 `/health`、`/ready` 均为 200。部署流程只执行健康检查；随后手动运行的 -两套完整小集 Add/Search 回归均已通过，见“修复版本的线上回归”。旧 inflight journal -未修改；健康检查与实际基准验收分别记录。 - -发布 workflow 使用独立的 `build`／`deploy` job，并由工作流级并发锁串行化。 -镜像构建及其 Docker／Rust 缓存位于 build runner；Go／Pulumi 位于新的 deploy runner。 -跨 job 只传递固定镜像 digest、Memoria 来源与配置快照 SHA-256。kubeconfig、运行凭据、 -私有 stack 配置及完整 Helm values 不作为输出或 artifact。两个 job 分别预检目标集群， -单项发布核对跨 job 快照摘要和 Pulumi 前的实时快照，变化时停止，不覆盖未选应用。 -构建记录继续由 build job 保存，image 模式记录本身不提供源码 SHA。 - -部署 job 将 Go 程序编译到 `deploy/pulumi/.bin/aml-pulumi`，在该 CI checkout 内设置 Go -runtime `binary` 后执行 preview／up，避免 Pulumi 再次编译。仓库中的 `Pulumi.yaml` -仍保留默认 Go runtime，不强制本地使用预编译文件。Go 检查继续执行，build job 不安装 -Go 或编译部署程序。`PULUMI_TOKEN` 仅进入 deploy job，凭据和临时配置各自在所在 job 清理。 - -磁盘启动阈值为适配器构建 3 GiB、Memoria 源码构建 12 GiB、Go 编译 6 GiB、Pulumi -执行 2 GiB，检查 workspace 与 `RUNNER_TEMP`；阈值不足则明确失败，并不承诺构建峰值 -永远不耗尽磁盘。build／deploy 超时分别为 90／60 分钟。仅更新 Memoria 且选择 image -模式时不创建 Docker 构建环境。main 来源、固定 digest、三个部署目标、原有证书等待与 -冻结保护继续采用既有设计；自动发布保持默认关闭。 - -上述隔离方案针对 -[run 37566751796](https://github.com/matrixorigin/memory_benchmarks/actions/runs/37566751796) -已证实的磁盘耗尽：源码镜像已推送成功，Pulumi 的 Go 再编译出现 -`no space left on device`，失败发生在资源修改前。当前线上版本通过固定镜像的 -[run 37568843033](https://github.com/matrixorigin/memory_benchmarks/actions/runs/37568843033) -部署，Repository Variable `AML_MEMORIA_IMAGE` 指向上表 digest，默认源码 ref 仍为 main。 -新版 workflow 的源码模式端到端发布仍须在合并后运行验收；既有成功部署不作为新版流程 -已通过的证据。 - -首次完整部署的 [run 37459492335](https://github.com/matrixorigin/memory_benchmarks/actions/runs/37459492335) -于 2026-10-06 完成；当时旧 Memoria `e180dff` 与同一适配器已通过 7 项公网最小联调： -owner 范围认证、同步 Add 后立即 Search、跨会话检索、用户隔离、幂等重试、top_k、空用户。 -耗时 16.32 秒，使用随机 UUID 用户，测试记忆随后逻辑停用、临时转发关闭；用户库、journal -及历史快照没有物理删除。该联调验证旧版本的真实数据库与上海 `BAAI/bge-m3` 调用， -不等同于新版本回归、AML 官方 Smoke 或榜单质量分数，也未独立校验原始向量维度。 - -修复版本已完成上述固定选择的完整写入／检索回归；剩余运行验收包括更大样本、 -可恢复 503 的原因观测、未知写入恢复、公网长请求与真实 SLB 超时、并发容量与时延、 -凭据丢失恢复及数据物理清理策略。通用 image 模式已通过本次 -源码产物部署，但既有 gitops 旧镜像的兼容性不因此得到验证。Answer/Eval、正式 AML -Smoke／Full 未由本次部署执行；部署成功不代表正式参评就绪。发布冻结、worker 参数、 -Helm 检查、ready 用例、依赖锁定、私有配置及初始化恢复保护继续采用现有设计。 - -后续代码和实验通过本项目任务／PR 共建。旧独立 Memoria 路径未迁入；未完成任务、 -验收条件和实际运行依据统一维护于 [Issue #1 当前任务清单](https://github.com/matrixorigin/memory_benchmarks/issues/1)。 diff --git a/agent_memory_leaderboard/docs/review-issue-1.md b/agent_memory_leaderboard/docs/review-issue-1.md deleted file mode 100644 index 1e0ddb1..0000000 --- a/agent_memory_leaderboard/docs/review-issue-1.md +++ /dev/null @@ -1,92 +0,0 @@ -# AML Issue #1：当前核实结论与处理状态 - -核实日期：2026-10-07。对象为 [Issue #1 正文及修正评论](https://github.com/matrixorigin/memory_benchmarks/issues/1)。正文审查的是 `b037c42`；本轮真实评测代码为 `origin/main@003dda1c5f1681d6a307dec9203968e3168992e6`。关联 Memoria 核对实际部署源码 `81c5cc6d5e86a34072ecbc1bb41979b06364e7c7`，并检查原评论引用的 `689f3f9` 中相关回退路径。代码、部署记录与评测结果分别作为各自范围的证据，不将旧版本结论直接视为当前状态。 - -## 总体结论 - -适配器已有真实 embedding、公网 HTTPS、镜像构建及完整小集 Add/Search 验证。输入标签隔离、Answer/Eval、重试观测、增量断点和诊断工具已合入，首个无标签 LoCoMo 历史的 87 道文本题全部完成作答判分。时间混合场景已复现历史证据不可见的配置风险；未知写入恢复、embedding token 边界、正式容量和官方 Smoke 仍待解决或验收。不能继续使用“没有真实环境验证”“全部只用模拟后端”的结论，也不能以小集成功表示参赛就绪。 - -Issue 按当前实现维护未完成任务、验收条件及版本证据，移除过时或无证据的断言。下表 -保留原编号以便定位审查范围；算法方向属于实验，不将所有建议列为已确认 bug。 - -## 逐项处理状态 - -| 原项 | 当前事实与应更正结论 | 处理状态 | -|---|---|---| -| #1 指标不等价 | 首个无标签历史已完成 Answer/Eval：自建 judge 56.32%、Recall@100 80.23%、覆盖 87／87。提示词与评分器由项目维护，原生 evaluator 和 AML 等价性未确认 | 自建闭环及首个基线完成；扩大覆盖、裁判审计和官方评分待验收 | -| #2 存储粒度 | 仍按消息及 32 KiB 字节切块，没有返回时邻接补全。实测首历史实际 prompt 约 4.9k–6.7k token，100 条记录全部进入预算；不能仅凭未填满窗口认定浪费 | 保留为对照实验；先审查标注证据已到位仍判错的题目 | -| #3 超限永久失败 | 32 KiB 仍不是模型 token 上限；持续 embedding 拒绝仍可能留下未知写入。实际使用上海 BAAI/bge-m3，不能用 text-embedding-v4 的限制代替当前 provider 契约。响应体重试修复不解决超长输入 | 待按实际模型核对边界及真实复现 | -| #4 未知写入恢复 | 已提交且能找到 marker 的写入可恢复；查不到时仍停留 inflight。timeout + grace 不能排除迟到提交；重复 marker 会使 recover 返回 502 | 缺口仍在，否定盲目超时重发方案 | -| #5 写入吞吐 | 每个记忆分片正常执行 store/get/search；全内容探针会再次计算 embedding。已测固定小集和 20 次低负载 Search，但未做正式规模写入／容量测试，也未接入批量写入 | 部分测量，尚未完成容量验收 | -| #6 真实部署验证 | 已有 embedding 真实最小联调、适配器／Memoria 镜像、公网 HTTPS，以及两套完整小集回归 | 本地真实联调和部署已完成；官方 Smoke 仍待执行 | -| #7 标签进入正文 | 新 runner 不把来源标签写入 Add，使用外置内容 hash manifest；首历史 8700 条返回记录全部匹配，歧义和未匹配均为 0；旧报告仍单独保留 | 已合入并完成首个无标签真实基线；改写／合块前仍需稳定 ID 映射 | -| #8 options | 接收但不参与 query；不自动违反协议，收益需要对照 | 实验项，不是必需协议修复 | -| #9 rerank／rewriting | 尚未添加。后端公开 Search 最多 100，300→100 需要内部候选能力；HyDE 生成内容不能冒充返回证据 | 实验项，先固定可信质量基线 | -| #10 时间衰减 | 来源 timestamp 仍映射 observed_at。实测旧记忆单独时走 fulltext 可见；新旧混合时走 hybrid，仅近期可见，旧记录仍 active；阈值两侧也只返回较新一侧 | 条件风险已复现；时间适配实验待实施，不宣称所有 Add 失败或全局衰减为 bug | -| #11 Memoria 能力 | 未接入独立事实／时间线双层抽取；普通写入已有实体抽取入口，无过滤主表 Search 已有图检索分支。unique subject 不等于禁用所有治理 | 更正“所有特色能力未使用”；实际启用与命中需看配置及 Explain | - -## 已取得的真实验证 - -[LoCoMo 回归 37571328104](https://github.com/matrixorigin/memory_benchmarks/actions/runs/37571328104) 完成 101/101 个 Add 批次、242/242 道文本检索，跳过 104 道多模态题；Recall@100 为 83.61%，Search P50/P95 为 0.99/2.63 秒，执行约 34.94 分钟。 - -[LongMemEval-S 回归 37574166791](https://github.com/matrixorigin/memory_benchmarks/actions/runs/37574166791) 完成 69/69 个 Add 批次和唯一一道题，证据排第一，执行约 11.02 分钟。两份 contract 与各自修复前失败运行一致，原失败批次全部完成；没有改写输入或重置旧 journal。 - -这些运行验证固定选择的数据接收和检索链路。LongMemEval 的 `answer_` 标签仍进入模型可见正文，其 100% 不能称作无标签泄漏的质量基线；也不能推断本轮高分由该标签造成。LoCoMo 已披露的异常 gold ID 仍按原 exact-ID 规则计分。两套结果都没有 Answer/Eval，不是官方 AML 成绩。 - -适配器访问日志还有 11/4 次中间 Add 503，既有有界重试后均完成。现有产物没有保存中间响应原因，不能将这些 503 归因于解码、未知写入或索引延迟。应补安全的重试次数／原因观测后定位。完整小集不是正式数据规模吞吐证明，也没有解决所有未知写入。 - -[干净基线 37594716119](https://github.com/matrixorigin/memory_benchmarks/actions/runs/37594716119) -完成 28 Add／87 Search／87 判分，覆盖率 100%，自建 judge 49／87；source attribution -无歧义／未匹配。5 次 Add 503 均为 `write_not_readable`，涉及 4 个逻辑批次并恢复； -这是新运行的诊断，不能反推旧运行 11／4 次 503 的原因。25 道标注证据全部进入 -预算但 judge 未通过，需受控抽查实际回答与裁判；不能直接认定检索算法有缺陷。 - -PR #9 的 [CI 37589473987](https://github.com/matrixorigin/memory_benchmarks/actions/runs/37589473987) -已通过，包含 280 项 pytest（1 warning）。真实 Explain 发现诊断白名单漏记 `hybrid` -后，本分支补充该路径和 8 个用例，完整 pytest 288 passed、Ruff 通过。聚合报告与 -验收范围见[当前方案](competition-plan.md#干净端到端基线2026-10-07)。 - -## 对历史来源时间评论的更正 - -Memoria [混合检索评分](https://github.com/matrixorigin/memoria/blob/81c5cc6d5e86a34072ecbc1bb41979b06364e7c7/memoria/crates/memoria-storage/src/store.rs#L6204) 确实按 observed_at 衰减，并剔除有效置信度小于 0.05 的候选。T1 初始 0.95、365 天衰减常数的计算本身没有变化。 - -但 [服务层](https://github.com/matrixorigin/memoria/blob/81c5cc6d5e86a34072ecbc1bb41979b06364e7c7/memoria/crates/memoria-service/src/service.rs#L1963) 在混合结果为空时继续全文检索；原评论引用的旧版也有这条分支。因此“混合路径过滤了旧证据”不能直接等同于“Search 一定没有结果／Add 一直失败”。普通无过滤 Search 还可能走图路径，最终行为与查询和过滤条件有关。 - -已有隔离合成探针使用 2023-05-08 和当前来源时间，两组 Add/Search 均 200，旧时间保存为 observed_at；未复现仅因该旧时间就阻塞 Add。常规公开数据 runner 仍只在正文保存日期、不发送 timestamp，故完整 benchmark 不能覆盖这条时间映射。 - -新增四组时间场景共 16 次请求全部成功，但混合场景三种 query（含旧文本精确查询） -均只返回近期记录；阈值两侧只返回较新侧。独立 owner-scoped Explain 分别观察到 -旧-only 为 fulltext、混合／阈值为 hybrid；结构化查询确认旧记录 active，observed_at -为来源时间、created_at 为本次写入时间。该结果与部署源码的过滤／回退条件一致。 - -现在应实验验证适配边界如何解耦来源时间与置信度年龄，同时保留原时间用于证据与 -时序推理；不将条件风险扩大为“所有 Add 必定失败”，也不据此全局关闭 Memoria 衰减。 -LoCoMo 基线未发送 timestamp，因此这项风险不能解释其答案分数。完整安全证据见 -[时间探针验收](competition-plan.md#时间与低负载探针验收2026-10-07)。 - -## 官方规则与策略需澄清 - -- **组别名称与模型要求仍有不一致之处。** 当前 Full checklist 已写 Open-source Methods 的 Add 阶段期望使用 gpt-4o-mini；不能继续笼统写“开源方法模型规则完全未出现”。但 FAQ 仍使用学术／工业分类，学术榜 embedding 指定 text-embedding-v4，开放权重模型建议工业榜。两套名称的映射、上海 bge-m3 对本次申报的资格，以及不使用 LLM 的纯存储 Add 是否适用该要求，仍需官方明确；不要自行把规则扩大到所有组件，也不要直接认定现配置合规。[当前文档](https://agentmemories.ai/zh-cn/docs)、[赛事 FAQ](https://agentmemoryleaderboard.ai/competition/) -- **117,760 是总输入预算。** 指令、问题及 options 也占预算，不能全部分配给检索证据；精确 Answer 模型、tokenizer、提示词和 evaluator 需按冻结契约核对。[API Guide](https://agentmemories.ai/api-guide) -- **配额仍是两次，保守规划一次是时间判断。** 第二次 Full 在第一次完成 30 天后解锁；失败／取消支持符合条件的断点续跑，不应理解成无法恢复或每次续跑都消耗新 Full。材料截止为 10 月 31 日，评测停止为 11 月 4 日。按 10 月 7 日当前时间规划，新的首次 Full 完成后再等 30 天已超出窗口。[赛事 FAQ](https://agentmemoryleaderboard.ai/competition/) -- **开放材料不要一刀切删除。** 需要清理凭据、私有部署配置和不能公开的评测轨迹；公开数据的下载器、解析器、来源链接和方法设计可按授权保留。公开 GitHub 固定 commit 是要求，所需完整复现范围仍需对齐官方审核。 -- **接口“逐点完全符合”过于绝对。** 基本 schema、认证与用户隔离已有验证，但内容策略拒绝和权限拒绝仍共用 403 等边界尚未解决；官方 Smoke、长请求、恢复和容量不能由单元测试或健康检查代替。 - -## P2 更新 - -- `/health` 是 liveness，符合基本协议；独立 `/ready` 已实现并有健康／上游不可用／journal 不可用及线程隔离用例。该项可完成，无需把上游依赖加入 liveness。 -- journal 仍是单 Pod SQLite／文件锁，支持同机多进程；不能水平扩展的范围限制成立，实测瓶颈没有确定。不以增加 worker 数量当作容量验收。 -- 逐题原子文件、最终合并及恢复读取方式已合入，有离线断点／失败续跑用例；真实首个 87 题流程通过，运行进程强杀和更大规模仍需验收。 -- README、部署／接入示例、Actions Summary、按版本与数据集的结果记录已经补齐；原“没有记录”应更新为现有证据与剩余覆盖范围。私人 artifacts 不应为了证明跑过而直接提交原始正文。 - -## 当前优先级 - -1. 抽查 25 道“标注证据已进入预算、judge 未通过”的题目；区分上下文、作答与裁判问题，避免只看总分修改算法。 -2. 针对已经复现的时间风险做适配边界对照；扩大干净 LoCoMo 与 LongMemEval-S 覆盖，保持模型、提示词、预算与评分版本固定。 -3. 处理 token／字节边界、可信的未知写入恢复；诊断新运行的 read-back 暂时不可读，不改变安全重试边界。 -4. 可信来源 ID 映射完成后再做粒度／邻接实验；options、rerank 的收益需对照。另行验收写入容量、公网长请求和物理清理。 -5. 对齐正式组别／模型／开放材料，完成官方 Smoke，再冻结版本并安排 Full。 - -正式方案、部署及结果的唯一维护入口为 [共建方案与工作计划](competition-plan.md)。继续基于同事的 memory_benchmarks 实现共建；旧独立适配工作只作为参考，不作为当前项目成绩。 - -本地开发能力、保留语义及验收边界见[当前设计](competition-plan.md#本地质量闭环与诊断设计)和[操作指南](../benchmarks/EVALUATION.md)。代码实现状态不替代已发布版本或真实运行证据。 diff --git a/deploy/README.md b/deploy/README.md index 87610ed..0479bf1 100644 --- a/deploy/README.md +++ b/deploy/README.md @@ -1,642 +1,216 @@ -# 历史阿里云 dev 发布参考 - -本目录保留旧阿里云 dev 部署代码和历史验收参考。原直部署 workflow 已移除，不再提供 -活动发布入口；本文的旧 workflow 操作步骤不再适用。当前 Memoria 和适配器运行于 QA， -由 moi-gitops 管理；评测使用 **QA memory benchmark** 与独立 QA key。 -ACR 镜像仓库和 DashScope 模型服务仍可继续使用，与服务是否运行在阿里云集群无关。 - -## 实施状态与 Review - -**Memoria 和适配器已在阿里云 dev 部署，公网最小联调通过。** -[部署 run 37459492335](https://github.com/matrixorigin/memory_benchmarks/actions/runs/37459492335) -使用本仓库 commit `3048f6bab82966ee63c25fbf5f6cb51cadf87c6d`，2026-10-06 完成 -离线检查、两个镜像构建与 ACR 推送、Pulumi up 和证书等待，全流程约 14 分 48 秒。 -两个 Deployment 均为 1/1 Ready、无重启，20Gi journal PVC 已绑定。 -公网入口为 `https://aml.cn-dev.matrixone.tech`；证书 Ready，正常 TLS 校验下 -`/health`、`/ready` 返回 200，未带 key 的 `/search` 返回 401。 - -现有 `src.smoke` 通过公网适配器和临时本地 Memoria Service 转发验证了 owner 认证、 -同步 Add 后立即 Search、跨会话检索、用户隔离、幂等重试、top_k 和空用户，共 7 项， -耗时 16.32 秒。测试仅使用随机 UUID 用户，测试记忆已逻辑停用，转发已关闭； -未物理删除用户库、journal 或历史快照。此为项目集成测试，不是 AML 官方 Smoke 或质量评分。 -Memoria 默认从 `matrixorigin/memoria` 的 `main` 分支构建， -也支持选择其他分支、tag、commit 或已发布镜像；实际部署始终使用镜像 digest。 -当前已于 2026-10-07 更新到 `main@81c5cc6d5e86a34072ecbc1bb41979b06364e7c7`， -包含 Memoria PR #277／#278，使用上述最小联调后的独立更新 -[run 37568843033](https://github.com/matrixorigin/memory_benchmarks/actions/runs/37568843033)。 -新 Pod Ready，公网健康检查为 200；新版本完整基准仍待复测。上文 7 项联调属于旧版本。 -具体 digest 和剩余验收范围见方案文档的[当前交付状态](../agent_memory_leaderboard/docs/competition-plan.md#当前交付状态)。 - -Memoria 显式采用多库模式：`DATABASE_URL` 与 `MEMORIA_SHARED_DATABASE_URL` 指向同一 -专用共享库 `aml_memoria`，`MEMORIA_MULTI_DB=1`。初始化脚本为专用角色授予共享库权限及 -`CREATE DATABASE ON ACCOUNT *`；用户库由 Memoria 按需创建并由该角色拥有。 -当前版本的共享 schema、按需用户库及带上海 embedding 配置的真实 Add/Search 已通过最小联调。 -控制项与权限边界见[数据库模式与部署兼容性](../agent_memory_leaderboard/docs/competition-plan.md#数据库模式与部署兼容性)。 - -完整方案、交付状态、源码导航和 Review 重点见 -[CI/CD 交付概要与 Review 入口](../agent_memory_leaderboard/docs/competition-plan.md#cicd-交付概要与-review-入口)。 -本文维护发布配置和操作步骤，设计决策统一维护在方案文档。 - -## 资源与所有权 - -| 项目 | 配置 | -|---|---| -| Pulumi stack | `MatrixOneCloud/memory-benchmarks/new-dev` | -| Kubernetes namespace | `aml-memory-benchmarks` | -| Memoria | 单副本，内部 Service `aml-memoria:8100` | -| Add/Search 适配器 | 单副本，内部 Service `aml:80`；公网由 NGINX Ingress 接入 | -| journal | `aml-adapter-state` PVC，20Gi，`alicloud-disk-essd-pl0`，RWO | -| 数据库 | 专用共享库 `aml_memoria`，以及 Memoria 按需创建的 `mem_u_` 用户库 | -| 数据库用户／角色 | `aml_memoria`／`aml_memoria_role`，共享库权限＋建库权限＋新建对象所有权 | - -私有 `new-dev` 配置固定了 API Server 和 `kube-system` UID，阻止误用 AWS 或控制面 -kubeconfig。此 stack 管理新建的应用资源，复用 unit 集群、MatrixOne 和 NGINX。 -namespace 与 journal PVC 受 Pulumi `protect` 保护；删除环境时需要显式解除保护。 -数据库用户、角色和库在一次性初始化步骤中创建，不由 Helm 卸载或 Pulumi destroy 删除。 - -同名 `new-dev` 存在于多个 gitops Pulumi project 中。控制面 -`cloud-service/new-dev` 的 `moi-main/moi-memoria` 属于另一集群，本项目部署自己的 -`aml-memoria`。应用发布入口只操作本项目独立 stack。 - -### 私有环境配置 - -`deploy/pulumi/Pulumi.new-dev.yaml` 只保存在本地并被 gitignore 排除；仓库提交 -`Pulumi.new-dev.example.yaml`，集群地址、UID 和数据库租户标识使用占位符。 -现有本地配置已保留。首次本地配置可复制 example，填入受控环境标识；不要提交实际文件。 - -CD 从三个 Repository Variables 生成同一格式的私有配置： -`AML_EXPECTED_API_SERVER`、`AML_EXPECTED_CLUSTER_UID`、`AML_DATABASE_ACCOUNT`。 -这些是环境标识，不是认证密钥；已从现有私有配置上传。集群和租户身份校验继续生效。 -`configure_github.py` 后续也会从本地私有文件同步这些 Variables。 - -## 一次性数据库初始化 - -管理员连接配置只用于本地初始化。支持 `DATABASE_URL=mysql://...` 和 `mysql -h ...` -形式；解析后使用驱动连接，不执行文件中的 shell 命令。 +# 部署参考 + +本目录提供 Memoria 与 AML Add/Search 适配器的部署模板和辅助工具。 +具体环境的部署计划、验收记录和历史运行结果由环境维护者保存在本地， +公开文档不声明某个线上版本已经通过验收。 + +## 目录与配置边界 + +| 路径 | 用途 | +| --- | --- | +| `chart/` | Memoria、适配器、持久卷、Service 和可选 Ingress/TLS 模板 | +| `pulumi/` | 历史独立 dev stack 与目标配置示例 | +| `docker/` | 从固定 Memoria 源码构建镜像的配方 | +| `scripts/` | 配置生成、目标核查、数据库初始化、镜像及发布辅助工具 | +| `memoria-source.json` | Memoria 源码构建来源配置 | + +当前仓库的 GitHub Actions 提供离线检查、适配器镜像构建及手动 QA benchmark， +不会自动部署应用。历史阿里云直接部署 workflow 已移除；保留的 Pulumi 和辅助脚本 +不是当前共享环境的发布入口。环境更新应沿用对应 GitOps 仓库的 review 与发布流程。 + +运行前应核对目标、存储、入口、数据库和模型服务配置。不要用示例值直接更新共享环境。 +保留现有的目标身份核查和凭据边界；数据库初始化工具需要有权创建运行账号与授权的维护者执行。 + +## 运行配置 + +适配器必须连接兼容的 Memoria HTTP 服务，并配置 Memoria master key。 +Memoria 的数据库和 embedding 配置由后端维护，普通 Add/Search 客户端不需要这些凭据。 + +| 配置 | 说明 | +| --- | --- | +| `MEMORIA_URL` | 适配器访问的 Memoria 地址 | +| `MEMORIA_MASTER_KEY` | 适配器上游凭据；通过私有环境或 Secret 注入 | +| `ADAPTER_API_KEY` | 客户端访问适配器使用的独立凭据 | +| `MEMORIA_NAMESPACE` | 将本次用途与其他评测或服务隔离的命名空间 | +| `ADAPTER_STATE_DIR` | 稳定、持久化的 SQLite journal 目录 | + +配置项、默认值及协议要求见[适配器说明](../agent_memory_leaderboard/README.md) +和[环境变量示例](../agent_memory_leaderboard/.env.example)。 +部署工具中的 `AML_*` 变量名与应用运行时变量名不同，不能直接混用； +按所选模板和脚本的实际映射配置。 + +镜像支持按固定源码构建或引用已有 `repository@sha256:...`。 +保存实际源码与镜像 digest 的对应关系；镜像名称、tag 和 digest 本身不是凭据。 + +环境配置、私钥、运行报告和数据库文件应存放于 Git 忽略的目录。 +内部文档可以使用仓库根目录的 `var/private-docs/`，或适配器目录下的 `var/`。 +这些路径不属于公开文档依赖，复制模板时也不应把它们加入构建上下文或提交。 + +## 本地复现 + +### 1. 固定版本与依赖 + +准备 Git、Python 3.12+ 和 uv。部署完整后端时还需要 Docker 与 Compose； +使用 Kubernetes 模板时需要 Helm 及一个独立的复现环境。 + +检出待复现的完整 mb commit，不使用随时间变化的 `main` 作为版本标识： ```sh -uv venv .deploy-venv --python 3.12 -uv pip install --require-hashes --only-binary=:all: --python .deploy-venv/bin/python -r deploy/requirements.txt -.deploy-venv/bin/python deploy/scripts/bootstrap_db.py \ - --admin-file agent_memory_leaderboard/.env --apply +git clone https://github.com/matrixorigin/memory_benchmarks.git +cd memory_benchmarks +git checkout --detach '' ``` -脚本创建数据库、数据库角色及独立用户，并将运行密码、Memoria master key 和适配器 -API key 保存为 `deploy/.runtime.env`，权限 `600`。文件已被 gitignore 排除。 -后续重跑复用这个文件，不重设既有用户密码，不删除库或数据。专用用户已经存在而文件 -缺失时，脚本在生成凭据和执行 DDL 前停止，直接提示恢复方式；新建用户也不使用 -`IF NOT EXISTS` 掩盖并发创建造成的密码差异。凭据更新采用原子替换，临时文件同样忽略。 - -恢复时优先从受控备份取回完整 `.runtime.env`；若需要管理员明确轮换 SQL 密码，随后 -同步 `AML_DATABASE_PASSWORD` GitHub Secret 与服务配置。master key 和 adapter key -单独恢复或轮换。登录失败会提示保留原文件并检查密码／角色，不要删除后盲目重跑。 - -这里的独立账号指 **数据库登录用户**。现有连接属于一个 MatrixOne 租户；本方案没有 -新建整个租户。角色拥有共享库和其表上的权限，以及租户级 `CREATE DATABASE` 权限。 -运行时新建的用户库和表归该角色所有；不授予 `accountadmin`、全局表权限或租户级删库权限。 -建库权限不能限制为某个名称前缀，owner 前缀也不是 SQL 权限边界；该用户可以创建其他新库， -但不应访问其他角色拥有的业务数据。计算资源仍共用；若需要租户级权限／容量隔离，应另建 -MatrixOne account。重复运行上述初始化命令可补齐授权，原有密码和两个 API key 保持不变。 -权限语法参见 [MatrixOne GRANT](https://docs.matrixorigin.cn/en/v26.3.0.13/MatrixOne/Reference/SQL-Reference/Data-Control-Language/grant/)。 - -2026-10-06 已用现有凭据重跑初始化并验证：共享库重复创建、新建自有库／表、CRUD、 -ALTER、索引与自有库删除成功；另一个管理员角色拥有的临时库的读取、更新、删除均被拒绝。 -权限验证仅使用合成数据，临时库已清理。部署后的最小联调也已验证 Memoria schema 初始化及首次 Add/Search。 - -### 测试用户与认证 - -通过适配器测试无需预注册 Memoria 用户，也无需为每位 AML 用户生成 Memoria API key。 -客户端提供 `Authorization: Bearer ` 以及请求体中的 `user_id`。 -适配器将 `[namespace, user_id]` 稳定哈希为 owner，使用内部 -`Authorization: Memoria-Owner ` 和 `X-User-Id: ` 调用 -Memoria；首次访问需要存储的用户时，Memoria 按需初始化用户库和 schema。 - -同一测试用户的 Add/Search 必须使用相同 `user_id`，跨会话可检索该用户的记忆。 -更换 `user_id` 会进入另一用户范围；不要在重试时改变 `user_id` 或部署 owner 前缀。 -AML auth key 验证调用方，`user_id` 决定数据归属，二者不能互相替代。 -`AML_MEMORIA_MASTER_KEY` 和 SQL 密码仅用于内部服务，不交给 AML。 -部署前仍须执行专用 SQL 用户／角色／共享库初始化；这与创建测试用户是两件事。 - -## GitHub Actions 配置 - -离线 `CI - Lint, Tests & Adapter Build` 无须手工配置 Secret。下面的运行凭据用于 -`AML Aliyun dev deployment`，**preview 和 deploy 均需要**，因为 preview 也会检查 -目标集群并推送镜像。源码公开仓库的 checkout 使用 Actions 自动提供的 -`GITHUB_TOKEN`，当前无须额外配置 GitHub PAT。 - -### Secrets - -| 名称 | 来源及用途 | 配置范围／当前状态 | -|---|---|---| -| `KUBECONFIG` | 必填，来自 `~/dev/unit-kubeconfig` 的完整原始 YAML；用于部署到指定阿里云 unit 集群。不填写文件路径，不做 base64 编码 | Repository Secret，已上传 | -| `PULUMI_TOKEN` | 必填，Pulumi Cloud access token；需有 `MatrixOneCloud/memory-benchmarks/new-dev` 创建／读写权限。workflow 映射为 `PULUMI_ACCESS_TOKEN` | Repository Secret，已通过本次 Pulumi up | -| `NEW_ACR_USERNAME` | 必填，Hangzhou ACR 登录用户名，用于推送和 Pod 拉取镜像 | Organization Secret，本仓库已有访问授权 | -| `NEW_ACR_PASSWORD` | 必填，与上述用户名匹配的 ACR 登录密码；需能推送／拉取适配器及 Memoria 仓库 | Organization Secret，已通过镜像推送与 Pod 拉取 | -| `AML_DATABASE_PASSWORD` | 必填，专用 `aml_memoria` SQL 用户密码，来自生成的 `deploy/.runtime.env`；供 Memoria 连接数据库 | Repository Secret，已上传 | -| `AML_MEMORIA_MASTER_KEY` | 必填，生成于 `deploy/.runtime.env`，至少 32 字符；Memoria 与适配器上游调用共用，独立于对外 key | Repository Secret，已上传 | -| `AML_ADAPTER_API_KEY` | 必填，生成于 `deploy/.runtime.env`，至少 32 字符且与 master key 不同；AML 调用 Add/Search 时使用 | Repository Secret，已上传；正式参评时向 AML 平台提供此 key | -| `AML_EMBEDDING_API_KEY` | 当前上海 embedding 服务必填，由该模型服务提供有效 key；Memoria 使用 `Authorization: Bearer ` 调用 | 必需 Repository Secret，已配置；无 key 返回 401，带配置 key 的真实 Add/Search 联调通过 | - -2026-10-06 只读核对 GitHub 名称元数据：六个必需 Repository Secrets 均已存在， -两个必需 Organization Secrets 对本仓库可用，当前没有缺失的必需 Secret 名称。 -Secret 名称核对本身不证明凭据有效；本次实际部署另行验证了集群、Pulumi、ACR、 -数据库及应用认证链路。后续轮换或权限变更仍须重新验收。 - -配置入口是本仓库 `Settings → Secrets and variables → Actions → Secrets`。 -新增 Repository Secret 时填写表中名称和值；通常只填写值，不填写 `KEY=` 或外围 -引号。`KUBECONFIG` 的值是完整 YAML。组织已有的 ACR 凭据由组织维护，本仓库已有 -授权，无需复制；若组织调整访问范围，需要保留 `memory_benchmarks` 的访问权限。 -GitHub 配置方式见 [官方 Secrets 文档](https://docs.github.com/en/actions/how-tos/write-workflows/choose-what-workflows-do/use-secrets)。 - -Pulumi token 来源为 Pulumi Cloud 的 access token 管理，本项目读取的 GitHub Secret -名称是 `PULUMI_TOKEN`。组织中同名用途的 `PULUMI_ACCESS_TOKEN` 不会自动替代它， -以当前 workflow 引用为准。[Pulumi access tokens](https://www.pulumi.com/docs/administration/concepts/access-tokens/) - -管理员密码不进入 workflow 或 Pod。运行 DSN 在 Pulumi 中使用独立用户密码生成，用户名 -和密码按 URL 规则编码，以 secret value 传入 Kubernetes Secret；不在 stack output -中输出任何 key、DSN 或 kubeconfig。 - -首次配置可通过 `deploy/scripts/configure_github.py` 从本地文件上传 kubeconfig 和三个 -运行 Secret，输入经 stdin 交给 `gh`，不显示或放入命令行参数。该工具同时设置适配器 -镜像仓库及 Memoria 构建模式，可选配置来源 ref、Memoria 镜像仓库或现成镜像 digest； -不触发 Actions，也不启用 main 自动发布。默认 `--memoria-build-mode source`， -源码模式不要求 `--memoria-image`。 - -例如，在仓库根目录执行以下命令可从既有本地文件重新上传配置，命令不打印密钥值， -不会运行部署；已有配置完整时无须重跑： +用同一套源码运行该版本的锁定依赖。Memoria 必须支持 owner 隔离、metadata 查询 +及相应写入协议；具体兼容行为见[重试与部署状态](../agent_memory_leaderboard/README.md#retries-and-deployment-state)。 +若已有兼容 Memoria 服务，可直接执行第 3 步。 + +### 2. 准备 Memoria 与数据库 + +从 [Memoria 仓库](https://github.com/matrixorigin/memoria)检出待复现的完整 commit， +按照该版本 README 的 Quick Start 和 `docker-compose.yml` 配置 MatrixOne、API 和 embedding。 +Memoria 与 MatrixOne 的配置属于后端部署；只启动 mb 不会自动创建完整后端。 + +最低需要核对： + +- MatrixOne 可连接，数据库运行账号具备所选存储模式所需的建库、迁移与读写权限。 +- Memoria master key 已配置，API 可访问；该 key 与适配器的客户端 key 分开。 +- embedding 服务地址、模型、维度和鉴权有效，维度与该版本数据库配置一致。 +- 数据目录持久化；重建实例、变更模型或维度不能被当作无影响的镜像替换。 + +新建完整 Compose 环境的操作由 Memoria 对应版本的部署说明定义。 +若使用本仓库的 [Compose overlay](../agent_memory_leaderboard/README.md#docker-deployment-with-memoria)， +它会将适配器接入该 Compose 的网络并持久化 journal；先配置好上游 `.env`， +不要同时按 overlay 和下方 uv 方式启动两个占用相同端口的适配器。 + +### 3. 启动适配器 + +以下命令在仓库根目录开始执行。先填写自己的 Memoria 地址、与后端一致的 master key +和独立的适配器 key；示例值不能作为真实凭据使用。 ```sh -rtk proxy .deploy-venv/bin/python deploy/scripts/configure_github.py \ - --kubeconfig ~/dev/unit-kubeconfig \ - --adapter-repository registry.cn-hangzhou.aliyuncs.com/moc-pub/plugin \ - --memoria-build-mode source --memoria-ref main \ - --memoria-repository registry.cn-hangzhou.aliyuncs.com/moc-pub/plugin +cd agent_memory_leaderboard +uv sync --locked +mkdir -p var +chmod 700 var +cat > var/reproduction.env <<'EOF' +MEMORIA_URL=http://127.0.0.1:8100 +MEMORIA_MASTER_KEY='replace-with-your-memoria-master-key' +ADAPTER_API_KEY='replace-with-a-separate-adapter-key' +MEMORIA_NAMESPACE=local-reproduction-v1 +ADAPTER_STATE_DIR=./var +MEMORY_TIME_NORMALIZATION_ENABLED=false +EOF +chmod 600 var/reproduction.env +# 编辑本机的 var/reproduction.env，替换地址和凭据后，再显式加载： +set -a +. ./var/reproduction.env +set +a +uv run --no-sync uvicorn src.app:create_app --factory --host 127.0.0.1 --port 8000 ``` -该脚本上传 kubeconfig、数据库密码和两种运行 key，设置镜像及来源 Variables。 -Pulumi token、组织 ACR 凭据、embedding key 通过对应的 GitHub 设置单独维护。 - -当前发布代码只使用 Kubernetes provider，复用既有 cert-manager／ClusterIssuer， -无需在本仓库新增阿里云 RAM AccessKey、DNS 签发凭据或证书私钥。其 DNS 凭据由既有 -基础设施维护。当前 Add/Search 流程不要求 LLM 或 rerank key；发布流程不运行官方 -AML 评测，因此 AML 平台的评测授权 key 也不属于此 CI/CD 配置。 - -### Variables - -| 名称 | 要求／用途 | -|---|---| -| `AML_EXPECTED_API_SERVER` | 必填，目标 unit Kubernetes API 的 HTTPS 地址；从私有 dev 配置上传 | -| `AML_EXPECTED_CLUSTER_UID` | 必填，目标 `kube-system` UID；从私有 dev 配置上传 | -| `AML_DATABASE_ACCOUNT` | 必填，现有 MatrixOne 租户 UUID；不是专用 SQL 用户密码 | -| `AML_ADAPTER_REPOSITORY` | 必填，当前为 `registry.cn-hangzhou.aliyuncs.com/moc-pub/plugin`；需有该仓库推送权限 | -| `AML_MEMORIA_BUILD_MODE` | 可选，`source` 或 `image`；省略时按 `deploy/memoria-source.json`，默认 `source` | -| `AML_MEMORIA_REF` | 可选，Memoria 分支、tag 或 commit；省略时使用配置文件中的 `main`；手动发布可覆盖 | -| `AML_MEMORIA_REPOSITORY` | 源码模式可选，默认使用适配器的同一 ACR 仓库；当前同为 `registry.cn-hangzhou.aliyuncs.com/moc-pub/plugin`，由不同项目 tag 前缀区分 | -| `AML_MEMORIA_IMAGE` | 仅 `image` 模式必填，现成的 `repository@sha256:...`；源码模式使用本次构建返回的 digest，忽略此变量 | -| `AML_DEV_CD_ENABLED` | 可选，`true` 才启用 main push 自动部署；默认仅手动发布 | -| `AML_FREEZE` | 可选，`true` 阻止自动和手动部署；空或 `false` 允许，其他值拒绝继续；preview 仍可执行 | -| `AML_ADAPTER_WORKERS` | 可选，正整数，默认 `1`；传给 Helm `workers` 与 Uvicorn，不增加 Pod 副本数 | -| `AML_PUBLIC_HOST` | 已设置为 `aml.cn-dev.matrixone.tech`，DNS、Ingress、证书及 HTTPS 最小联调已通过 | -| `AML_TLS_SECRET` | 可选，cert-manager 生成的 TLS Secret 名，默认 `aml-tls` | -| `AML_CERT_ISSUER` | 可选，默认复用 Ready 的 `aliyun-prod-letsencrypt` ClusterIssuer | - -### 镜像名称结构 - -镜像 tag 引用格式为 `//:`， -实际部署引用为 `//@sha256:<64 位 digest>`。 -当前统一使用 `registry.cn-hangzhou.aliyuncs.com/moc-pub/plugin`： - -| 服务 | ACR namespace | repository | project 前缀 | -|---|---|---|---| -| Add/Search 适配器 | `moc-pub` | `plugin` | `aml-memory-adapter` | -| 源码构建 Memoria | `moc-pub` | `plugin` | `aml-memoria` | - -构建 tag 格式为 `--<7 位 commit SHA>`，日期在一次工作流运行中 -统一取 UTC 构建日期。适配器 SHA 来自 `memory_benchmarks`，Memoria SHA 来自所选 ref -的实际 checkout；两者同仓库但使用不同项目前缀。对应完整格式为： - -```text -registry.cn-hangzhou.aliyuncs.com/moc-pub/plugin:aml-memory-adapter-- -registry.cn-hangzhou.aliyuncs.com/moc-pub/plugin:aml-memoria-- -``` +应用不自动加载 env 文件。此例的 journal 保存在 `agent_memory_leaderboard/var/`， +重启或重试时保留该目录、namespace、用户和请求标识。需要全新独立运行时使用新的 +namespace 并单独管理旧数据，不能通过清空 journal 恢复未知写入。 +时间注释在示例中保持关闭；复现开启该功能的版本时应明确设为 `true` 并记录。 -`AML_ADAPTER_REPOSITORY` 和 `AML_MEMORIA_REPOSITORY` 均配置为上述共享仓库； -Memoria 变量省略时也默认使用适配器仓库。构建脚本允许共享仓库，并生成不同前缀的 tag。 -仓库 Variables 只填写 `//`，不带 tag 或 digest； -`AML_MEMORIA_IMAGE` 属于现成镜像模式，要求完整 digest 引用。 -可选的既有现成镜像仍引用 `moc-pub/memoria` 下真实已发布的 digest；源码模式向 -`moc-pub/plugin` 推送，不依赖该既有引用。此处 ACR namespace 与 Kubernetes namespace -`aml-memory-benchmarks` 独立。tag 用于查找，实际发布始终使用构建返回的 digest。 -两个源码镜像已成功推送到该仓库，并由 dev Pod 成功拉取。 - -Memoria embedding 默认配置来自 gitops dev：`BAAI/bge-m3`、1024 维、上海服务 -`https://bgem3.model.shanghai.idc.matrixorigin.cn:30443/v1`。当前 key 与配置下的 dev Memoria -写入／检索联调已通过；模型质量仍需基准评测。本适配器只调用普通存储／检索接口， -此发布配置不要求 LLM 或 rerank 模型。 -不混用不同 embedding 模型的既有向量；固定模型后再建立质量基线。 - -2026-10-06 从本机使用正常 HTTPS 证书校验，向上述服务的 `/embeddings` 发送一条 -`model=BAAI/bge-m3` 的短文本请求，不发送 Authorization 或其他 API key。服务在约 -0.071 秒内返回 HTTP `401`，内容为 `{"error":"Unauthorized"}`。 -**当前公网接口不接受匿名调用，部署必须提供 `AML_EMBEDDING_API_KEY`。** -workflow 配置检查与 Pulumi 程序均将该 key 列为必填，缺失时在创建应用资源前失败。 -匿名探针仅验证鉴权行为；部署后的真实 Add/Search 已使用配置的 key 和模型完成。 -该最小测试没有独立检查模型原始向量长度，也不提供检索质量评分。 - -当前 `AML_MEMORIA_IMAGE` 为 -`registry.cn-hangzhou.aliyuncs.com/moc-pub/plugin@sha256:16d7eefa847749ffd4d61569419110a52b8de8fb78a283a8cd57df004d04ea8b`， -对应 `main@81c5cc6` 的源码构建产物。只有选择 `image` 模式才使用该 Variable； -源码模式默认构建 `main`，流程不会自动将 Variable 改写为构建结果。更换现成版本时更新 -`AML_MEMORIA_IMAGE`，并保留构建来源与对应质量基线。 - -### 从 Memoria 源码构建 - -Memoria 源码构建只在本项目的 **AML Aliyun dev deployment** 中执行。 -日常 PR／main push 的 **CI - Lint, Tests & Adapter Build** 保留适配器镜像检查，不构建 Memoria。 - -| 发布选择 | 是否构建 Memoria | -|---|---| -| `deployment_target=both` 或 `memoria`，有效模式为 `source` | 构建并推送，`preview` 和 `deploy` 均执行 | -| `deployment_target=memory_benchmarks` | 跳过，保留当前 Memoria 镜像 | -| 更新 Memoria，有效模式为 `image` | 跳过，使用指定 digest 镜像 | - -`configured` 按已有配置解析为 `source` 或 `image`。若启用 main push 自动发布， -该发布 workflow 也会按上述规则构建；自动发布默认关闭。 -默认来源在 [memoria-source.json](memoria-source.json)： - -```json -{"default_mode": "source", "repository": "matrixorigin/memoria", "ref": "main"} -``` +### 4. 验证链路与运行 benchmark -手动发布时 `memoria_build_mode=configured` 使用仓库配置，选择 `source`／`image` -可覆盖本次模式；`memoria_ref` 留空时使用 `AML_MEMORIA_REF` 或配置文件中的 `main`。 -填入 `feature/example` 可构建该分支，填入 tag 或完整 commit SHA 可指定相应版本。 -benchmark workflow 自身仍从 `memory_benchmarks/main` 运行；Memoria 来源 ref 与它独立。 -更换源码仓库时编辑上述 JSON，默认仓库是公开仓库，跨仓库 checkout 使用 GitHub token。 -来源分支／tag 必须存在于该远端仓库；本地未推送的修改不会进入发布 workflow 的源码构建。 -Memoria 仓库有新提交不会自动触发本仓库的发布，需要手动触发，或由已启用的 -本仓库 main push 发布读取其最新版本。 - -工作流 checkout 来源 ref 后记录实际完整 commit；构建期间继续使用这份 checkout。 -镜像推送至 `registry.cn-hangzhou.aliyuncs.com/moc-pub/plugin`，以 -`aml-memoria--<实际 SHA 前 7 位>` 标记，再按构建返回的 digest 部署。 -适配器使用同仓库和不同项目前缀；需要确保仓库存在且 ACR 凭据具备推送／拉取权限。 -本次 CD 已验证两个镜像的推送与 Pod 拉取权限。 - -构建使用本项目的 [Memoria Dockerfile](docker/memoria.Dockerfile)，上下文是检出的 -Memoria 仓库根目录，使用 `cargo build --locked --release --bin memoria`。 -Rust `1.90.0` builder 和 Debian Bookworm runtime 均固定镜像 digest，使用 BuildKit -Cargo cache mounts 和 GHA 层缓存；临时 runner 不保证跨运行保留 cache mount 内容。 -运行进程为 UID 1000，执行 `memoria serve`，日志输出到标准输出。 -原 Memoria Dockerfile 默认 Rust `1.85`，而当前 lock 中含要求 `1.88` 的依赖； -此独立构建文件在本项目维护，源码分支不需要包含新的 Dockerfile。以后依赖提高最低 -编译器版本时，应在本项目更新 builder 并验收构建。 - -本地使用同一构建文件的示例： +另开终端，在同一适配器目录加载自己刚才填写的环境文件，然后运行： ```sh -cd ~/runtime-agent/memoria -rtk proxy docker build --platform linux/amd64 \ - -f ../memory_benchmarks/deploy/docker/memoria.Dockerfile -t memoria:aml-local . +set -a +. ./var/reproduction.env +set +a +curl --fail --silent --show-error http://127.0.0.1:8000/ready +uv run --no-sync python -m src.smoke --adapter-url http://127.0.0.1:8000 ``` -本地未执行此示例命令。发布 workflow 的源码模式负责 checkout、构建、推送及 digest -传递；构建失败会阻止后续发布。`image` 模式跳过 Memoria checkout 和构建。 - -CD 将 ref、实际完整 commit、构建 tag／UTC 日期、镜像 digest、构建 Dockerfile hash 和 benchmark commit -保存到 Actions summary 与 `memoria-build--` artifact，保留 30 天； -Pulumi output 和 Memoria Pod annotation 同时记录来源 repo／ref／commit。 -该记录证明镜像选择，不能单独证明部署成功或评测通过。评测报告应另存这些版本信息。 -使用 `main` 时不同运行可能得到不同 commit；需要重放 preview 或某次评测的版本时， -将记录中的完整 commit 填入 `memoria_ref`，或使用 `image` 模式指定那次镜像 digest。 +项目 smoke 会实际写入并检索测试记忆，需要正常的数据库和 embedding 服务， +会消耗资源；它不等于 AML 官方 Smoke，也不替代完整 benchmark。 +该版本的数据准备、运行命令、评分协议和已知限制见 +[benchmark 总览](../agent_memory_leaderboard/benchmarks/README.md)及 +[评估说明](../agent_memory_leaderboard/benchmarks/EVALUATION.md#local-commands)。 +对齐官方结果还应核对官方冻结的版本、协议及模型要求，不能仅凭本地 smoke 成功判断一致。 -在本项目接入源码构建的范围与版本记录要求见 -[方案中的镜像选择与源码构建](../agent_memory_leaderboard/docs/competition-plan.md#memoria-镜像选择与源码构建)。 +## Kubernetes 模板复现 -## 发布流程 +`chart/` 同时渲染 Memoria 与适配器，不包含 MatrixOne 数据库、embedding 服务、 +运行 Secret、registry Secret 或 journal PVC 的完整创建流程。这些资源必须由 +独立复现环境的维护者提前配置；相关默认名称可在 [values.yaml](chart/values.yaml) 中修改。 -### Actions 参数填写 - -在本仓库 **Actions → AML Aliyun dev deployment → Run workflow** 操作。 -目前已有完整 dev 部署，后续使用同一 stack 更新已有服务；不用重新创建数据库或测试用户。 - -| 场景 | workflow 分支 | operation | deployment_target | memoria_build_mode | memoria_ref | -|---|---|---|---|---|---| -| 首次部署／更新两个服务 | `main` | `deploy` | `both` | `source` | `main` 或指定 Memoria ref | -| 只更新 Memoria | `main` | `deploy` | `memoria` | `source` | 指定 Memoria 分支、tag 或 SHA | -| 只更新适配器 | `main` | `deploy` | `memory_benchmarks` | `configured`（此场景忽略） | 留空（此场景忽略） | -| 预览上述变更 | `main` | `preview` | 对应范围 | 与实际发布一致 | 与实际发布一致 | - -workflow 的分支决定 `memory_benchmarks` 代码；`memoria_build_mode` 和 `memoria_ref` -只控制 **Memoria**。`source` 从源码构建；`configured` 读取已配置模式（默认源码）； -`image` 使用 `AML_MEMORIA_IMAGE` 的固定 digest 镜像。ref 留空时使用已配置来源，默认 `main`。 -输入 `deploy` 才实际更新应用；需要先检查变更时按下面的 preview／deploy 两步执行。 - -### 执行步骤 - -1. 将变更合入 `main`，填写上述 Secrets／Variables。 -2. Actions 中选择 **AML Aliyun dev deployment**，点击 **Run workflow**。 - workflow 分支选择 `main`，`operation` 选择 `preview`，`deployment_target` 选择 `both`， - `memoria_build_mode` 选择 `source`，`memoria_ref` 填 `main`。 - 它先选择 - Memoria 来源并检出源码，核对目标集群、权限和 StorageClass，运行离线检查， - 构建并发布适配器及所选 Memoria 镜像，再预览独立 Pulumi stack。 - **preview 也会发布镜像，并可能创建空的 Pulumi stack，但不创建 Kubernetes 应用资源。** -3. 再次点击 **Run workflow**，保持上述分支／来源参数，将 `operation` 改为 `deploy` - 执行发布。程序等待 Helm 和 Pod 就绪，单个 dev 发布串行执行。 - 任务入口和 `up` 前检查冻结，Pulumi 对真实更新也检查 `AML_FREEZE`。 - 自动部署默认关闭，Actions 不调用真实 Add/Search 或启动基准／官方评测。 -4. 核对公网域名的 DNS 和 `AML_PUBLIC_HOST`（当前均已配置）。chart 创建应用自己的 `Certificate`， - 现有 cert-manager 使用阿里云 DNS-01 自动签发、保存及续期 TLS Secret；发布等待 - Certificate Ready。DNS A 记录应指向 unit 集群 - NGINX 公网地址；2026-10-06 只读核实的地址是 `47.97.230.53`，以发布时实际值为准。 -5. 公网启用后的目标接口为 `https:///add` 和 `https:///search`。 - 验收 DNS、证书、鉴权、真实写入检索、用户隔离、重启恢复和端到端时延后再参评。 - -### 构建与部署的 runner 隔离 - -发布 workflow 分成两个顺序执行的 job，工作流级并发锁覆盖整个流程： - -1. **build**：完成配置／集群预检、离线检查、未选应用快照、所选镜像构建与推送。 - 只输出固定镜像 digest、Memoria 来源与快照 SHA-256；构建记录继续保存为原有 artifact。 -2. **deploy**：使用新的 runner，重新生成私有配置、读取凭据并核对集群及当前部署。 - 单项发布核对跨 job 快照摘要，以及执行 Pulumi 前的实时快照。变化时停止，重新发起运行。 - 然后执行 Go 检查，编译到 `deploy/pulumi/.bin/aml-pulumi`，在 CI checkout 内配置 Go - runtime 的 `binary` 选项，preview／up 直接运行该二进制。 - -Docker／Rust 构建存储与 Go／Pulumi 部署编译存储分别位于两个 runner。 -`deploy/pulumi/Pulumi.yaml` 在仓库中仍采用默认 Go runtime，本地 Pulumi 使用方式保持一致； -只有 CI checkout 被修改为使用预编译程序。 -[Pulumi Go 预编译程序说明](https://www.pulumi.com/docs/iac/languages-sdks/go/) - -磁盘预检分别要求适配器构建前至少 3 GiB、Memoria 源码构建前至少 12 GiB、 -部署程序编译前至少 6 GiB、执行 Pulumi 前至少 2 GiB 可用空间，同时检查 workspace -与 `RUNNER_TEMP`。不足时输出阶段和可用容量并停止；这些是启动阈值，不是构建峰值保证， -后续可按实际使用量调整。不要在同一个已耗尽磁盘的 runner 上重试编译。 - -kubeconfig、运行凭据、生成的私有 stack 配置和完整 Helm values 不进入 job outputs -或 artifact。两个 job 各自清理临时 kubeconfig、私有 stack 配置与本地快照； -部署 job 单独读取 `PULUMI_TOKEN`。冻结检查在 job 入口及真实部署前继续生效。 - -单个 **build** job 最长 90 分钟，**deploy** job 最长 60 分钟。 -选择 `image` 且仅更新 Memoria 时，流程跳过 Docker 构建环境和镜像构建，直接使用配置的 digest。 -参数填写、首次部署、单项更新、镜像命名及证书等待方式继续使用上述说明。 - -### ACR 推送格式 - -两个镜像的构建步骤均使用 `provenance: false` 和 `sbom: false`。当前 ACR 入口不接受 -BuildKit 默认 provenance 附件的 `application/vnd.oci.empty.v1+json`，会在 manifest 推送 -阶段拒绝请求。若出现 `unknown manifest class`，应使用已包含上述设置的最新 `main` -发起新的 Run workflow；重新运行旧记录仍会执行旧版本的 workflow。 - -镜像 digest、来源 SHA 和构建记录继续保留；这些记录用于追溯版本，不构成签名证明。 -[Docker 构建附件说明](https://docs.docker.com/build/metadata/attestations/) - -### 选择更新范围 - -`deployment_target` 控制本次更新的应用，默认 `both`。`operation=preview`／`deploy` 均支持。 - -| 选择 | 发布行为 | -|---|---| -| `both` | 更新 Memoria 和 memory_benchmarks 的 AML Add/Search 适配器；首次部署选择此项 | -| `memoria` | 按 `memoria_build_mode`／`memoria_ref` 构建或选择 Memoria 镜像，复用当前适配器镜像和应用配置 | -| `memory_benchmarks` | 构建并更新 AML 适配器，复用已部署 Memoria 的实际 digest、来源和应用配置；忽略 Memoria 构建参数 | - -单项更新需要已有完整的 `aml` Helm release 和两个 Deployment。流程从目标集群读取当前 -Helm values，核对实际镜像，保留未选应用的配置和共享 checksum；不会用仓库 Variable 中的 -旧镜像替代实际部署。构建结束、Pulumi 操作前再次核对现有配置，变化时停止并要求重新运行。 - -当前共享数据库连接和认证／embedding key 必须与已部署 Secret 一致。要轮换这些配置， -应选 `both`。chart 改动若会更新未选应用的 Deployment，也必须选 `both`。 -单项更新保留当前 Ingress、证书配置等共享 Helm values；共享资源配置更新使用 `both`。 -无需新增 Secrets。自动部署若启用仍默认 `both`，冻结规则对所有更新范围生效。 - -Memoria 更新采用 Recreate，更新期间适配器进程可继续运行，但其 Add/Search 上游会暂时 -不可用；比赛评测期间仍应冻结发布。这里的 `memory_benchmarks` 指运行中的 AML 适配器， -发布不会自动运行 benchmark 或官方评测。 - -离线检查流程是 **CI - Lint, Tests & Adapter Build**，不会部署应用。CI 使用固定版本 -`actionlint v1.7.7` 检查 workflow YAML 和 Actions 表达式。若部署流程仅显示文件路径、 -立即失败且没有 job，应先检查 workflow 文件语法；这种失败不会创建应用资源。 - -NGINX 路由设置 1800 秒读／发送超时和关闭上游自动重试，以支持同步 Add。 -整个链路的 SLB、控制器限制和 AML 契约还要核实；这不构成已支持所有 30 分钟请求的证明。 -不能将控制面 `mocloud-alb` 的设置直接复制到当前只有 `nginx` 的 unit 集群。 - -证书自动化复用 **cert-manager + 现有 ClusterIssuer**，TLS Secret 由 cert-manager -持续管理。CI/CD 声明应用自己的 Certificate，不保存证书私钥，也不部署第二套签发／ -续期任务。当前集群已有 cert-manager `v1.12.1`，三个组件均有可用副本，生产／staging -Issuer 均为 Ready；此 CD 不安装或升级共享控制器。该旧版本的维护属于集群基础设施职责。 - -当前生产 Issuer 的 DNS webhook 配置范围为 `cn-dev.matrixone.tech`；已选定并配置 -`aml.cn-dev.matrixone.tech`。2026-10-06 公共解析器 `223.5.5.5` 的 TCP 查询确认 -A 记录为 `47.97.230.53`、TTL 600 秒，与只读核查的 NGINX LoadBalancer IP 一致。 -应用 Ingress 已创建，`aml-tls` 证书已由该 Issuer 签发并 Ready。域名不属于该范围时， -需要基础设施维护者提供对应 Issuer，不能仅修改应用域名后假定签发成功。 -[cert-manager DNS-01](https://cert-manager.io/docs/configuration/acme/dns01/) - -DNS 解析区域为 `cn-dev.matrixone.tech`（已委派给 `ns1.alidns.com`／`ns2.alidns.com`）， -域名管理员已配置以下记录；后续修改须使用拥有该区域权限的账号： - -| 字段 | 值 | -|---|---| -| 主机记录 | `aml` | -| 类型 | `A` | -| 记录值 | `47.97.230.53`（部署时核对 unit NGINX LoadBalancer） | -| 线路 | 默认 | -| TTL | 600 秒 | - -cert-manager 自动管理证书验证 TXT 和续期，不自动创建业务 A 记录；本应用流程也未 -安装 ExternalDNS。这条 A 记录由域名管理员一次性配置，后续入口 IP 变化时维护。 -有正确区域权限时可以通过阿里云 CLI／API 添加，不要求只能在控制台操作。 -[阿里云添加记录 API](https://www.alibabacloud.com/help/en/dns/api-alidns-2015-01-09-adddomainrecord) +| 前置资源／配置 | 模板要求 | +| --- | --- | +| 数据库与 embedding | Memoria Pod 可访问，模型和维度一致 | +| 运行 Secret | 默认 `aml-runtime`，包含 `DATABASE_URL`、`MASTER_KEY`、`EMBEDDING_API_KEY`、`ADAPTER_API_KEY` | +| 镜像拉取 Secret | 默认 `aml-registry`，适用于所选镜像仓库 | +| journal PVC | 默认 `aml-adapter-state`，可写且能供 UID/GID 1000 使用 | +| 镜像与架构 | 适配器及 Memoria 的 repository/digest；当前模板选择 `amd64` 节点 | +| 入口（可选） | Ingress controller、DNS 与 TLS；开启证书模板时还需对应 ClusterIssuer | -Let’s Encrypt 当前默认有效期为 90 天，覆盖一个月比赛；以实际 Certificate 的 `notAfter` -为准，续期持续由 cert-manager 管理。 -[Let’s Encrypt 有效期说明](https://letsencrypt.org/docs/cert-lifetimes/) +维护者在 Git 忽略的 `var/` 中准备私有 values，填写两份镜像的真实 repository/digest、 +embedding、Secret、PVC、资源和入口配置。若改变 release 名称，也要同步核对 +`memoria.url`，避免继续引用默认服务名。运行 Secret 中的数据库账号需满足 +当前模板启用的 Memoria multi-database 模式所需权限。 -部署后如需本地联调，可转发适配器： +从仓库根目录可先执行离线模板检查： ```sh -kubectl --kubeconfig "$HOME/dev/unit-kubeconfig" -n aml-memory-benchmarks \ - port-forward service/aml 8000:80 +python3 deploy/scripts/render_chart.py ``` -`/health` 直接在事件循环检查存活；`/ready` 使用独立线程容量和 HTTP 连接检查 journal -可读及 Memoria `/health`，每个 worker 最多一个检查，并发探针直接返回 503，不排队。 -ready 不验证运行 master key、数据库授权、embedding 或 Add/Search 质量。 +该脚本使用合成值检查不同模板分支，不访问集群，也不能证明真实凭据或目标环境可用。 +完成配置后，由独立复现环境维护者按其发布流程安装 chart；本仓库的 QA benchmark +不会替其准备这些资源。现有共享环境仍通过对应 GitOps PR 发布。 -## 接入已部署的 Add/Search +## 复现记录 -客户端只需要公网地址和 **`AML_ADAPTER_API_KEY`**，无需 kubeconfig、数据库密码或 -`MEMORIA_MASTER_KEY`，也无需预注册 Memoria 用户。运维从受控的 `deploy/.runtime.env` -取得适配器 key 并提供给调用方；GitHub Secret 页面不能回读已保存的值。 -AML 平台配置 Add URL、Search URL 和该 key；你在本地联调也使用同样的接口。 +部署文档保留操作方法；每次运行还应单独保存以下非秘密元数据： -| 配置 | 值 | -|---|---| -| Add URL | `https://aml.cn-dev.matrixone.tech/add` | -| Search URL | `https://aml.cn-dev.matrixone.tech/search` | -| 认证 Header | `Authorization: Bearer ` | -| Content-Type | `application/json` | -| 交互式接口说明 | `https://aml.cn-dev.matrixone.tech/docs` | +| 项目 | 需要固定／记录的值 | +| --- | --- | +| 源码 | mb、Memoria 完整 commit SHA | +| 运行镜像 | 适配器、Memoria、MatrixOne 的 tag/digest 与架构 | +| 模型与功能 | embedding 模型／维度、相关模型版本、时间注释等开关 | +| 部署配置 | namespace／隔离规则、持久化、并发、排队、超时及入口限制 | +| 评测契约 | 数据版本／hash、范围、Top K、chunking、回答／Judge 的版本与预算 | +| 执行结果 | 开始结束时间、运行标识、成功／失败与评分覆盖率 | -### curl：写入后检索 +记录凭据的配置方式，不记录真实值。公开方法的固定仓库版本与部署步骤应可核对； +内部环境地址、具体运行日志和验收进展可以留在受控本地记录中。 -先设置环境变量。示例 key 是占位符，不是实际凭据；运行时替换为自己的 key。 -每次独立演示生成新用户，避免与其他测试数据混在一起。 +## 发布流程 -```sh -export AML_BASE_URL='https://aml.cn-dev.matrixone.tech' -export AML_ADAPTER_API_KEY='<实际适配器 key>' -export AML_DEMO_USER="aml-demo-$(python3 -c 'import uuid; print(uuid.uuid4().hex)')" - -curl --fail-with-body -sS "$AML_BASE_URL/health" -curl --fail-with-body -sS "$AML_BASE_URL/ready" - -curl --fail-with-body -sS --max-time 120 "$AML_BASE_URL/add" \ - -H "Authorization: Bearer $AML_ADAPTER_API_KEY" \ - -H 'Content-Type: application/json' \ - --data-binary @- <", - "session_id": "session-1" -} -``` +## 接入已部署的 Add/Search -Search 返回记忆证据，不生成最终答案。以下为结构示意；ID、内容格式、分数和时间取决于 -实际后端结果，`score` 和 `created_at` 为可选字段，无匹配时返回 `{"data": []}`。 +向环境维护者取得适配器地址和客户端访问密钥。使用 HTTPS，并在进程环境中设置凭据， +不要把凭据写进 URL、示例文件或日志。 -```json -{"data": [{"id": "", "content": "<包含 Orion server uses Rust 的记忆证据>"}]} -``` +| 接口 | 用途 | +| --- | --- | +| `POST /add` | 按 `user_id` 写入消息；同步完成后返回成功及原始请求标识 | +| `POST /search` | 在同一 `user_id` 内检索，返回记忆证据而非最终答案 | +| `GET /health` | 进程存活检查 | +| `GET /ready` | journal 可读性与上游健康检查 | -### Python：只用标准库 - -先设置上述 `AML_BASE_URL` 和 `AML_ADAPTER_API_KEY`，将下面保存为 `aml_demo.py`， -运行 `python3 aml_demo.py`。它发送一条 Add 和一条 Search，不启动本地服务或评测。 - -```python -import json -import os -import time -import uuid -from urllib.request import Request, urlopen - -base = os.getenv("AML_BASE_URL", "https://aml.cn-dev.matrixone.tech").rstrip("/") -api_key = os.environ["AML_ADAPTER_API_KEY"] -run_id = uuid.uuid4().hex -user_id = f"aml-demo:{run_id}:alice" - - -def post(path, payload): - request = Request( - base + path, - data=json.dumps(payload).encode("utf-8"), - headers={ - "Authorization": f"Bearer {api_key}", - "Content-Type": "application/json", - }, - method="POST", - ) - with urlopen(request, timeout=120) as response: - return json.load(response) - - -add_payload = { - "request_id": f"eval:{run_id}:conv-0:chunk-0", - "user_id": user_id, - "session_id": "session-1", - "messages": [{ - "role": "user", - "content": "Orion project uses Rust for the server.", - "timestamp": int(time.time() * 1000), - }], -} -print("Add:", json.dumps(post("/add", add_payload), ensure_ascii=False)) -print("Search:", json.dumps(post("/search", { - "user_id": user_id, - "query": "What language does the Orion server use?", - "top_k": 10, -}), ensure_ascii=False)) -``` +可执行的 curl 示例见[根目录快速开始](../README.md#try-the-deployed-api)。 +完整字段、重试、错误和 journal 迁移语义见 +[适配器说明](../agent_memory_leaderboard/README.md#retries-and-deployment-state)。 +重试写入应沿用原始请求 ID、用户和完整 payload，不清理 journal 来绕过未知写入状态。 + +## 评测与数据保留 -### 请求字段与使用规则 - -| 字段 | 要求／用途 | -|---|---| -| Add `request_id` | 必填非空字符串，整体视为不透明 ID；相同用户的不同写入使用不同 ID，原样重试保留 ID 和完整 payload | -| `user_id` | Add/Search 均必填非空字符串，决定记忆归属；同一用户跨会话检索仍用相同值 | -| Add `session_id` | 必填非空字符串，用于来源会话；Search 不需要它，不按会话限制检索 | -| Add `messages` | 必填非空数组，每条包含 `role` 和 `content` | -| message `role` | `user` 或 `assistant` | -| message `content`、Search `query` | 非空文本，或非空的 `[{"type":"text","text":"..."}]` 数组；当前不接受图片 | -| message `timestamp` | 可选，整数 Unix 毫秒，例如 `1704067200000`；不是秒或 ISO 字符串 | -| Search `top_k` | 必填正整数，返回数量不超过此值；当前后端最多检索 100 条 | -| Search `options` | 可选字符串数组；当前接受该字段，但不用于生成答案 | - -未知请求字段会被拒绝。相同 `user_id`／`request_id` 原样重试不会重复写入； -同一 ID 改 payload 返回 400。最小示例没有自动重试或清理：新增写入会留在该随机用户下。 -需要完整的验证和测试记忆逻辑停用时，使用已有 `src.smoke` 并配置内部 Memoria 访问； -它需要额外 master key，普通 Add/Search 客户端不需要。 -错误码和重试规则见[适配器说明](../agent_memory_leaderboard/README.md#retries-and-deployment-state)。 -示例客户端的 120 秒超时仅供小请求联调，不代表正式 AML 整批 Add 的总超时要求。 - -## 发布冻结与上线验收 - -进入正式评测前设置 `AML_FREEZE=true`，关闭自动部署，取消排队的 deploy，等待已运行 -发布完成，再核对运行镜像 digest。Repository Variable 在任务中按当次解析值使用， -两次检查不表示实时重新读取；更改变量不会取消已经运行的任务。冻结期间不手工执行 -`up`、重启应用或更新运行 Secret。preview 仍会发布镜像，不能当作完全只读操作。 - -CI/CD 已固定 Actions commit SHA，部署依赖安装强制校验 PyPI 发布 hash 并使用 wheel； -离线检查增加 Helm lint／template，覆盖内部入口＋单 worker 和公网 TLS＋两个 worker。 -健康探针的八个用例覆盖健康、上游非 2xx／连接失败／超时、journal 不可用， -以及 40 个 Search 占满业务线程池时探针仍可用、并发 ready 不排队。 - -正式参评前仍须验收： - -- 当前源码 digest 在 UID 1000／只读根文件系统下启动、schema 初始化和 Add/Search 已通过。 - 重启恢复仍未验证；后续来源版本也须核对日志中的 `Read-only file system`／`Permission denied`。只有证据明确需要 - 额外可写目录时才增加最小挂载；不预先取消只读限制。 -- 核对公网负载均衡实例的产品、listener 和真实超时。验证无中间响应的 5 分钟请求， - 继续验证超过 900 秒以及接近组别契约上限的请求，并验证超时后的恢复。记录准确耗时、 - HTTP 状态、客户端／Ingress 日志；短请求通过或流式心跳不能代替同步 Add 验收。 -- worker 默认保持 1。调整 `AML_ADAPTER_WORKERS` 后测量吞吐、P50／P95、错误率、 - 内存以及 journal／数据库／embedding 压力，再决定容量；正式评测期间冻结参数。 - -## 发布与评测分开 - -手动评测入口为 **Actions → AML benchmark**，支持 LoCoMo-Refined 和 LongMemEval-S， -默认一个完整历史。它复用现有 `AML_ADAPTER_API_KEY`，不使用部署凭据；与 CD 共用并发组， -防止 workflow 发布中断正在执行的 benchmark。Summary 和下载报告的操作步骤见 -[benchmark workflow 说明](../agent_memory_leaderboard/benchmarks/CI.md)。 - -CI/CD 完成服务发布；基准由明确的评测任务触发。owner 前缀、独立用户、专用库和 -独立 Memoria 隔离权限及数据，MatrixOne、embedding、NGINX 和节点容量仍可能共享。 -从一次小集任务开始测量吞吐、P50／P95、错误和模型额度；全局并发、速率与总量预算 -尚未在适配器实现。正式 Full 前的质量／恢复问题见 -[比赛设计](../agent_memory_leaderboard/docs/competition-plan.md)。 +手动 QA workflow 只运行 benchmark，不会部署后端或读取数据库管理员凭据。 +支持范围和成本边界见[benchmark workflow 说明](../agent_memory_leaderboard/benchmarks/CI.md)。 +本地回答与 Judge 不替代 AML 官方评测。原始评测正文、private cache、具体运行结果及 +验收进展不加入公开仓库；按各数据来源的使用条件与保留要求管理。 +Actions 附件过期不会自动清理 Memoria、journal 或历史快照，需要单独的清理安排。