mirror of
https://gitcode.com/JianFeeeee/HomeAgent.git
synced 2026-09-22 09:58:06 +00:00
bfdb395731
## 为什么 用户决定「本轮不覆盖 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）不进仓库，由导出脚本生成。
68 lines
2.5 KiB
Go
68 lines
2.5 KiB
Go
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
|
||
}
|