端侧 RAG 实战用 embeddinggemma-2 GGUF 给离线 AI Agent 装上记忆【免费下载链接】embeddinggemma-2-GGUF项目地址: https://ai.gitcode.com/hf_mirrors/unsloth/embeddinggemma-2-GGUF大模型天生健忘每次对话结束上下文即被清空。要让 Agent 记住私有文档、历史记录或用户偏好业界标准答案是检索增强生成RAG——把知识先向量化、再按语义召回最后拼进提示词。但云上 RAG 意味着数据出境、按 token 计费、以及每一次检索都依赖网络往返对隐私敏感、网络受限或追求低延迟的场景这三点都是硬伤。2026 年 10 月 6 日Google DeepMind 正式发布 EmbeddingGemma 2——一个把文本、代码、图像、视频、音频统一映射到同一 768 维向量空间的多模态嵌入模型740M 参数、Apache 2.0 协议量产后在 Pixel 11 Pro 上纯文本权重仅占约 191MB 活跃内存。与此同时Unsloth 同步发布了本仓库的 GGUF 量化版本让这条完全离线的 RAG 流水线可以在普通 CPU 笔记本上直接跑起来。社区也迅速跟进围绕 Ollama/Docker 部署的教程密集出现掘金上已有人发布端侧 RAG 实战指南其核心目标正是赋予离线 AI 代理记忆。本文将以本仓库的 GGUF 文件为线索从架构选型、向量化接入、记忆库构建与召回到一段可运行的 Agent 记忆 Demo完整走通一条断网可用的端侧 RAG 链路。一、端侧 RAG 的架构与选型为什么是 GGUF一条最小可用的 RAG 流水线由五步组成文档切块 → 文本向量化 → 写入向量库 → 查询向量化 → 向量库召回 top-k → 拼入提示词交给 LLM 生成回答。其中向量化是决定检索质量的一环而向量库 嵌入模型的选型直接决定了这条链路能不能在端侧成立。端侧部署对嵌入模型的约束有三条体积小、可 CPU 推理、生态兼容。EmbeddingGemma 2 的模块化设计正好命中纯文本只需 270M 参数130M transformer 140M embedder视觉170M与音频300M编码器可按需加载8K token 上下文是上一代的 4 倍可处理约 5.5 分钟音频、29 张图像或 58 帧视频。官方博客披露上一代 EmbeddingGemma 下载量已超过 2000 万次其 MTEB 多语言与代码评测成绩在 sub-1B 规模中领先代码检索单项从 68.76 提升至 78.689.92 分。选择 GGUF 格式的理由同样直接GGUF 是 llama.cpp 生态的标准分发格式文件即模型无需 Python 推理框架即可在 CPU 上以原生速度运行并提供 OpenAI 兼容的/v1/embeddingsHTTP 接口——这意味着向量化服务可以被任何语言、任何框架调用天然适合嵌入 Agent 这类多进程应用。本仓库提供了完整的量化矩阵数据来源README.md 及仓库文件文件大小定位embeddinggemma-2-UD-Q4_K_XL.gguf约 176 MB动态量化首选官方教程默认档位embeddinggemma-2-UD-Q5_K_XL.gguf约 210 MB精度/体积平衡档embeddinggemma-2-UD-Q6_K_XL.gguf约 249 MB高精度量化档embeddinggemma-2-Q8_0.gguf约 310 MB近无损量化档embeddinggemma-2-BF16.gguf约 558 MB全精度推荐参考档embeddinggemma-2-F16.gguf约 558 MB全精度变体mmproj-*.gguf约 555–982 MB多模态投影器视觉/音频编码器UD 系列即 Unsloth 的动态量化方案README 中标注其在保持精度的同时优于其他主流量化官方发布的本地运行教程默认选择约 176MB 的 UD-Q4_K_XL 文件可见其对资源占用与质量权衡的认可。选型时有一个极易踩的坑写进 README.md 的 Numerical Precision 一节该模型禁止以 FP16 精度推理。EmbeddingGemma 2 的激活值动态范围超出 FP16 可表达区间FP16 下模型不会报错而是悄悄返回 NaN 或降质向量——这种失败极其隐蔽。官方建议使用 BF16指数位与 FP32 相同内存减半或 FP32。这也是为什么仓库同时提供 BF16 与 F16 两份全精度文件生产环境请优先选择 BF16 或量化档位。二、向量化接入llama.cpp OpenAI 兼容端点接入的第一步是用包含 EmbeddingGemma 2 支持的 llama.cpp 构建启动一个嵌入服务。官方教程给出的启动参数如下注意三个关键点--embeddings开启嵌入模式、--pooling mean指定平均池化模型架构本身即为 Mean Pooling见 README.md 的架构表、--alias为模型注册一个便于 API 引用的名字./llama.cpp/build/bin/llama-server \ --model embeddinggemma-2-UD-Q4_K_XL.gguf \ --alias embeddinggemma2 \ --embeddings \ --pooling mean \ --ctx-size 2048 \ --batch-size 2048 \ --ubatch-size 2048 \ --parallel 1 \ --host 127.0.0.1 \ --port 8080输入超过 2048 token 时--ctx-size、--batch-size、--ubatch-size需同步调大上限 8192每条输入必须能放进单个物理 batch。服务起来后调用方式与 OpenAI Embeddings API 完全一致。这里有一个 EmbeddingGemma 2 特有的细节任务指令前缀Task Instruction Prefixes。模型训练时会在文本前拼接短指令前缀以区分任务类型检索这类非对称任务中查询与文档应使用不同的前缀curl http://127.0.0.1:8080/v1/embeddings \ -H Content-Type: application/json \ -d { model: embeddinggemma2, input: [ task: search result | query: 如何在离线环境给 Agent 添加记忆, title: none | text: 检索增强生成通过向量召回将私有知识注入提示词全程无需联网。 ], encoding_format: float }README.md 的 Best Practices 一节给出了完整的前缀体系Web/文档检索用task: search result | query: {...}作为查询前缀、文档用title: {title} | text: {content}无标题时写作title: none问答用task: question answering、代码检索用task: code retrieval对称任务分类、聚类、相似度则对全部输入使用同一前缀如task: sentence similarity | query: {...}。漏掉前缀不会报错但会静默降低检索精度——这正是社区教程反复强调必须手动拼接的原因。多模态输入图像/视频/音频不需要任何前缀。拿到响应后建议先校验向量质量每个向量应有 768 个有限数值非 NaN/Inf再写入索引。三、离线记忆库的构建与召回向量化只是第一步记忆库的核心是存得小、召得准。EmbeddingGemma 2 原生支持 Matryoshka 表示学习MRL768 维输出可以直接截断为 512、256 或 128 维。官方评测显示见 README.md 截断评测表压缩到 256 维1:3时 MTEB 多语言均值仅从 61.36 降至 60.41几乎无损128 维1:6时降至 57.89多模态质量下降明显更适合纯文本场景。存储收益可以量化以 100 万条文档为例768 维 float32 向量约占用 2.86GB压缩到 128 维后仅约 477MB——6 倍的存储压缩比。对于端侧 Agent 长期积累的记忆库这是决定可行性的关键数字。但 MRL 有两个必须遵守的工程约束同为 README.md 的明确警告截断后必须重新 L2 归一化。对单位向量做切片不会保持单位长度跳过归一化会导致静默降级——检索结果看起来合理但排序质量悄悄劣化查询与文档必须使用相同维度。768 维的查询向量无法与 128 维的库内向量正确计算余弦相似度。在 Python 侧使用 SentenceTransformers 时直接在encode()中传参即可规避手工截断的坑query_emb model.encode( query, prompt_nameSearchQuery, # 对称任务改用 SentenceSimilarity 等 truncate_dim256, # 或 512 / 128 normalize_embeddingsTrue, # 截断后自动重归一化 )召回阶段的数据结构可以非常朴素一个 NumPy 矩阵 余弦相似度 top-k 排序就足以支撑万级记忆条目的端侧检索规模再大可以平滑替换为 Chroma、LanceDB、FAISS 等本地向量库。社区实测也印证了模型的中文与跨语言能力有作者在无 GPU 的普通 PC 上验证埃菲尔铁塔位于巴黎与英文原文的跨语言相似度达到 0.846说明多语言检索在端侧并非能用而已。四、一个可跑的 Agent 记忆 Demo把以上三段串起来就是一条完整的离线记忆流水线llama-server提供向量化 生成式 LLM 两个本地服务中间用一段不到百行的 Python 粘合写入记忆与召回记忆。Step 1启动嵌入服务命令见第二节。Step 2写一个通用的嵌入客户端与记忆库import json, numpy as np, urllib.request EMB_URL http://127.0.0.1:8080/v1/embeddings def embed(texts, prefixtitle: none | text: ): 文档侧统一加 Document 前缀查询侧用 query 前缀单独调用。 payload json.dumps({ model: embeddinggemma2, input: [prefix t for t in texts], encoding_format: float, }).encode() req urllib.request.Request(EMB_URL, datapayload, headers{Content-Type: application/json}) data json.loads(urllib.request.urlopen(req, timeout30).read()) return np.array([d[embedding] for d in data[data]], dtypenp.float32) class MemoryBank: def __init__(self, dim256): # 与查询侧保持同一维度 self.docs, self.vectors [], np.zeros((0, dim), dtypenp.float32) def add(self, texts): vecs embed(texts) vecs / np.linalg.norm(vecs, axis1, keepdimsTrue) # L2 归一化 self.docs list(texts) self.vectors np.vstack([self.vectors, vecs]) def recall(self, query, k3): q embed([query], prefixtask: search result | query: )[0] q / np.linalg.norm(q) scores self.vectors q # 余弦相似度 top np.argsort(scores)[::-1][:k] return [(self.docs[i], float(scores[i])) for i in top]Step 3Agent 的记忆读写循环。Agent 每次学到新事实对话总结、用户偏好、私有文档时调用bank.add(...)写入每次推理前调用bank.recall(user_input)取回最相关的 k 条记忆拼进提示词后交给本地生成模型如 Gemma 4作答memory MemoryBank() memory.add([ 用户偏好简洁的终端命令讨厌 GUI 工具。, 上周解决了项目 A 的依赖冲突需要固定 pydantic2。, 团队约定所有 Agent 日志输出到 ~/.agent/logs/。, ]) def answer(user_input, llm_urlhttp://127.0.0.1:11434/api/generate): hits memory.recall(user_input, k3) context \n.join(f[记忆] {doc} (相关度 {s:.3f}) for doc, s in hits) prompt f基于以下记忆回答用户\n{context}\n\n用户{user_input}\n回答 # 调用本地 LLM如 Ollama 上的 gemma4全程无外网请求 ...至此一条写入记忆 → 语义召回 → 离线生成的闭环已经在纯本地硬件上跑通。检索质量与存储成本的权衡通过dim参数一改即得追求召回精度用 768追求存储极限用 128。值得一提的延伸是本仓库还包含 mmproj-BF16.gguf、mmproj-Q8_0.gguf 等多模态投影器文件。EmbeddingGemma 2 支持在文本中插入|image|、|video|、|audio|占位符将图像、视频、音频与文本交织编码为同一个向量——这意味着 Agent 的记忆边界可以从纯文本扩展到看到过的截图、听过的会议录音、查过的商品图而查询侧依然只需一段文字。端侧 RAG 从离线问答走向离线多模态记忆只差把 mmproj 装进推理管线这一步。嵌入模型决定了 Agent 记忆的上限高度GGUF 量化决定了它能否装进你的设备。当 176MB 的权重文件与 128 维的向量库组合在一起一个完全离线、数据不出本机的记忆型 Agent已经不再是云端大厂的专属能力。【免费下载链接】embeddinggemma-2-GGUF项目地址: https://ai.gitcode.com/hf_mirrors/unsloth/embeddinggemma-2-GGUF创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/10/10 21:26:34 · 阅读 1.2k 端侧 RAG 实战：用 embeddinggemma-2 GGUF 给离线 AI Agent 装上记忆
端侧 RAG 实战用 embeddinggemma-2 GGUF 给离线 AI Agent 装上记忆【免费下载链接】embeddinggemma-2-GGUF项目地址: https://ai.gitcode.com/hf_mirrors/unsloth/embeddinggemma-2-GGUF大模型天生健忘每次对话结束上下文即被清空。要让 Agent 记住私有文档、历史记录或用户偏好业界标准答案是检索增强生成RAG——把知识先向量化、再按语义召回最后拼进提示词。但云上 RAG 意味着数据出境、按 token 计费、以及每一次检索都依赖网络往返对隐私敏感、网络受限或追求低延迟的场景这三点都是硬伤。2026 年 10 月 6 日Google DeepMind 正式发布 EmbeddingGemma 2——一个把文本、代码、图像、视频、音频统一映射到同一 768 维向量空间的多模态嵌入模型740M 参数、Apache 2.0 协议量产后在 Pixel 11 Pro 上纯文本权重仅占约 191MB 活跃内存。与此同时Unsloth 同步发布了本仓库的 GGUF 量化版本让这条完全离线的 RAG 流水线可以在普通 CPU 笔记本上直接跑起来。社区也迅速跟进围绕 Ollama/Docker 部署的教程密集出现掘金上已有人发布端侧 RAG 实战指南其核心目标正是赋予离线 AI 代理记忆。本文将以本仓库的 GGUF 文件为线索从架构选型、向量化接入、记忆库构建与召回到一段可运行的 Agent 记忆 Demo完整走通一条断网可用的端侧 RAG 链路。一、端侧 RAG 的架构与选型为什么是 GGUF一条最小可用的 RAG 流水线由五步组成文档切块 → 文本向量化 → 写入向量库 → 查询向量化 → 向量库召回 top-k → 拼入提示词交给 LLM 生成回答。其中向量化是决定检索质量的一环而向量库 嵌入模型的选型直接决定了这条链路能不能在端侧成立。端侧部署对嵌入模型的约束有三条体积小、可 CPU 推理、生态兼容。EmbeddingGemma 2 的模块化设计正好命中纯文本只需 270M 参数130M transformer 140M embedder视觉170M与音频300M编码器可按需加载8K token 上下文是上一代的 4 倍可处理约 5.5 分钟音频、29 张图像或 58 帧视频。官方博客披露上一代 EmbeddingGemma 下载量已超过 2000 万次其 MTEB 多语言与代码评测成绩在 sub-1B 规模中领先代码检索单项从 68.76 提升至 78.689.92 分。选择 GGUF 格式的理由同样直接GGUF 是 llama.cpp 生态的标准分发格式文件即模型无需 Python 推理框架即可在 CPU 上以原生速度运行并提供 OpenAI 兼容的/v1/embeddingsHTTP 接口——这意味着向量化服务可以被任何语言、任何框架调用天然适合嵌入 Agent 这类多进程应用。本仓库提供了完整的量化矩阵数据来源README.md 及仓库文件文件大小定位embeddinggemma-2-UD-Q4_K_XL.gguf约 176 MB动态量化首选官方教程默认档位embeddinggemma-2-UD-Q5_K_XL.gguf约 210 MB精度/体积平衡档embeddinggemma-2-UD-Q6_K_XL.gguf约 249 MB高精度量化档embeddinggemma-2-Q8_0.gguf约 310 MB近无损量化档embeddinggemma-2-BF16.gguf约 558 MB全精度推荐参考档embeddinggemma-2-F16.gguf约 558 MB全精度变体mmproj-*.gguf约 555–982 MB多模态投影器视觉/音频编码器UD 系列即 Unsloth 的动态量化方案README 中标注其在保持精度的同时优于其他主流量化官方发布的本地运行教程默认选择约 176MB 的 UD-Q4_K_XL 文件可见其对资源占用与质量权衡的认可。选型时有一个极易踩的坑写进 README.md 的 Numerical Precision 一节该模型禁止以 FP16 精度推理。EmbeddingGemma 2 的激活值动态范围超出 FP16 可表达区间FP16 下模型不会报错而是悄悄返回 NaN 或降质向量——这种失败极其隐蔽。官方建议使用 BF16指数位与 FP32 相同内存减半或 FP32。这也是为什么仓库同时提供 BF16 与 F16 两份全精度文件生产环境请优先选择 BF16 或量化档位。二、向量化接入llama.cpp OpenAI 兼容端点接入的第一步是用包含 EmbeddingGemma 2 支持的 llama.cpp 构建启动一个嵌入服务。官方教程给出的启动参数如下注意三个关键点--embeddings开启嵌入模式、--pooling mean指定平均池化模型架构本身即为 Mean Pooling见 README.md 的架构表、--alias为模型注册一个便于 API 引用的名字./llama.cpp/build/bin/llama-server \ --model embeddinggemma-2-UD-Q4_K_XL.gguf \ --alias embeddinggemma2 \ --embeddings \ --pooling mean \ --ctx-size 2048 \ --batch-size 2048 \ --ubatch-size 2048 \ --parallel 1 \ --host 127.0.0.1 \ --port 8080输入超过 2048 token 时--ctx-size、--batch-size、--ubatch-size需同步调大上限 8192每条输入必须能放进单个物理 batch。服务起来后调用方式与 OpenAI Embeddings API 完全一致。这里有一个 EmbeddingGemma 2 特有的细节任务指令前缀Task Instruction Prefixes。模型训练时会在文本前拼接短指令前缀以区分任务类型检索这类非对称任务中查询与文档应使用不同的前缀curl http://127.0.0.1:8080/v1/embeddings \ -H Content-Type: application/json \ -d { model: embeddinggemma2, input: [ task: search result | query: 如何在离线环境给 Agent 添加记忆, title: none | text: 检索增强生成通过向量召回将私有知识注入提示词全程无需联网。 ], encoding_format: float }README.md 的 Best Practices 一节给出了完整的前缀体系Web/文档检索用task: search result | query: {...}作为查询前缀、文档用title: {title} | text: {content}无标题时写作title: none问答用task: question answering、代码检索用task: code retrieval对称任务分类、聚类、相似度则对全部输入使用同一前缀如task: sentence similarity | query: {...}。漏掉前缀不会报错但会静默降低检索精度——这正是社区教程反复强调必须手动拼接的原因。多模态输入图像/视频/音频不需要任何前缀。拿到响应后建议先校验向量质量每个向量应有 768 个有限数值非 NaN/Inf再写入索引。三、离线记忆库的构建与召回向量化只是第一步记忆库的核心是存得小、召得准。EmbeddingGemma 2 原生支持 Matryoshka 表示学习MRL768 维输出可以直接截断为 512、256 或 128 维。官方评测显示见 README.md 截断评测表压缩到 256 维1:3时 MTEB 多语言均值仅从 61.36 降至 60.41几乎无损128 维1:6时降至 57.89多模态质量下降明显更适合纯文本场景。存储收益可以量化以 100 万条文档为例768 维 float32 向量约占用 2.86GB压缩到 128 维后仅约 477MB——6 倍的存储压缩比。对于端侧 Agent 长期积累的记忆库这是决定可行性的关键数字。但 MRL 有两个必须遵守的工程约束同为 README.md 的明确警告截断后必须重新 L2 归一化。对单位向量做切片不会保持单位长度跳过归一化会导致静默降级——检索结果看起来合理但排序质量悄悄劣化查询与文档必须使用相同维度。768 维的查询向量无法与 128 维的库内向量正确计算余弦相似度。在 Python 侧使用 SentenceTransformers 时直接在encode()中传参即可规避手工截断的坑query_emb model.encode( query, prompt_nameSearchQuery, # 对称任务改用 SentenceSimilarity 等 truncate_dim256, # 或 512 / 128 normalize_embeddingsTrue, # 截断后自动重归一化 )召回阶段的数据结构可以非常朴素一个 NumPy 矩阵 余弦相似度 top-k 排序就足以支撑万级记忆条目的端侧检索规模再大可以平滑替换为 Chroma、LanceDB、FAISS 等本地向量库。社区实测也印证了模型的中文与跨语言能力有作者在无 GPU 的普通 PC 上验证埃菲尔铁塔位于巴黎与英文原文的跨语言相似度达到 0.846说明多语言检索在端侧并非能用而已。四、一个可跑的 Agent 记忆 Demo把以上三段串起来就是一条完整的离线记忆流水线llama-server提供向量化 生成式 LLM 两个本地服务中间用一段不到百行的 Python 粘合写入记忆与召回记忆。Step 1启动嵌入服务命令见第二节。Step 2写一个通用的嵌入客户端与记忆库import json, numpy as np, urllib.request EMB_URL http://127.0.0.1:8080/v1/embeddings def embed(texts, prefixtitle: none | text: ): 文档侧统一加 Document 前缀查询侧用 query 前缀单独调用。 payload json.dumps({ model: embeddinggemma2, input: [prefix t for t in texts], encoding_format: float, }).encode() req urllib.request.Request(EMB_URL, datapayload, headers{Content-Type: application/json}) data json.loads(urllib.request.urlopen(req, timeout30).read()) return np.array([d[embedding] for d in data[data]], dtypenp.float32) class MemoryBank: def __init__(self, dim256): # 与查询侧保持同一维度 self.docs, self.vectors [], np.zeros((0, dim), dtypenp.float32) def add(self, texts): vecs embed(texts) vecs / np.linalg.norm(vecs, axis1, keepdimsTrue) # L2 归一化 self.docs list(texts) self.vectors np.vstack([self.vectors, vecs]) def recall(self, query, k3): q embed([query], prefixtask: search result | query: )[0] q / np.linalg.norm(q) scores self.vectors q # 余弦相似度 top np.argsort(scores)[::-1][:k] return [(self.docs[i], float(scores[i])) for i in top]Step 3Agent 的记忆读写循环。Agent 每次学到新事实对话总结、用户偏好、私有文档时调用bank.add(...)写入每次推理前调用bank.recall(user_input)取回最相关的 k 条记忆拼进提示词后交给本地生成模型如 Gemma 4作答memory MemoryBank() memory.add([ 用户偏好简洁的终端命令讨厌 GUI 工具。, 上周解决了项目 A 的依赖冲突需要固定 pydantic2。, 团队约定所有 Agent 日志输出到 ~/.agent/logs/。, ]) def answer(user_input, llm_urlhttp://127.0.0.1:11434/api/generate): hits memory.recall(user_input, k3) context \n.join(f[记忆] {doc} (相关度 {s:.3f}) for doc, s in hits) prompt f基于以下记忆回答用户\n{context}\n\n用户{user_input}\n回答 # 调用本地 LLM如 Ollama 上的 gemma4全程无外网请求 ...至此一条写入记忆 → 语义召回 → 离线生成的闭环已经在纯本地硬件上跑通。检索质量与存储成本的权衡通过dim参数一改即得追求召回精度用 768追求存储极限用 128。值得一提的延伸是本仓库还包含 mmproj-BF16.gguf、mmproj-Q8_0.gguf 等多模态投影器文件。EmbeddingGemma 2 支持在文本中插入|image|、|video|、|audio|占位符将图像、视频、音频与文本交织编码为同一个向量——这意味着 Agent 的记忆边界可以从纯文本扩展到看到过的截图、听过的会议录音、查过的商品图而查询侧依然只需一段文字。端侧 RAG 从离线问答走向离线多模态记忆只差把 mmproj 装进推理管线这一步。嵌入模型决定了 Agent 记忆的上限高度GGUF 量化决定了它能否装进你的设备。当 176MB 的权重文件与 128 维的向量库组合在一起一个完全离线、数据不出本机的记忆型 Agent已经不再是云端大厂的专属能力。【免费下载链接】embeddinggemma-2-GGUF项目地址: https://ai.gitcode.com/hf_mirrors/unsloth/embeddinggemma-2-GGUF创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考