手把手教学：用Ollama玩转谷歌开源嵌入模型

手把手教学：用Ollama玩转谷歌开源嵌入模型

你是不是经常遇到这样的问题：想在自己的电脑上跑一个AI模型，但发现要么模型太大跑不动，要么部署过程太复杂直接劝退？特别是对于文本搜索、智能问答这类需要理解语义的任务，传统的关键词匹配已经不够用了，而大模型的嵌入（Embedding）能力又往往需要昂贵的云端算力。

今天，我要带你玩一个特别有意思的东西——谷歌开源的轻量级嵌入模型 EmbeddingGemma-300M。它只有3亿参数，却能在你的笔记本电脑上流畅运行，帮你把文本变成计算机能理解的“向量”，轻松实现语义搜索、文档分类、智能问答等功能。

更棒的是，我们将通过Ollama这个神器来部署它。Ollama就像是一个AI模型的“应用商店”，让你用几条简单的命令就能把模型跑起来，完全不需要操心复杂的依赖和环境配置。

这篇文章，我会手把手带你从零开始，完成整个部署和使用的全过程。无论你是开发者、学生，还是对AI技术感兴趣的爱好者，都能跟着一步步操作，亲眼看到这个模型如何工作。

1. 认识我们的主角：EmbeddingGemma-300M

在开始动手之前，我们先花几分钟了解一下我们要用的这个模型。知道它在做什么，后面的操作会更有方向。

1.1 什么是文本嵌入？

你可以把“文本嵌入”想象成一种“翻译”。我们人类读一段文字，能理解它的意思、情感和背后的信息。但计算机看不懂文字，它只认识数字。

嵌入模型的工作，就是把一段文字（比如“今天天气真好”）转换成一串有意义的数字（比如[0.12, -0.45, 0.78, ...]），这串数字就叫“向量”或“嵌入向量”。关键是，语义相似的文字，转换出来的数字串也会很相似。

举个例子：

• “我喜欢吃苹果”转换成的向量，和“我爱吃水果”的向量，在数学上会很接近。
• “我喜欢吃苹果”的向量，和“今天股市大跌”的向量，就会相差很远。

有了这个能力，我们就能让计算机“理解”文本，并基于这种理解去做事，比如：

• 语义搜索：不再只是匹配关键词，而是找意思相近的内容。
• 智能分类：自动把相似主题的文档归到一起。
• 问答系统：从一堆文档里找到能回答你问题的段落。

1.2 为什么选择EmbeddingGemma-300M？

市面上嵌入模型很多，比如OpenAI的text-embedding-ada-002，效果很好，但需要联网调用API，有费用和延迟问题。而EmbeddingGemma-300M有几个独特的优势，特别适合我们个人和小团队使用：

1. 轻量级，本地可跑：参数量仅3亿，经过量化后，在内存（RAM）不到200MB的设备上就能运行。这意味着你的普通笔记本电脑甚至一些开发板都能胜任。
2. 功能专一且强大：它基于谷歌最新的Gemma 3架构打造，专注于生成高质量的文本向量。支持2K长度的文本输入（能处理很长的段落），并且输出向量的维度可以在768到128之间灵活选择，让你在速度和精度之间做权衡。
3. 多语言支持：使用了100多种口语语言的数据进行训练，对中文的支持非常友好。
4. 完全开源免费：谷歌开源，可以随意下载、使用、甚至修改，没有调用次数和费用的限制。
5. 离线运行，数据安全：所有计算都在你自己的设备上完成，敏感文档数据无需上传到云端，安全可控。

简单说，它是一个为你个人电脑量身定制的、专业级的文本理解引擎。接下来，我们就让它转起来。

2. 环境准备：安装Docker与Ollama

我们将使用Docker来运行Ollama，这是最简单、最干净的方式，能避免各种环境冲突问题。请确保你的电脑已经安装了Docker。

2.1 安装Docker

如果你还没有安装Docker，可以参考以下步骤：

• Windows/Mac用户：直接访问 Docker官网 下载 Docker Desktop 安装包，图形化安装非常方便。
• Linux用户（以Ubuntu为例）：可以通过命令行快速安装。

# 更新软件包索引 sudo apt-get update # 安装必要的依赖 sudo apt-get install ca-certificates curl # 添加Docker官方GPG密钥 sudo install -m 0755 -d /etc/apt/keyrings sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc sudo chmod a+r /etc/apt/keyrings/docker.asc # 添加Docker软件源 echo \ "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \ $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \ sudo tee /etc/apt/sources.list.d/docker.list > /dev/null # 再次更新并安装Docker引擎 sudo apt-get update sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin # 验证安装，运行hello-world镜像 sudo docker run hello-world

看到“Hello from Docker!”的输出，说明安装成功。

2.2 使用Docker启动Ollama服务

Ollama官方提供了现成的Docker镜像，我们只需要一条命令就能把它跑起来。

打开你的终端（Windows用PowerShell或CMD，Mac/Linux用Terminal），执行以下命令：

docker run -d -v ollama:/root/.ollama -p 11434:11434 --name ollama ollama/ollama

我来解释一下这条命令做了什么：

• docker run：运行一个容器。
• -d：在后台运行（守护进程模式）。
• -v ollama:/root/.ollama：创建一个名为ollama的持久化数据卷，并挂载到容器内的/root/.ollama目录。这个很重要，它保证了我们下载的模型文件在容器重启后不会丢失。
• -p 11434:11434：将容器内部的11434端口映射到主机的11434端口。Ollama的API服务就运行在这个端口上。
• --name ollama：给这个容器起个名字，方便后续管理。
• ollama/ollama：要使用的Docker镜像名称。

执行后，你可以用下面的命令检查容器是否正常运行：

docker ps

你应该能看到一个名为ollama的容器正在运行。至此，Ollama服务就已经在后台默默启动了，它正在监听本地的11434端口，等待我们发号施令。

3. 下载并运行EmbeddingGemma模型

Ollama服务跑起来了，现在我们要告诉它：“去把EmbeddingGemma这个模型给我下载下来”。

3.1 进入Ollama容器并拉取模型

我们需要进入刚才创建的ollama容器内部去执行命令。在终端中运行：

docker exec -it ollama bash

这个命令会打开一个交互式的bash shell，就像你登录到了容器内部的操作系统一样。命令行提示符可能会变成类似root@容器ID:/#的样子。

现在，在这个容器内部的shell里，使用Ollama的pull命令下载模型：

ollama pull embeddinggemma:300m

这里我们指定了embeddinggemma:300m这个标签，确保拉取的是300M参数的精简版本。下载过程需要一些时间，取决于你的网速。你会看到下载进度条。

国内网络优化提示：如果下载速度很慢或总是失败，可能是因为网络连接问题。你可以尝试重启Ollama服务（见文末“常见问题”部分），或者寻找配置国内镜像源的方法（由于主题限制，不在此展开，但相关资源很容易搜索到）。

下载完成后，你可以列出本地已有的模型进行确认：

ollama list

你应该能看到embeddinggemma:300m出现在列表中。

3.2 验证模型嵌入功能

模型下载好了，我们写一个最简单的Python脚本来测试它是否能正常工作。首先，退出容器（在容器shell里输入exit），回到你自己的主机环境。

在你的工作目录下，创建一个名为test_embedding.py的文件，并输入以下代码：

import requests import json def get_embedding(prompt: str, model: str = "embeddinggemma:300m", url: str = "http://localhost:11434/api/embeddings"): """ 从Ollama API获取给定文本的嵌入向量。 """ payload = { "model": model, "prompt": prompt } try: response = requests.post(url, data=json.dumps(payload)) response.raise_for_status() # 检查HTTP错误 response_data = response.json() embedding_vector = response_data.get("embedding") return embedding_vector except Exception as e: print(f"获取嵌入向量时出错: {e}") return None # 测试 if __name__ == "__main__": test_text = "谷歌的EmbeddingGemma是一个轻量级嵌入模型。" embedding = get_embedding(test_text) if embedding: print("成功取得嵌入向量！") print(f"向量前5维: {embedding[:5]}") print(f"向量总维度: {len(embedding)}") else: print("失败。请检查Ollama服务是否运行，以及模型名称是否正确。")

运行这个脚本前，确保你的主机上安装了Python和requests库。如果没有，可以通过pip install requests安装。

然后运行脚本：

python test_embedding.py

如果一切顺利，你将看到类似下面的输出：

成功取得嵌入向量！ 向量前5维: [-0.15188363194465637, 0.016393350437283516, 0.02211342193186283, 0.001807519467547536, -0.02730322815477848] 向量总维度: 768

恭喜！这串数字就是“谷歌的EmbeddingGemma是一个轻量级嵌入模型。”这句话的数学表示。我们的模型已经成功运行，并具备了将文本转化为向量的核心能力。

4. 实战演练：构建一个简易的语义搜索系统

光能生成向量还不够酷，我们来做一个真正有用的小项目：一个本地文档语义搜索工具。假设你有一个知识库文档（比如产品说明书、学习笔记），你想用自然语言提问，它能帮你找到最相关的段落。

这个项目会用到RAG（检索增强生成）的基本思想：先用EmbeddingGemma把文档库和问题都变成向量，然后通过计算“余弦相似度”找到最相关的文档片段。

4.1 准备知识库和代码

首先，准备一个文本文件作为知识库，比如叫my_knowledge_base.txt，里面放一些内容。这里我用一段关于EmbeddingGemma的简介作为示例，你可以替换成任何你感兴趣的文本。

my_knowledge_base.txt 内容示例：

EmbeddingGemma是谷歌推出的开源文本嵌入模型，参数量为3亿。 它基于Gemma 3架构，能生成高质量的文本向量表示。 该模型支持超过100种语言，包括中文。 它特别适合在手机、笔记本电脑等资源有限的设备上运行。 主要功能包括语义搜索、文档聚类和问答系统。

接着，创建一个名为semantic_search.py的Python文件。代码稍长，但我会详细注释：

import numpy as np import requests import json from typing import List, Tuple # 复用我们之前写的获取嵌入向量的函数 def get_embedding(prompt: str, model: str = "embeddinggemma:300m") -> List[float]: url = "http://localhost:11434/api/embeddings" payload = {"model": model, "prompt": prompt} try: response = requests.post(url, data=json.dumps(payload)) response.raise_for_status() return response.json().get("embedding", []) except Exception as e: print(f"错误: 获取'{prompt[:30]}...'的嵌入向量失败 - {e}") return [] # 计算两个向量之间的余弦相似度（值越接近1越相似） def cosine_similarity(vec_a: List[float], vec_b: List[float]) -> float: a = np.array(vec_a) b = np.array(vec_b) return np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b)) def main(): # 1. 读取知识库文本并分割成句子 with open("my_knowledge_base.txt", "r", encoding="utf-8") as f: text = f.read() # 简单按句号分割，更复杂的文本可以优化分割逻辑 sentences = [s.strip() for s in text.split('。') if s.strip()] print(f"知识库加载完成，共 {len(sentences)} 个句子。") # 2. 为知识库中每个句子生成嵌入向量并存储 print("正在为知识库句子生成嵌入向量...") knowledge_base = [] # 存储（句子， 其向量） for i, sent in enumerate(sentences): print(f" 处理中 ({i+1}/{len(sentences)}): {sent[:40]}...") emb = get_embedding(sent) if emb: knowledge_base.append((sent, emb)) else: print(f" 警告: 句子 '{sent[:30]}...' 处理失败，已跳过。") # 3. 交互式搜索循环 print("\n===== 语义搜索系统已就绪 =====") print("输入你的问题（输入 'quit' 退出）：") while True: query = input("\n你的问题: ").strip() if query.lower() == 'quit': print("再见！") break if not query: continue # 4. 将用户问题也转化为向量 query_embedding = get_embedding(query) if not query_embedding: print("无法处理您的问题，请重试。") continue # 5. 计算问题与知识库中每个句子的相似度 similarities = [] for sent, sent_emb in knowledge_base: sim = cosine_similarity(query_embedding, sent_emb) similarities.append((sim, sent)) # 6. 按相似度从高到低排序 similarities.sort(key=lambda x: x[0], reverse=True) # 7. 展示最相关的3个结果 print(f"\n对于问题: '{query}'") print("找到的最相关结果：") for rank, (sim, sent) in enumerate(similarities[:3], 1): print(f" {rank}. [相似度: {sim:.4f}] {sent}") if __name__ == "__main__": main()

4.2 运行并体验语义搜索

确保你的Ollama容器正在运行，然后在终端执行：

python semantic_search.py

程序会先加载并处理你的知识库文本，然后进入交互模式。你可以尝试问一些问题，比如：

• 输入：EmbeddingGemma支持多少种语言？
• 输入：这个模型适合在什么设备上运行？
• 输入：它是用来做什么的？

看看系统返回的句子，是不是恰好能回答你的问题？尽管我们只是做了简单的向量相似度匹配，但效果已经比单纯的关键词搜索（比如搜“设备”两个字）要智能得多，因为它理解语义。

这就是嵌入模型的魔力：它将模糊的自然语言匹配，变成了精确的数学计算。

5. 进阶探索与常见问题

5.1 结合大模型进行智能问答（RAG完整流程）

上面的搜索系统只做到了“检索”，我们可以更进一步，把检索到的最相关片段，送给一个文本生成大模型（比如Gemma 3n），让它来组织语言，生成一个完整的答案。这就是一个简易的RAG流程。

你需要先通过Ollama拉取一个生成模型，例如ollama pull gemma3n:e2b（这是一个2B参数的轻量生成模型）。然后修改上面的代码，在检索到相关句子后，将它们作为上下文，连同问题一起发送给生成模型API (http://localhost:11434/api/generate)，让它合成最终答案。这会让你的问答系统更加流畅和智能。

5.2 常见问题与解决

在玩转的过程中，你可能会遇到一两个小麻烦，这里提供解决方案：

问题1：运行模型时提示this model does not support embeddings

• 原因：你使用的Ollama版本可能较旧，不支持该模型的嵌入功能。
• 解决：确保你使用的是我们通过Docker安装的最新版Ollama。如果问题依旧，可以尝试在容器内升级Ollama：ollama upgrade。

问题2：ollama pull下载模型超时或失败

• 原因：网络连接不稳定。
• 解决：
  1. 重启Ollama服务。在容器内，可以运行pkill -f ollama然后重新启动服务（对于Docker容器，更简单的方法是重启容器：docker restart ollama）。
  2. 配置国内镜像源，可以显著提升下载速度（具体方法可搜索“Ollama 国内镜像源”）。

问题3：如何管理Ollama容器和模型？

• 停止容器：docker stop ollama
• 启动容器：docker start ollama
• 删除容器：docker rm ollama（注意，这也会删除容器内的模型，但因为我们用了数据卷-v ollama:/root/.ollama，模型文件还在数据卷里）
• 查看模型列表：进入容器后执行ollama list
• 删除模型：进入容器后执行ollama rm 模型名

6. 总结

跟着这篇教程走下来，你已经完成了几件很酷的事：

1. 成功部署了一个专业的AI嵌入模型：在你的本地环境，通过Docker和Ollama，无痛安装了谷歌开源的EmbeddingGemma-300M。
2. 理解了嵌入模型的核心价值：看到了文本如何被转化为向量，以及如何利用向量相似度实现语义搜索。
3. 亲手构建了一个可用的语义搜索工具：虽然简单，但完整实现了从文档处理、向量化到相似度匹配的全流程。
4. 拥有了一个可扩展的AI应用基石：这个本地嵌入服务，可以作为你更多创意项目的基础，比如智能知识库、个性化推荐、文档自动归类等等。

EmbeddingGemma-300M + Ollama 的组合，极大地降低了使用先进AI技术的门槛。它把原本需要云端GPU和复杂工程的知识，变成了每个人在个人电脑上就能轻松玩转的工具。

技术的乐趣在于动手尝试和创造。现在，你的本地AI引擎已经启动，下一步就是用它去解决你实际遇到的问题。无论是整理你的个人笔记，还是为你开发的小应用增加智能搜索功能，这个轻量但强大的模型都能成为你的得力助手。

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。