Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions .github/workflows/tests.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
12 changes: 12 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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/...`)——
Expand Down
Original file line number Diff line number Diff line change
@@ -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/<id>` 可单独清某条缓存。
若将来要做 GHCR 镜像(方案 D),另开 DEC。
Loading