From b2eafdf8851c599f64cb8ff1caa733f6a61c86ce Mon Sep 17 00:00:00 2001 From: JianFeeeee Date: Fri, 11 Sep 2026 11:43:35 +0800 Subject: [PATCH] =?UTF-8?q?refactor(sdk):=20=E7=A7=BB=E9=99=A4=20MediaAtta?= =?UTF-8?q?chment.Description=EF=BC=8C=E5=AA=92=E4=BD=93=E4=B8=8D=E5=86=8D?= =?UTF-8?q?=E4=BB=A5=E6=96=87=E6=9C=AC=E6=8F=8F=E8=BF=B0=E5=8F=82=E4=B8=8E?= =?UTF-8?q?=E7=B4=A2=E5=BC=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 描述式索引是把图片将就成文本的机制，已在内核侧彻底拆除： - MediaAttachment 不再携带 Description：媒体只按自己的原生向量被 检索与召回，不生成、不检索、不持久化任何描述文本； - InsertWithMedia 的语义随之收敛为「媒体成为文档直接持有的一等块」， 文档向量融合这些块的原生向量，图片按图本身被召回； - 往返测试同步去掉描述字段，只断言 digest/MIME/name/data 不损坏。 注意：这是公开 SDK 的破坏性字段删除（有意为之，媒体描述链路整体废弃）， 不是加法式变更。 --- sdk/memory.go | 18 ++++++++++-------- sdk/stress_test.go | 11 +++++------ 2 files changed, 15 insertions(+), 14 deletions(-) diff --git a/sdk/memory.go b/sdk/memory.go index a90785f..35f626f 100644 --- a/sdk/memory.go +++ b/sdk/memory.go @@ -49,15 +49,17 @@ type TextMemoryAPI interface { // // 两个方向共用一个类型： // - 写入（InsertWithMedia）：给 Data + MIME 就是新内容；只给 Digest 则是引用已有内容。 -// - 读出（Query）：内核只填 Digest/MIME/Description，**不回 Data**—— +// - 读出（Query）：内核只填 Digest/MIME，**不回 Data**—— // 一次检索可能命中几十张图，把字节全塞回插件会把 ABI 消息撑爆。 // 需要字节时拿 Digest 单独取。 +// +// 刻意没有 Description 字段：媒体不作为文本被索引，也不带任何生成的描述。 +// 它只按自己的原生向量被检索与召回；附加文字请写在文档 / 三元组的文本里。 type MediaAttachment struct { - Digest string `json:"digest,omitempty"` - MIME string `json:"mime,omitempty"` - Data []byte `json:"data,omitempty"` - Name string `json:"name,omitempty"` - Description string `json:"description,omitempty"` + Digest string `json:"digest,omitempty"` + MIME string `json:"mime,omitempty"` + Data []byte `json:"data,omitempty"` + Name string `json:"name,omitempty"` } type TextEvent struct { @@ -74,8 +76,8 @@ type DocMemoryAPI interface { Insert(doc *Doc) error // InsertWithMedia 写入文档并关联媒体。attachments 里带 Data 的会落进 // 内容寻址存储（相同字节只存一份），只带 Digest 的直接引用已有内容。 - // 插件无需自己拼标记：内核会把 `[mime <短 digest>] <描述>` 补进 Content， - // 让向量检索和后续蒸馏都能看到这份媒体。 + // 媒体成为文档直接持有的一等记忆块：文档向量会融合它们的原生向量， + // 因此图片按自己的向量被召回，不依赖任何生成的描述文本。 InsertWithMedia(doc *Doc, attachments []MediaAttachment) error Remove(id string) Stats() map[string]interface{} diff --git a/sdk/stress_test.go b/sdk/stress_test.go index c088cdc..c79d574 100644 --- a/sdk/stress_test.go +++ b/sdk/stress_test.go @@ -463,11 +463,10 @@ func TestStress_MediaTypesJSONRoundTripAtScale(t *testing.T) { data[i] = byte(i * 7 % 256) } att := MediaAttachment{ - Digest: strings.Repeat("a", 64), - MIME: "image/png", - Data: data, - Name: "图片-名字 with space & 符号.png", - Description: "一张紫蓝红三色带图，含 emoji 🎨 与换行\n第二行", + Digest: strings.Repeat("a", 64), + MIME: "image/png", + Data: data, + Name: "图片-名字 with space & 符号.png", } b, err := json.Marshal(att) if err != nil { @@ -485,7 +484,7 @@ func TestStress_MediaTypesJSONRoundTripAtScale(t *testing.T) { t.Fatalf("size=%d 第 %d 字节损坏: %02x != %02x", n, i, back.Data[i], data[i]) } } - if back.Name != att.Name || back.Description != att.Description || back.MIME != att.MIME || back.Digest != att.Digest { + if back.Name != att.Name || back.MIME != att.MIME || back.Digest != att.Digest { t.Fatalf("size=%d 元数据往返不一致: %+v", n, back) } }