feat(memory): 新增 chineseclip provider —— text+image 的小体积可商用向量空间

## 为什么

用户决定「本轮不覆盖 video,先支持 text+image」。这一刀正好解锁了此前
「小 + 可商用 + 覆盖视频」三者不可兼得的僵局:不要求视频后,唯一同时满足
**小、可商用、中文原生** 的选项是 Chinese-CLIP ViT-B/16。

实测对比(同机、真实跑出来的数字):

| | Chinese-CLIP | jina-v5-omni-nano | Qwen3-VL-Emb-2B |
|---|---|---|---|
| 参数量 | 188M | 1.04B | 2B |
| 产物 / 常驻内存 | 754MB / **1.15GB** | ~2GB / 2.23GB | 8GB / 9.4GB |
| 维度 | 512 | 768 | 2048 |
| 许可 | **Apache-2.0** | CC BY-NC(不可商用) | Apache-2.0 |
| 视频 | 无 | 有 | 有 |

本机可用内存只有 5.3GB,Qwen 的 9.4GB 无法进程内使用;而 ORT format + mmap
那条路被证实当前不通(转换器对三段图段错误;走通还需同时升 ORT 运行时与
Go 绑定,v1.36 要求 API 29 而本机只有 28)。1.15GB 则可以直接进程内跑。

**代价已写进包注释与文档**:CLIP 是双塔对比学习,text↔image 是强项,但纯文本
语义明显弱于 MLLM 型嵌入器;文本检索仍由既有词向量/TF-IDF 路径兜底。
需要更强文本语义或视频时切回 qwen3vl。

## 内容

- `providers/chineseclip/`:按公共 SPI 实现的 provider(注册名 `chineseclip`),
  含 BERT WordPiece 分词器、图像预处理、ONNX 双塔推理、无标签 stub。
- `scripts/export_chineseclip_onnx.py`:从官方权重导出规范产物 + 冻结参考,
  自带逐用例 PyTorch 对比与覆盖度断言(计划集合≠执行集合即非零退出)。
- `cmd/homed/main.go`:空白导入两个 provider,由配置选其一。
- `go.mod`:`golang.org/x/text` 由间接依赖转为直接依赖(删音标需要 NFD)。

## 实现要点

- **分词器逐 token 对齐官方**。第一版探针自己拼 BertTokenizer(只给 vocab.txt、
  没删音标、中文没逐字切),中文被整体切成 [UNK],三个不同句子产出几乎相同的
  向量(余弦 0.98)——差点把「模型坏了」当成结论。官方配置是 do_lower_case=true
  + 删音标生效 + 中文逐字切分;`TestTokenizerMatchesOfficialReference` 钉住
  逐 token 一致。
- **图像缩放自写 bicubic**(复刻 PIL 的 precompute_coeffs + a=-0.5 核),不引
  golang.org/x/image:它未进本机模块缓存,且最新版要求把整个工具链升到 Go 1.26,
  为一个缩放函数动工具链不划算。
- **归一化在 provider 侧**(两个塔的图里都没归一化),检索按余弦。
- **指纹覆盖全部影响语义的产物**:两个 ONNX 图 + vocab.txt + embed_config.json,
  读不到就写 MISSING(跳过等于对缺件不敏感)。
- 会话 Run 用 runMu 串行化(ORT 会话不保证并发安全),创建/销毁用 mu。

## 模态范围

只声明 `text` 与 `image`;`audio`/`video` 明确返回 `ErrUnsupportedModality`,
绝不用别的模型向量冒充(这是「音频明确 unsupported」纪律的落地)。

## 验证(实测)

导出侧:10 个用例(5 文本 + 5 图像)ONNX vs 官方 PyTorch 全部
`cos = 1.000000000`,覆盖度断言 10/10 通过。

Go 侧(`CHINESECLIP_MODEL_DIR=... go test -tags onnxruntime ./providers/chineseclip/ -v`):
11/11 通过,其中
- 文本 5 用例 `cos = 1.000000000000`(逐位一致)
- 图像 4 纯色用例 `cos = 1.000000`(与官方预处理在 6 位小数内一致)
- 跨模态判别:红图对「红色」文本高于「蓝色」文本
- 模态拒绝 / 空输入 / 指纹稳定 / 产物缺失报错

顺带修掉测试自身的一个假通过:参考向量是**未归一化**的原始输出(模长 10~36),
原先「点积当余弦 + 单侧下界」会让 13.6 也判过,已改为真余弦 + 双侧容差。

构建矩阵:`go build/vet ./...` 与 `-tags onnxruntime` 两种都过;
`providers/... pkg/... internal/config/... internal/memory/vector/...` 回归通过
(qwen3vl 的 TestVideoModelInputMRope 需要 QWEN_ONNX_MODEL_DIR 指向含视频档的
v3 目录,缺该环境变量时用的是只有文本+图像的目录,与本改动无关)。

## 未做(明确记录)

- 发行版默认 provider 与构建标签变更:留下一提交(涉及打包与模型分发策略)。
- 模型产物(754MB)不进仓库,由导出脚本生成。
This commit is contained in:
JianFeeeee
2026-09-11 23:58:53 +08:00
parent d1959cbe80
commit bfdb395731
11 changed files with 1757 additions and 4 deletions

View File

@ -0,0 +1,67 @@
package chineseclip
import (
"encoding/json"
"fmt"
"os"
"path/filepath"
)
// embedConfig 是产物目录里 embed_config.json 的映射:provider 的全部模型假设
// 都来自这个文件,不在代码里散落魔数。
type embedConfig struct {
Arch string `json:"arch"`
Dimension int `json:"dim"`
TextONNX string `json:"text_onnx"`
VisionONNX string `json:"vision_onnx"`
MaxLength int `json:"max_length"`
ImageSize int `json:"image_size"`
ImageMean []float64 `json:"image_mean"`
ImageStd []float64 `json:"image_std"`
Normalize bool `json:"normalize_vector"`
Modalities []string `json:"modalities"`
Unsupported []string `json:"unsupported_modalities"`
}
// loadConfig 读取并校验产物配置。任何不匹配都必须**明确报错**:
// 静默沿用默认值会在换错模型时产出「看起来正常、语义错误」的向量,
// 那类错误会污染整个图记忆且难以追查。
func loadConfig(dir string) (embedConfig, error) {
path := filepath.Join(dir, "embed_config.json")
data, err := os.ReadFile(path)
if err != nil {
return embedConfig{}, fmt.Errorf("chineseclip: 读取 %s: %w", path, err)
}
var cfg embedConfig
if err := json.Unmarshal(data, &cfg); err != nil {
return embedConfig{}, fmt.Errorf("chineseclip: 解析 %s: %w", path, err)
}
if cfg.Dimension != 512 {
return embedConfig{}, fmt.Errorf("chineseclip: 维度不匹配 dim=%d(期望 512)", cfg.Dimension)
}
if cfg.MaxLength <= 0 || cfg.MaxLength > 512 {
return embedConfig{}, fmt.Errorf("chineseclip: max_length 非法: %d", cfg.MaxLength)
}
if cfg.ImageSize != 224 {
return embedConfig{}, fmt.Errorf("chineseclip: image_size 不匹配 %d(期望 224)", cfg.ImageSize)
}
if len(cfg.ImageMean) != 3 || len(cfg.ImageStd) != 3 {
return embedConfig{}, fmt.Errorf("chineseclip: image_mean/std 必须各 3 个分量,得到 %d/%d",
len(cfg.ImageMean), len(cfg.ImageStd))
}
for i := range cfg.ImageStd {
if cfg.ImageStd[i] == 0 {
return embedConfig{}, fmt.Errorf("chineseclip: image_std[%d] 为 0", i)
}
}
if cfg.TextONNX == "" || cfg.VisionONNX == "" {
return embedConfig{}, fmt.Errorf("chineseclip: 未声明 onnx 文件名(text=%q vision=%q)",
cfg.TextONNX, cfg.VisionONNX)
}
for _, name := range []string{cfg.TextONNX, cfg.VisionONNX, "vocab.txt"} {
if _, err := os.Stat(filepath.Join(dir, name)); err != nil {
return embedConfig{}, fmt.Errorf("chineseclip: 产物缺少 %s: %w", name, err)
}
}
return cfg, nil
}