ollama部署本地大模型｜embeddinggemma-300m向量化服务Python调用完整示例

想在自己的电脑上跑一个强大的文本向量化模型，但又担心它太大、太慢、太复杂？今天，我们就来搞定这件事。我将带你一步步用ollama部署一个名为embeddinggemma-300m的轻量级嵌入模型，并手把手教你如何用Python调用它，把一段段文字变成机器能理解的“数字指纹”。整个过程非常简单，即使你之前没怎么接触过AI模型部署，也能轻松跟上。

1. 为什么选择embeddinggemma-300m？

在开始动手之前，我们先花一分钟了解一下，我们即将部署的这个“小能手”到底有什么过人之处。

embeddinggemma-300m 是谷歌开源的一个文本嵌入模型。你可以把它理解为一个“文本翻译器”，但它不是把中文翻译成英文，而是把任何一段文字（比如一句话、一段文章）翻译成一串有意义的数字（也就是向量）。这串数字就像是这段文字的“DNA”或“指纹”。

有了这个“数字指纹”，计算机就能做很多聪明事：

• 找相似内容：比如，你输入“如何养猫”，它能帮你从海量文章里找到讲“猫咪饲养指南”、“宠物猫的日常护理”的相关内容，即使字面不完全一样。
• 文本分类：自动给新闻贴标签，比如科技、体育、娱乐。
• 智能聚类：把用户评论自动分成好评、中评、差评等几大类。

它最大的优点就是“小而精”。虽然名字里有“3亿参数”，听起来很大，但在AI模型世界里，它属于非常轻量级的选手。这意味着你可以在普通的笔记本电脑上流畅运行它，不需要昂贵的显卡，真正实现了“尖端AI，触手可及”。

2. 环境准备与ollama部署

我们的第一步，是把embeddinggemma-300m这个模型“请”到我们的电脑里。我们将使用一个叫做 ollama 的工具，它能让模型部署变得像安装软件一样简单。

2.1 安装ollama

ollama支持Windows、macOS和Linux。这里以macOS/Linux为例，Windows用户可以去官网下载安装包。

打开你的终端（Terminal），执行以下命令一键安装：

curl -fsSL https://ollama.ai/install.sh | sh

安装完成后，运行下面命令启动ollama服务：

ollama serve

服务会一直在后台运行。请保持这个终端窗口打开，或者以后台方式运行它。

2.2 拉取embeddinggemma-300m模型

打开一个新的终端窗口，输入以下命令。ollama会自动从模型库中下载embeddinggemma-300m模型。

ollama pull embeddinggemma:300m

下载时间取决于你的网速，模型大约几百MB。看到“success”的提示，就表示模型已经安安稳稳地躺在你的电脑里了。

2.3 验证模型是否就绪

我们可以先通过ollama自带的命令行简单测试一下模型是否能正常工作。

ollama run embeddinggemma:300m “Hello, world!”

这条命令会让模型对“Hello, world!”这句话生成嵌入向量。如果一切正常，你会在终端看到输出一长串数字（就是向量），这说明模型部署成功了！

3. Python调用：从理论到实践

模型部署好了，接下来就是重头戏：如何在我们自己的Python程序里使用它。ollama提供了一个非常方便的HTTP API，我们的Python代码通过发送HTTP请求来和模型“对话”。

3.1 安装必要的Python库

我们主要会用到requests库来发送HTTP请求。用pip安装它：

pip install requests

3.2 你的第一个嵌入向量生成脚本

让我们写一个最简单的Python脚本，体验一下生成文本向量的过程。创建一个新文件，比如叫做get_embedding.py。

import requests
import json

# 1. 定义ollama服务的地址和模型名称
OLLAMA_URL = “http://localhost:11434/api/embeddings”
MODEL_NAME = “embeddinggemma:300m”

# 2. 准备我们要向量化的文本
text_to_embed = “人工智能正在改变世界。”

# 3. 构造请求数据
payload = {
    “model”: MODEL_NAME,
    “prompt”: text_to_embed
}

# 4. 发送POST请求到ollama API
try:
    response = requests.post(OLLAMA_URL, json=payload)
    response.raise_for_status()  # 检查请求是否成功
    # 5. 解析返回的JSON数据
    result = response.json()
    # 提取嵌入向量（那串数字）
    embedding_vector = result[“embedding”]
    # 6. 打印结果
    print(f“文本：'{text_to_embed}'”)
    print(f“生成的向量维度：{len(embedding_vector)}”)
    print(f“向量前10个值：{embedding_vector[:10]}...”) # 只打印前10个值，因为太长了
except requests.exceptions.RequestException as e:
    print(f“请求出错：{e}”)
except KeyError:
    print(“返回的数据格式不符合预期。”)

运行这个脚本：

python get_embedding.py

如果成功，你会看到类似这样的输出：

文本：'人工智能正在改变世界。'
生成的向量维度：768
向量前10个值：[0.045, -0.123, 0.087, ...]...

恭喜！你已经成功用Python生成了第一个文本嵌入向量。这个768维的向量，就是句子“人工智能正在改变世界。”在这个模型眼中的唯一数学表示。

4. 实战进阶：构建一个简易语义搜索系统

光生成向量还不够酷，我们来点实际的：用这个模型搭建一个微型语义搜索引擎。假设我们有一个小文档库，用户输入一个问题，我们要找出库中最相关的文档。

4.1 步骤一：建立文档库并生成向量库

我们先准备几个简单的“文档”，并预先为它们生成好嵌入向量，存起来。

import requests
import json
import numpy as np
from typing import List, Dict

OLLAMA_URL = “http://localhost:11434/api/embeddings”
MODEL_NAME = “embeddinggemma:300m”

def get_embedding(text: str) -> List[float]:
    “”“获取单段文本的嵌入向量”“”
    payload = {“model”: MODEL_NAME, “prompt”: text}
    response = requests.post(OLLAMA_URL, json=payload)
    response.raise_for_status()
    return response.json()[“embedding”]

# 我们的迷你文档库
documents = [
    “Python是一种高级编程语言，以简洁易读著称。”,
    “机器学习是人工智能的一个分支，让计算机能从数据中学习。”,
    “深度学习利用神经网络处理复杂问题，如图像识别和自然语言处理。”,
    “Ollama是一个帮助你在本地轻松运行大模型的工具。”,
    “向量搜索通过比较数字向量的相似度来找到相关内容。”
]

print(“正在为文档库生成嵌入向量...”)
document_embeddings = []
for doc in documents:
    vec = get_embedding(doc)
    document_embeddings.append(vec)
    print(f“文档 ‘{doc[:20]}...’ 向量化完成。”)

# 将文档和向量保存起来（这里用变量模拟存储）
knowledge_base = list(zip(documents, document_embeddings))
print(“\n文档向量库构建完成！”)

4.2 步骤二：计算相似度并返回结果

当用户输入一个查询时，我们计算查询语句的向量，然后和文档库里每一个文档的向量计算“余弦相似度”（一种衡量向量方向接近程度的方法，值越接近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 search_similar_documents(query: str, top_k: int = 3):
    “”“语义搜索：找到与查询最相关的文档”“”
    print(f“\n用户查询：'{query}'”)
    # 1. 获取查询语句的向量
    query_embedding = get_embedding(query)
    
    # 2. 计算与每个文档的相似度
    similarities = []
    for doc_text, doc_vec in knowledge_base:
        score = cosine_similarity(query_embedding, doc_vec)
        similarities.append((doc_text, score))
    
    # 3. 按相似度分数从高到低排序
    similarities.sort(key=lambda x: x[1], reverse=True)
    
    # 4. 返回最相关的top_k个结果
    print(f“找到最相关的 {top_k} 个文档：”)
    for i, (doc, score) in enumerate(similarities[:top_k], 1):
        print(f“{i}. [相似度：{score:.4f}] {doc}”)

# 来试试搜索效果！
if __name__ == “__main__”:
    # 测试几个查询
    search_similar_documents(“什么是神经网络？”, top_k=2)
    search_similar_documents(“介绍下编程语言”, top_k=2)

运行这段完整的代码，你会看到类似下面的输出：

正在为文档库生成嵌入向量...
文档 ‘Python是一种高级编程语言...’ 向量化完成。
...
文档向量库构建完成！

用户查询：'什么是神经网络？'
找到最相关的 2 个文档：
1. [相似度：0.8921] 深度学习利用神经网络处理复杂问题，如图像识别和自然语言处理。
2. [相似度：0.7563] 机器学习是人工智能的一个分支，让计算机能从数据中学习。

用户查询：'介绍下编程语言'
找到最相关的 2 个文档：
1. [相似度：0.9345] Python是一种高级编程语言，以简洁易读著称。
2. [相似度：0.7012] Ollama是一个帮助你在本地轻松运行大模型的工具。

看！即使查询语句“什么是神经网络？”和文档“深度学习利用神经网络...”没有相同的字眼，模型也能凭借对语义的理解，找到最相关的内容。这就是嵌入向量的魔力。

5. 常见问题与实用技巧

在实际使用中，你可能会遇到一些小问题，这里有一些提示：

• 连接错误：确保ollama serve正在运行。检查URL http://localhost:11434 在浏览器中是否能打开（会显示Ollama的API信息）。
• 速度优化：第一次生成某个句子的向量会稍慢，因为模型需要加载计算。后续相同或相似的句子会快很多。对于批量处理，可以考虑简单的缓存机制。
• 文本长度：嵌入模型通常有最大文本长度限制。如果文本非常长，可能需要先进行分段，再分别获取每段的向量，或者使用更高级的聚合策略（如取平均）。
• 生产环境：本篇教程主要用于本地开发和测试。如果需要在生产环境中服务更多请求，你可能需要考虑使用更高效的Web框架（如FastAPI）来封装这个功能，并管理模型加载和并发请求。

6. 总结

回顾一下我们今天完成的事情：

1. 认识了embeddinggemma-300m：一个强大且轻量的文本嵌入模型，适合本地部署。
2. 使用ollama一键部署：用几行命令就把模型拉取到本地并运行起来。
3. 掌握了Python核心调用方法：通过HTTP API，我们学会了如何用requests库与模型交互，生成文本向量。
4. 实现了一个迷你语义搜索Demo：从构建向量库到计算相似度，我们完成了一个完整可用的语义搜索流程，亲眼见证了基于嵌入的搜索如何理解语义而非关键词。

整个过程没有复杂的深度学习框架，没有令人头疼的环境配置，就是简单的工具和清晰的代码。你现在已经拥有了在本地处理文本语义理解的能力，可以把它应用到你的个人项目、实验或者学习中去，比如构建个人知识库检索、分析社交媒体评论情感、对文章自动分类等等。

希望这篇教程能成为你探索本地AI应用的一块扎实的敲门砖。动手试试，修改代码，用它来解决你实际遇到的问题吧！

---

获取更多AI镜像

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