jianf/HomeAgent
1
0
Fork 0
mirror of https://gitcode.com/JianFeeeee/HomeAgent.git synced 2026-09-21 09:28:14 +00:00
Code Issues Packages Projects Releases Wiki Activity
398 Commits 6 Branches 27 Tags
fe883d5362d9ae7d775fba31cd2d8aa4bd0a5bac
Commit Graph

4 Commits

Author SHA1 Message Date
JianFeeeee
d4c5e808c7 feat(packaging): 模型与 ONNX Runtime 随 server/full 包发布 
模型与运行库是发行版能力的一部分，不做成「装完再自己下载」：

- package-linux.sh：新增 stage_multimodal_assets()，打 server/full 前校验产物
  SHA256SUMS、逐文件非空、运行库架构与目标一致，缺一即失败；client 包不含。
  顺带修掉三个让打包在最后一步才炸的既有缺陷：
  · 版本串直接取 git describe（v1.0.0-68-gxxx-dirty）不是合法包版本——deb 要求
    数字开头、rpm 不允许 '-'。以前只有显式 VERSION=1.0.3 才打得出来；默认路径
    从来没通过过。现在归一化，非数字开头时显式报错。
  · 三处 mktemp -d 落在 /tmp（本机 9.8GB tmpfs），而 staging 要复制 719MB 模型，
    中途 ENOSPC；报错文本指向某个 .onnx 文件，看着像资产坏了。改为落在与构建产物
    同盘的 build/.stage-tmp。
  · 开工前删掉旧的 SHA256SUMS：失败时脚本直接退出、不重算，留着像在为残缺产物背书。
- setup.sh：把包内 /usr/lib/homeagent/models/chinese-clip-vit-b16-onnx 软链到
  <dataDir>/models/…（不复制 754MB、保持 dataDir 可迁移、已有自定义目录不覆盖）
- homeagent.service：ExecStart 改 /usr/bin/homed（deb 装在那里，此前写 /usr/local/bin，
  装了也不会被 unit 用上）、加 ONNXRUNTIME_DIR 与 StateDirectory、MemoryMax 2G→8G
  （实测常驻约 4.5GB，2G 会在首次全量建索引时被 cgroup OOM）
- control-{full,server}：补 libstdc++6 / libgcc-s1（libonnxruntime.so 需要）
- providers/{chineseclip,qwen3vl}：findOnnxLib 支持 ONNXRUNTIME_DIR / ONNX_ML_DIR
  与包内 /usr/lib/homeagent/onnxruntime，随包的运行库才真的会被用上
- postinst：修掉两个让「装完即用」失效的点——它检查 /lib/systemd/system/ 下的 unit
  而 deb 装到 /etc/systemd/system/，于是 daemon-reload/enable **从未执行**；以及
  setup.sh 的失败被 `|| true` 吞掉（正是 initconfig 静默缺陷被藏住的原因）。现在
  三个候选路径都查、失败可见并给出补救命令、首装 start / 升级 restart。
- docs/zh/multimodal-space.md：新增「随包分发」一节，并修正播种判据的说明

验收（从真实 deb 走一遍，不是读脚本）：
- 包内 initconfig 已是动态链接，凭据真的写进 config.db
- 解包 → 按 postinst 顺序跑 setup.sh → 包内 homed 冷启动：
  multimodal space active: provider=chineseclip dim=512 fp=cd2a495cf990
  modalities=[text image]
- 全新安装的默认值确实被播种（core.plugin.dir / provider / model_dir 都在）
- 真实对话拿到回复（3.4s，回复中含唯一标记）
- 包内模型 SHA256SUMS 5/5 通过；包内 ORT 与源同 sha256；server 包 722MB
  （旧版 17MB，差额即模型与运行库）；full 包同样含全部资产；client 包不含
 2026-09-12 08:10:44 +08:00
JianFeeeee
bfdb395731 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）不进仓库，由导出脚本生成。
 2026-09-11 23:58:53 +08:00
JianFeeeee
d1959cbe80 feat(core): 注入行为的记忆/裁剪标志位落地 + jieba 词库内嵌 + Windows 改走 WSL 
配套 SDK 提交：homeagent-sdk ba49dfd（公开 API 纯追加，无签名变更）。
本仓第三方的库镜像同步至该版本，以保证全新 clone 能编译。

## 1. 注入标志位（内核侧）

- 7 条注入路径（排队/中断/同步 × 纯文本/带媒体 + 旧 NoMem 变体）解析并转发
  no_memory / context_policy / cleaner_name；策略在入口**校验**，
  非法值报错而不是静默降级成 none（降级会让调用方以为自己声明的裁剪在生效）。
- 新增 validateContextPolicy（与 tool.register 同一套规则）与 pubSdkInjectOpts。
- input.register 不再手写字段白名单重建 ChannelDef，改为整体传递 + 补 ContextPolicy。
- io 层：applyInjectOpts 把标志位写进事件 payload，仅非零时写
  （零值与旧 payload 逐字节一致，事件订阅方与旧内核都不受影响）。
- ioAdapter / procCore / internal-sdk 别名补齐六个 *Opts 实现。

## 2. 修掉「输入无条件裁剪」这个真缺陷

eventloop 此前对**每条非中断输入**都调 `context.Prune(...)`：破坏性（低相关事件被
归档移出上下文）且无法从调用点看出是谁触发的。改为 pruneOnInput/pruneDeclared：

  优先级：注入点声明（payload.context_policy）> 通道声明（ChannelDef.ContextPolicy）
          > 默认**不裁剪**

查询向量仍取清洗后的内容；新增 cleanInputFor 解析清洗文本，优先级为
注入点声明的 cleaner（cleaner_name）> 按 source 查到的通道 cleaner > 原文，
名字查不到时**记日志再回退**（注入是 fire-and-forget，插件看不到错误，
至少要在内核日志留下「你声明的清洗没生效」的痕迹）。

## 3. jieba 词库内嵌（修「猜 GOMODCACHE → 静默失效」）

原 jiebaDictDir() 去猜 GOMODCACHE/GOPATH/~/go/pkg/mod，部署机上通常没有 Go 模块
缓存 → GetJieba() 返回 nil → 分词/关键词提取/NLP 依存解析（进而 doc→graph 三元组
抽取）/静态词向量 tokenizer **一律静默返回空列表**，只有一行日志。本机看起来正常
只因开发机与生产机重合、恰好有那份缓存。

现在词库随二进制分发：internal/memory/jiebadict/ 5 文件约 11.6MB + go:embed，
按**内容哈希**命名缓存目录落盘（词库升级不复用旧文件），已齐全则跳过写入。
模块缓存降为兜底。homed 体积 32MB。

顺带确认（并有测试佐证）：gojieba 的 Tag() 不需要 pos_dict/ 目录——
cppjieba 的 PosTagger 从主词典每行的词性列取 tag。

## 4. homed 放弃 Windows 原生，改走 WSL2

插件体系依赖「继承的 fd」+「统一共享内存区的段内偏移解引用」，Windows 既无 fd
继承语义，其句柄模型也无法表达后者；强行适配等于再维护一套平台专属 ABI
（C ABI 时代三套 ABI 并存曾导致改写型插件在某平台静默失效）。

- cmd/homed/platform_{windows,other}.go：原生 Windows 启动即拒绝并打印 WSL2 指引。
- internal/plugin/proc/shmalloc_windows.go：allocShm 直接返回「请用 WSL2」，
  **不返回半可用的段**（与 shmalloc_other.go 同风格：未支持平台显式报错）；
  procEnvForShm 返回 nil。顺手修掉两处长期编译错误
  （cryptorand→rand、h.evData→h.unified.evtData），使 GOOS=windows 至少能编译。
  注：homed 本就编不出 Windows——internal/memory 依赖 cgo-only 的 gojieba。
- deploy/packaging/installer.nsi：不再安装 homed.exe/initconfig.exe，改为携带
  **linux payload** 并调用新的 install-via-wsl.ps1；退出码 20/21 表示
  「需先装 WSL/发行版」，走指引而非报错。
- deploy/packaging/windows/install-via-wsl.ps1（新）：检测 WSL → 引导安装 →
  确保 WSL2 → 送包进发行版 → 在 WSL 内按 Linux 方式安装。**复用 Linux 包与
  linux/setup.sh**，不另写一套安装逻辑；落点与 deb 布局统一
  （/usr/bin/homed + /usr/lib/homeagent/setup.sh）。
- deploy/packaging/linux/setup.sh：API Key 允许 HOMEAGENT_API_KEY 覆盖
  （否则安装器界面显示一份、config.db 里另一份 → 登录不上）。
- deploy/packaging/build.sh：windows 目标只构建 waiter + gui，并新增
  stage_linux_payload 把 Linux 包暂存给安装器；homed/initconfig 在 windows
  目标下明确拒绝。

## 5. 插件调用点统一写明意图

- webui 的 OpenAI 兼容端点（固定提示词模板）→ InjectTextSyncNoMemory。
- agentcli 的 5 处纯状态通知（已启动/超时/执行结束/进程退出/读取结束）→ NoMemory；
  **带输出**的 2 处（定时反馈、有新输出）刻意保留记忆并注明理由。
- timer 的定时提醒 → NoMemory（中断本来也隐含 NoMemory，这里是写明意图）。

## 6. 版本

meta.Version 仍为 1.2.0（main 是下一个未发布中版本）；
SDKCompatibleVersion 1.1.0 → **1.2.0**（本内核已实现 SDK 1.2.0 全部新增方法）。

## 测试

- core：默认不裁剪（无声明/none/空）、通道 opt-in、注入点双向覆盖通道、
  nil context/io 安全、cleaner 优先级与未知名回退。
- io：零值 opts 与历史 payload 逐键相同；text/中断/媒体三类注入标志位都落到
  payload；旧方法仍生效。
- proc：validateContextPolicy 只接受 ""/none/prune，报错含位置与实际值；
  **跨进程** e2e——testdata 插件经 io.injectText 送出三个标志位，断言它们穿过 RPC
  到达内核。
- memory：模块缓存不可见时内嵌词库仍可用（分词与 POS 内容词均非空）、
  落盘幂等、内容哈希稳定。

验证：go build ./... / go vet ./... / go vet -tags onnxruntime ./...
      go test -short ./internal/memory/... ./internal/nlp/... ./internal/plugin/...
      ./internal/agent/{core,io}/... ./pkg/...
 2026-09-11 20:31:50 +08:00
JianFeeeee
a37bc7333e refactor(memory): 核心不再适配具体模型——公共 embedding provider SPI + 注册表 
问题：cmd/homed 里 `case "onnx": qwen.New(modelDir)` 把模型适配写进了核心，
`type=onnx` 名义上是格式、实际写死了一个模型家族；2117 行 Qwen 专属代码
（BPE、chat template、M-RoPE、Vision_gN 命名）住在内核树里，还带着一对
`//go:build onnxruntime` 的 stub。加任何新模型都要改内核。

现在核心只认一个模型无关的公共契约（pkg/embedding）：
- 输入是不透明的 Data+MIME，解码/预处理/时序分组全归 provider
- 能力是数据（Info.Modalities），不是接口方法——新增模态无需改核心接口
- 不支持的模态返回 embedding.ErrUnsupportedModality（可 errors.Is 识别）
- 按名字注册，重复注册 panic；Options 是 provider 私有命名空间，核心不解释

改动：
- 新增 pkg/embedding：Modality/Purpose/Input/Info/Provider/Config + 注册表
  （Open 校验 Info，ValidateVector 在入库前拦下维度错与非有限值）
- providers/qwen3vl：Qwen 实现整体移出内核（git mv），实现公共 SPI 并自注册
- internal/memory/vector：新增 ProviderAdapter（公共 SPI → 内部小接口）；
  ErrModalityUnsupported 改为公共哨兵别名；删除 VideoEmbedder 可选接口
  （那正是「核心为每个新模态长方法」的坏味道）
- http embedder 也变成普通 provider（注册名 http）
- cmd/homed：删除 qwen import 与 onnx/http 分支，改为按 provider 名打开 +
  透传 options.*；provider 打开失败只警告并禁用多模态检索，不影响启动
- config：multimodal_space.type/onnx./http.* → provider + options.*
- 删除 internal/memory/qwen（整体搬迁）

测试：
- pkg/embedding：注册表隔离/未知名字/非法 Info 自动关闭/ValidateVector
- vector：适配器原样透传字节与 MIME、维度错被拦、Close 幂等且停止使用、
  两个哨兵 errors.Is 互通
- providers/qwen3vl：新增公共 SPI 全链路集成测试（Open→Info→Embed→
  未知模态哨兵），并明确断言 Info 不声明 video

已知未完成（不得当作已验证）：
- 视频冻结回归 TestEmbedderVideoMatchesONNXReference **显式跳过**：Go 侧
  video 模板缺少 processor 按时间组插入的字面时间戳文本
  （<0.0 seconds>/<1.0 seconds>），同一输入 Python seq=1190(1152+38)、
  Go 只有 22 个文本 token。时间戳也占 M-RoPE 位置，故现有 M-RoPE 自洽断言
  通过不能证明与官方实现一致。修复属 provider 内部工作。
- 视觉侧三档已导出并逐档校验通过（cos 1.000000119/1.000000119/1.000000000）

验证：go build ./... ；go vet -tags onnxruntime ./... ；
go test -short ./internal/memory/... ./internal/agent/core/... ./internal/sdk/... ./pkg/...
；onnxruntime 下 providers/qwen3vl 全绿（视频为显式 skip）
 2026-09-11 18:26:19 +08:00