ST-Bionic-Memory-Ecology/docs/algorithms/vector-and-embedding.md

# 向量与 Embedding

向量是召回质量的下限。本文档说明 embedding 路径、向量空间身份、维度门禁——尤其是"换 embedding 模型导致维度变化"时如何保证不崩、不误用旧向量。

实现：`vector/embedding.js`、`vector/vector-index.js`、`vector/vector-space.js`、`vector/vector-gate.js`。

## Embedding 执行位置

> embedding 默认在客户端（浏览器）执行：`embeddingTransportMode` 默认 `"direct"`（直连第三方 embedding URL）。另一个值是 `"backend"`（走宿主后端代理）。

第三方自定义 URL 是一等公民：OpenAI 兼容 `/v1/embeddings`、one-api、new-api、litellm、vLLM、llama.cpp、Ollama 桥接等。Authority 不生成 embedding，只存/搜向量。

## 批量 Embedding

`embedBatch()`（`vector/embedding.js`）：

- 默认按 `embeddingBatchSize=10` 分块（可配，上限 100）
- 直连模式发送分块 OpenAI 兼容 `/embeddings` 请求，`input: string[]`，含 `encoding_format: "float"`
- 后端模式发送分块 `/api/vector/embed`，`texts: string[]`
- **分块失败回退**：整块失败时降级到逐条 `embedText`
- **部分结果回退**：返回的向量里有 null/缺失项时，只重试缺失项，不重试整块
- `AbortError` 继续向上传播（不吞）

HTTP 错误（400/401/403/429/502 等）会带状态码和响应体抛出，而不是吞成"返回空结果"的泛化错误——这样用户能看到真实的 provider 错误（比如余额不足 403）。

## 向量空间身份（vectorSpaceId）

换 embedding 模型会改变向量维度和语义空间。如果静默把新模型的查询向量拿去和旧模型的存储向量比，结果是垃圾。

> `vectorSpaceId` 由 provider 类型、embedding 模式、规范化 API URL、模型名、观测维度共同计算得出——**不是只看模型名**。API key 不参与计算。

实现见 `vector/vector-space.js` 的 `deriveVectorSpace(config, observedDim)`。

## 本地向量清单（manifest）

直连/自定义 URL 路径维护一个本地向量清单，记录 `vectorSpaceId`、`observedDim`、模型、状态。

> 向量搜索按 manifest 兼容性门控：维度或向量空间不匹配时，标记 stale/dirty 并返回空向量结果，让召回回退到图/词法召回——**绝不静默复用不兼容的旧向量**。

这条保证了用户换模型时看到的是"记忆没丢，搜索索引在重建"，而不是错误的召回结果或"数据丢失"的错觉。

## 维度门禁

`vector/vector-gate.js` 决定向量准备/修复前的动作：skip / repair / blocked / sync。

直连模型/源/集合变更时，不再把旧 `node.embedding` 当作干净可用。Authority 搜索在 BME apply/manifest 能力启用时也按 manifest 兼容性门控。

## 服务器端向量应用

启用 Authority `/bme/vector-apply` 时：

> BME 在 payload 里发送 `vectorSpaceId` 和 `observedDim`（顶层 + 每项元数据）。DOA 按批校验 vectorSpaceId/observedDim 一致性，拒绝混合维度，返回带类型的校验错误。失败/404/旧 DOA 时回退到旧 Authority Trivium 路径或本地。

## 连接测试

`testVectorConnection()` 测的是**真实批量 embedding 路径**（走 `embedBatch`），而不是单条短文本——因为"测试通过但实际 embedding 失败"的根因就是测试只测了单条短文本而运行时用的是批量长文本。

- 测试按表单选择的传输模式（direct/backend）测试，不被 Authority 自动主路径劫持
- 后端模式同时探测 `/api/vector/embed`（批量 embedding）和 `/api/vector/query`（向量存储健康）
- Authority 模式先用 embedding provider 生成批量向量，再检查 Trivium stat（避免暗示 Authority 生成 embedding）

## 后台向量同步合并

后台向量同步任务通过 `runtime/vector-sync-coalescer.js` 合并：

- 同 chat + 模型 scope 合并范围
- 活跃同步期间最多保留一个待处理任务
- 切换聊天时跳过陈旧任务
- 队列拒绝时回滚待处理状态

这避免了"每次编辑/reroll 都产生独立任务、串行 FIFO 队列堆积"的放大问题。

## 关键默认参数

| 参数 | 默认 | 含义 |
| --- | --- | --- |
| `embeddingTransportMode` | direct | embedding 传输模式（direct 直连 / backend 后端代理） |
| `embeddingBatchSize` | 10（上限 100） | 批量分块大小 |
| `encoding_format` | float | 直连 OpenAI 兼容请求 |