diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index 3cb58b5..da99b8a 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -136,6 +136,18 @@ jobs: PGPASSWORD="$PG_PASSWORD" psql -h localhost -U memory_user -d memory_system \ -v ON_ERROR_STOP=1 -f schema.sql + # ⚠️ 必须在「装并启动 Ollama」**之前** —— 否则 ollama pull 看不到已恢复的目录, + # 会白下一次 1.2 GB(缓存也就永远写不进"命中") + - name: 缓存 bge-m3 权重(~1.2 GB) + uses: actions/cache@v4 + with: + path: ~/.ollama/models + # ⛔ 刻意**不设 restore-keys**:前缀匹配会在未精确命中时退而取"最接近的一条", + # 那意味着可能静默用上旧权重且不报错。宁可未命中多下一次。 + # ⛔ 换模型 / 升级权重版本时,**必须把末尾的 v1 递增** —— 否则 CI 会一直用旧权重。 + # 裁决与理由见 docs/decisions决策/DEC-009-CI怎样缓存embedding模型-20260921.md + key: ollama-models-${{ runner.os }}-bge-m3-v1 + - name: 装并启动 Ollama,拉 bge-m3 run: | curl -fsSL https://ollama.com/install.sh | sh diff --git a/CHANGELOG.md b/CHANGELOG.md index 6329c0f..3434abb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,18 @@ > 本轮 4 个 PR 已合并(#4 #5 #6 #7);详见各小节与 `docs/decisions决策/DEC-004~008`。 +### 操作(Ops)· CI 缓存 embedding 模型(1.2 GB) + +- `test-embedding` job 每次都要现下 1.2 GB `bge-m3` 权重(实测 1m28s–2m36s,下载占大头) + ⇒ 加 `actions/cache` 缓存 `~/.ollama/models` +- ⛔ **刻意不设 `restore-keys`**:前缀匹配会在未精确命中时退而取"最接近的一条", + 那意味着**可能静默用上旧权重且不报错** ⇒ 宁可未命中多下一次(与 DEC-003/005 同族判据) +- key = `ollama-models-${{ runner.os }}-bge-m3-v1`;⛔ **换模型/升级权重必须手动递增 `v1`** +- 位置**必须在「装并启动 Ollama」之前**(否则 `ollama pull` 看不到已恢复的目录,永远命中不了) +- ✅ 本地核实:`~/.ollama/models` 与 `ollama serve` 实际使用的目录一致(容器内实证 `$HOME/.ollama/models`) +- ⚠️ **加缓存后的第一次运行仍要完整下一次**(缓存尚不存在),该次运行结束才写入缓存 +- 裁决与边界见 **`DEC-009`** + ### 操作(Ops)· 推送通道与仓库卫生 - **`origin` 改走 SSH-over-443**(`ssh://git@ssh.github.com:443/...`)—— diff --git "a/docs/decisions\345\206\263\347\255\226/DEC-009-CI\346\200\216\346\240\267\347\274\223\345\255\230embedding\346\250\241\345\236\213-20260921.md" "b/docs/decisions\345\206\263\347\255\226/DEC-009-CI\346\200\216\346\240\267\347\274\223\345\255\230embedding\346\250\241\345\236\213-20260921.md" new file mode 100644 index 0000000..d61f85b --- /dev/null +++ "b/docs/decisions\345\206\263\347\255\226/DEC-009-CI\346\200\216\346\240\267\347\274\223\345\255\230embedding\346\250\241\345\236\213-20260921.md" @@ -0,0 +1,74 @@ +# DEC-009 · CI 里怎么缓存 `bge-m3`(1.2 GB) + +| 项 | 值 | +|---|---| +| **日期** | 2026-09-21 | +| **状态** | ✅ 已裁决:用 `actions/cache` 缓存 `~/.ollama/models`,**且不设 `restore-keys`** | +| **触发** | `test-embedding` job 每次都要现下 1.2 GB 模型(实测耗时 1m28s–2m36s,其中下载占大头) | +| **相关** | `.github/workflows/tests.yml` · `DEC-002`(CI 的 embedding 边界)· `DEC-008`(推送通道) | + +--- + +## 一 · 现状:CI 里哪些东西是现下的 + +| 东西 | 机制 | 是否可缓存 | +|---|---|---| +| 代码 | `actions/checkout` | — | +| Python 3.11 + pip 包 | `actions/setup-python`(已开 `cache: pip`) | ✅ **已经在缓存**(本仓实测 2 条 / 各 65 MB) | +| PG / Redis 镜像 | `services:` 容器(Docker Hub) | 理论可,但复杂、收益小 | +| **Ollama 安装包** | workflow 里的 `curl … install.sh \| sh` | 收益小(行为不易稳定命中) | +| **`bge-m3` 权重 1.2 GB** | `ollama pull bge-m3` | ✅ **本 DEC 针对这条** | + +## 二 · 备选方案 + +| 方案 | 优 | 劣 | +|---|---|---| +| A. 什么都不做 | 零改动 | 每次白下 1.2 GB(时间 + 流量) | +| **B. `actions/cache` 缓存 `~/.ollama/models`,key 绑模型名+版本标记,且不设 `restore-keys`** ✅**选定** | 第一方 action(供应链面不变,见下);命中即省掉下载 | 首次仍要下一次;key 需人工维护 | +| C. 换第三方 marketplace 的 ollama action | 也许更"省事" | ⛔ **多一个第三方供应链面** —— 而这个 job 拿的是**真代码 + 真数据库**,不值得 | +| D. 把模型打进自建镜像(GHCR) | 命中稳定 | 复杂度高(要维护镜像构建与推送),本仓规模不值 | + +## 三 · ⚠️ 关键设计:**不设 `restore-keys`** + +`actions/cache` 若配了 `restore-keys`(前缀匹配),缓存未精确命中时会**退而取最接近的一条**。 +对本用例,那意味着: + +> **可能用上一份"旧的、甚至不是你以为的那个模型"的权重,而且没有任何报错。** + +⇒ **这是一个会静默出错的失效模式**,与本案的其它判据同族(`DEC-003`「别让没有生产者的量参与判定」、 +`DEC-005`「别把当次测量当架构事实」):**宁可未命中多下一次,也不要静默用错东西。** + +**key 设计**: + +```yaml +key: ollama-models-${{ runner.os }}-bge-m3-v1 +``` + +- 含 `runner.os`:换 OS 镜像则不命中(合理,二进制与缓存布局都可能不同) +- 末段 **`bge-m3-v1`** 是**人工版本标记**,不是自动探测 +- ⛔ **换模型、或升级量化/权重版本时,必须手动把 `v1` 递增** —— 否则 CI 会一直用旧权重且不报错 +- 只在 `test-embedding` job 里加(`test` job 不需要 Ollama) + +## 四 · 已知代价与边界(如实记录) + +1. **加缓存后的第一次运行仍要完整下一次**(缓存还不存在);那次运行结束时才写入缓存。 +2. **上游若重新发布 `bge-m3` 这个 tag**,缓存不会自动感知 —— 仍用旧权重,直到人工递增版本标记。 + 这是"用确定性换新鲜度"的有意取舍(与 A 的"每次都可能变"相反);对本仓的用途(跑回归)更合适。 +3. **缓存的可见性**:GitHub 的规则是**同分支或默认分支**创建的缓存可被复用; + 本仓已能观察到该行为(`setup-python` 的两条 pip 缓存 key 完全相同、分属不同分支)。 +4. **7 天未访问被清理 / 仓级总量上限**:属 GitHub 的策略(文档口径 7 天 / 10 GB)。 + ⚠️ **本次未能核实文档**(`docs.github.com` 被网络挡住);**已实测的是**:本仓 2 条缓存 / 125 MB。 + +## 五 · 验收判据 + +- [ ] workflow YAML 可解析 +- [ ] 缓存步骤位置在「装并启动 Ollama」**之前**(否则 `ollama pull` 看不到已恢复的目录) +- [ ] `path: ~/.ollama/models` 与 `ollama serve` 实际使用的目录一致(安装脚本用 `$HOME/.ollama`) +- [ ] 首次运行:日志出现缓存 **miss** ⇒ 下载 ⇒ 结束时 **saved** +- [ ] 第二次运行:日志出现缓存 **hit** ⇒ 无 1.2 GB 下载 ⇒ 用 `gh api …/actions/caches` 核到该条目 + +## 六 · 反悔成本 + +低。删掉那个 `uses: actions/cache` 步骤即可回到 A; +`gh api -X DELETE repos/…/actions/caches/` 可单独清某条缓存。 +若将来要做 GHCR 镜像(方案 D),另开 DEC。