Ollama本地部署与Embedding API调用实战：构建私有化语义搜索系统

在本地大模型应用开发中文本向量化Embedding是构建智能检索、语义搜索和RAG检索增强生成系统的基石。然而直接使用云端API不仅成本高还存在数据安全和网络延迟问题。Ollama作为一款优秀的本地大模型运行工具其内置的Embedding API功能为开发者提供了一个高性能、易部署、完全本地的向量化解决方案。本文将手把手带你完成Ollama的部署、Embedding模型的拉取并详细讲解如何通过Python和HTTP两种方式调用其Embedding API最终实现一个简单的语义相似度计算示例。无论你是想为个人知识库添加智能检索还是为企业内部文档构建私有化语义搜索服务这套方案都能让你快速上手。1. 背景与核心概念在深入实操之前我们有必要厘清几个核心概念这有助于理解我们正在构建什么以及为什么选择Ollama。1.1 什么是Embedding向量嵌入Embedding中文常译为“嵌入”或“向量化”其本质是将文本、图像、音频等高维离散的数据映射到一个低维连续的向量空间中。对于文本而言经过Embedding模型处理后一段话或一个词会被转换为一串固定长度的数字即向量。这个向量的神奇之处在于语义相近的文本其对应的向量在空间中的距离如余弦相似度也会很近。举个例子“我喜欢吃苹果”和“我爱吃水果”这两个句子经过Embedding后它们的向量相似度会很高。而“我喜欢吃苹果”和“今天天气很好”的向量相似度则会很低。这种特性使其成为语义搜索、文本分类、聚类和推荐系统的核心技术。1.2 为什么需要本地Embedding API常见的Embedding服务如OpenAI的text-embedding-ada-002、Cohere的API等虽然强大但存在明显痛点数据隐私敏感或内部文档发送到第三方服务器存在泄露风险。网络依赖与延迟每次调用都需要网络请求延迟不稳定影响用户体验。持续成本按调用次数或Token数计费长期使用成本不可忽视。定制化限制难以针对特定领域语料进行微调优化。本地部署Embedding API可以完美解决以上问题实现数据不出域、零延迟、一次部署长期免费使用的目标。1.3 Ollama简介及其优势Ollama是一个用于在本地运行、部署和管理大型语言模型LLM的开源框架。它简化了模型下载、运行和提供API服务的整个过程。对于Embedding任务Ollama的优势在于开箱即用无需复杂的环境配置一条命令即可启动模型服务。统一的API提供了与OpenAI API兼容的接口包括/v1/embeddings现有代码迁移成本极低。丰富的模型库支持众多优秀的开源Embedding模型如nomic-embed-text,bge-small-zh-v1.5,all-minilm等。资源友好许多轻量级Embedding模型如bge-small-zh-v1.5仅100MB左右对CPU和内存要求不高普通电脑即可运行。多平台支持支持macOS、Linux、Windows并可通过Docker部署。2. 环境准备与安装Ollama工欲善其事必先利其器。我们将从Ollama的安装开始并解决国内用户可能遇到的下载慢的问题。2.1 系统要求与安装Ollama对系统要求不高主流操作系统均可。对于Windows/macOS用户访问 Ollama官网 直接下载安装程序图形化界面安装即可。安装完成后通常会自动在后台启动服务。对于Linux用户以Ubuntu为例可以通过官方脚本安装这是最推荐的方式。# 使用curl下载安装脚本并执行 curl -fsSL https://ollama.com/install.sh | sh安装完成后Ollama会作为一个系统服务ollama.service自动运行。验证安装打开终端Windows用户可在PowerShell或CMD中操作输入以下命令ollama --version如果显示版本号如ollama version 0.1.xx则说明安装成功。2.2 配置国内镜像加速解决下载慢问题直接从Ollama官方拉取模型对于国内用户速度可能非常慢甚至失败。我们可以通过配置环境变量使用国内镜像源来加速。Linux/macOS在终端中执行以下命令修改或创建Shell配置文件如~/.bashrc,~/.zshrc。# 编辑配置文件例如使用nano编辑器 nano ~/.bashrc在文件末尾添加以下行export OLLAMA_HOST0.0.0.0 export OLLAMA_MODELS/path/to/your/models # 可选指定模型存放目录如D盘 # 关键设置镜像源这里以阿里云镜像为例镜像地址可能变动请以最新信息为准 export OLLAMA_ORIGINShttps://mirror.ghproxy.com/https://github.com/ollama/ollama # 对于模型拉取可以尝试在pull命令中直接使用镜像站URL非环境变量方式见下文保存文件后执行source ~/.bashrc使配置生效。Windows右键点击“此电脑” - “属性” - “高级系统设置” - “环境变量”。在“系统变量”或“用户变量”中点击“新建”。变量名OLLAMA_HOST变量值0.0.0.0。同样方法可以设置OLLAMA_MODELS变量来指定模型存放路径例如D:\ollama\models避免占用C盘空间。关于镜像源Windows环境变量设置可能不直接生效于模型拉取更有效的方法是在拉取命令中指定镜像。更通用的镜像拉取方法无论什么系统如果环境变量不奏效可以在拉取模型时在模型名前加上镜像站地址。目前一个可用的方法是使用ghproxy.com等GitHub代理。# 示例拉取bge-small-zh-v1.5模型 ollama pull bge-small-zh-v1.5 # 如果很慢可以尝试注意此方法非官方取决于镜像站是否支持ollama且地址可能失效 # OLLAMA_ORIGINShttps://mirror.ghproxy.com/https://github.com/ollama/ollama ollama pull bge-small-zh-v1.5重要提示国内镜像源状态不稳定如果上述方法失败可以搜索“Ollama 清华镜像源”或“Ollama 国内镜像”寻找最新的可用方案。有时使用稳定的网络环境直接拉取可能是最省心的选择。2.3 启动与检查Ollama服务安装后Ollama服务通常默认运行在http://localhost:11434。你可以通过以下命令管理服务# 查看服务状态 (Linux systemd) sudo systemctl status ollama # 启动服务 sudo systemctl start ollama # 停止服务 sudo systemctl stop ollama # 重启服务修改配置或模型后常用 sudo systemctl restart ollama对于Windows/macOS通常可以通过系统托盘或启动器来重启Ollama应用。检查API是否可用curl http://localhost:11434/api/tags如果返回一个JSON可能为空列表{models:[]}说明服务运行正常。3. 拉取与运行Embedding模型Ollama本身不包含模型需要我们从其模型库中拉取。我们将选择一个适合中文场景的轻量级模型。3.1 选择合适的Embedding模型Ollama支持多种Embedding模型可以通过ollama list查看已安装的通过ollama pull model-name拉取新的。对于中文文本推荐以下模型bge-small-zh-v1.5: 智源研究院开源的双语Embedding模型中文表现优异模型体积小约100MB非常适合入门和轻量级应用。nomic-embed-text: 一个通用的英文Embedding模型支持长上下文对于混合中英文的场景也可考虑。all-minilm: 一个轻量级的句子Transformer模型。本文以bge-small-zh-v1.5为例因为它对中文友好且资源占用低。3.2 拉取模型在终端中执行拉取命令ollama pull bge-small-zh-v1.5你会看到下载进度条。如果遇到网络错误请回顾2.2节配置镜像加速。常见的错误error: pull model manifest: file do通常与网络连接或镜像源问题有关。3.3 运行模型服务拉取完成后模型就可以使用了。Ollama的API服务是统一的当你通过API请求某个模型的Embedding时如果该模型未加载Ollama会自动将其加载到内存中。你也可以显式地“运行”一个模型这相当于将其预加载后续调用响应更快。ollama run bge-small-zh-v1.5执行这个命令会进入一个与模型的交互式对话界面对于LLM模型。对于Embedding模型这个界面用处不大通常我们直接通过API调用。你可以按CtrlD退出交互界面模型服务依然在后台可用。4. 调用Embedding APIPython实战Ollama提供了与OpenAI API格式兼容的接口这意味着我们可以使用熟悉的openaiPython库或者直接用requests库来调用。4.1 使用requests库直接调用这是最基础、依赖最少的方式。首先确保安装了requests库pip install requests# file: simple_embedding.py import requests import json # Ollama服务的地址 OLLAMA_URL http://localhost:11434 def get_embedding_using_requests(text, modelbge-small-zh-v1.5): 使用requests库直接调用Ollama的Embedding API url f{OLLAMA_URL}/api/embeddings payload { model: model, prompt: text # Ollama API 使用 prompt 字段传递文本 } headers { Content-Type: application/json } try: response requests.post(url, datajson.dumps(payload), headersheaders) response.raise_for_status() # 检查HTTP请求是否成功 result response.json() # 返回嵌入向量 return result.get(embedding) except requests.exceptions.RequestException as e: print(f请求失败: {e}) if response: print(f响应内容: {response.text}) return None if __name__ __main__: # 测试句子 sentences [ Ollama是一个本地大模型运行框架。, Embedding可以将文本转换为向量。, 今天天气真好我们一起去公园玩吧。 ] embeddings [] for sent in sentences: print(f正在处理: {sent}) embedding get_embedding_using_requests(sent) if embedding: # 打印向量维度长度 print(f 向量维度: {len(embedding)}) # 打印前5个元素看看样子 print(f 向量预览: {embedding[:5]}...\n) embeddings.append(embedding) else: print(f 处理失败\n) # 简单计算第一句和第二句的余弦相似度 (需要numpy) if len(embeddings) 2: try: import numpy as np vec1 np.array(embeddings[0]) vec2 np.array(embeddings[1]) # 余弦相似度 (A·B) / (||A|| * ||B||) cosine_sim np.dot(vec1, vec2) / (np.linalg.norm(vec1) * np.linalg.norm(vec2)) print(f句子1与句子2的余弦相似度: {cosine_sim:.4f}) # 预期前两句语义相关度更高相似度应大于0.5 except ImportError: print(请安装numpy以计算相似度: pip install numpy)4.2 使用openai兼容库调用由于Ollama兼容OpenAI API我们可以使用openai这个官方库只需修改base_url和api_key。首先安装pip install openai# file: openai_compatible_embedding.py from openai import OpenAI import numpy as np # 初始化客户端指向本地的Ollama服务 client OpenAI( base_urlhttp://localhost:11434/v1, # 注意这里是 /v1 api_keyollama, # Ollama不需要真实的API Key任意非空字符串即可 ) def get_embedding_using_openai(text, modelbge-small-zh-v1.5): 使用OpenAI兼容的客户端调用Embedding API try: response client.embeddings.create( modelmodel, inputtext # OpenAI SDK 使用 input 字段 ) return response.data[0].embedding except Exception as e: print(f调用OpenAI客户端失败: {e}) return None def calculate_cosine_similarity(vec1, vec2): 计算两个向量的余弦相似度 vec1 np.array(vec1) vec2 np.array(vec2) return np.dot(vec1, vec2) / (np.linalg.norm(vec1) * np.linalg.norm(vec2)) if __name__ __main__: texts [ 机器学习是人工智能的核心领域, 深度学习是机器学习的一个分支, 我喜欢在周末阅读科幻小说 ] print(使用OpenAI兼容库获取嵌入向量) all_embeddings [] for text in texts: emb get_embedding_using_openai(text) if emb is not None: print(f文本: {text[:30]}...) print(f 向量长度: {len(emb)}) all_embeddings.append(emb) # 计算相似度矩阵 if len(all_embeddings) len(texts): print(\n语义相似度矩阵:) for i in range(len(texts)): row [] for j in range(len(texts)): sim calculate_cosine_similarity(all_embeddings[i], all_embeddings[j]) row.append(f{sim:.3f}) print(f [{, .join(row)}]) # 预期前两句关于AI相似度高与第三句小说相似度低。运行上述任一脚本你就能看到文本被转换成了768维bge-small-zh-v1.5的输出维度的向量并且语义相近的文本其向量相似度更高。5. 集成到实际应用构建简易语义搜索理解了基础调用后我们将其集成到一个简单的语义搜索示例中模拟一个FAQ问答系统。5.1 项目结构semantic_search_demo/ ├── embeddings.py # 封装Embedding获取功能 ├── search.py # 核心搜索逻辑 ├── faq_data.py # 模拟的FAQ数据 └── main.py # 主程序入口5.2 代码实现1. 模拟数据 (faq_data.py)# file: faq_data.py FAQ_DATABASE [ { id: 1, question: 如何重置Ollama的服务, answer: 在Linux上可以使用命令 sudo systemctl restart ollama在Windows上可以重启Ollama应用程序。 }, { id: 2, question: Ollama支持哪些Embedding模型, answer: Ollama支持多种模型如 bge-small-zh-v1.5, nomic-embed-text, all-minilm 等使用 ollama list 查看。 }, { id: 3, question: 如何解决Ollama拉取模型慢的问题, answer: 可以尝试配置国内镜像源例如通过设置环境变量或使用第三方镜像站地址。 }, { id: 4, question: Python中如何调用Ollama的聊天API, answer: 可以使用requests库向 http://localhost:11434/api/generate 发送POST请求或使用OpenAI兼容的SDK。 }, { id: 5, question: Embedding向量的维度是多少, answer: 维度取决于模型例如 bge-small-zh-v1.5 输出768维向量nomic-embed-text 输出768维all-minilm 输出384维。 } ]2. 嵌入向量封装 (embeddings.py)# file: embeddings.py import requests import json import numpy as np from typing import List, Optional class OllamaEmbedder: def __init__(self, base_url: str http://localhost:11434, model: str bge-small-zh-v1.5): self.base_url base_url self.model model self.embedding_url f{base_url}/api/embeddings def get_embedding(self, text: str) - Optional[List[float]]: 获取单个文本的嵌入向量 payload {model: self.model, prompt: text} try: response requests.post(self.embedding_url, jsonpayload, timeout30) response.raise_for_status() return response.json().get(embedding) except Exception as e: print(f获取文本嵌入失败: {e}) return None def get_embeddings_batch(self, texts: List[str]) - List[Optional[List[float]]]: 批量获取嵌入向量注意Ollama API原生不支持批量这里循环调用 embeddings [] for text in texts: embeddings.append(self.get_embedding(text)) return embeddings staticmethod 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))3. 核心搜索逻辑 (search.py)# file: search.py from typing import List, Dict, Any import numpy as np from embeddings import OllamaEmbedder class SemanticSearchEngine: def __init__(self, embedder: OllamaEmbedder): self.embedder embedder self.corpus: List[Dict[str, Any]] [] # 存储原始数据 self.corpus_embeddings: np.ndarray None # 存储所有向量的矩阵 def build_index(self, data: List[Dict[str, Any]], text_field: str question): 构建搜索索引。 :param data: 数据列表每个元素是字典 :param text_field: 用于生成嵌入向量的字段名 self.corpus data texts [item[text_field] for item in data] print(正在为知识库生成嵌入向量请稍候...) embeddings_list self.embedder.get_embeddings_batch(texts) # 过滤掉失败的嵌入 valid_data [] valid_embeddings [] for item, emb in zip(data, embeddings_list): if emb is not None: valid_data.append(item) valid_embeddings.append(emb) self.corpus valid_data if valid_embeddings: self.corpus_embeddings np.array(valid_embeddings) print(f索引构建完成共处理 {len(self.corpus)} 条数据。) else: print(警告未能生成任何有效的嵌入向量索引为空。) self.corpus_embeddings np.array([]) def search(self, query: str, top_k: int 3) - List[Dict[str, Any]]: 语义搜索。 :param query: 查询字符串 :param top_k: 返回最相似的前K个结果 :return: 包含相似度和原始数据的字典列表 if self.corpus_embeddings.size 0: return [] # 获取查询语句的嵌入向量 query_embedding self.embedder.get_embedding(query) if query_embedding is None: return [] # 计算与知识库中所有向量的余弦相似度 query_vec np.array(query_embedding) # 使用矩阵运算提高效率 similarities np.dot(self.corpus_embeddings, query_vec) / ( np.linalg.norm(self.corpus_embeddings, axis1) * np.linalg.norm(query_vec) ) # 获取相似度最高的top_k个索引 top_indices np.argsort(similarities)[::-1][:top_k] # 组装结果 results [] for idx in top_indices: results.append({ score: float(similarities[idx]), data: self.corpus[idx] }) return results4. 主程序入口 (main.py)# file: main.py from faq_data import FAQ_DATABASE from embeddings import OllamaEmbedder from search import SemanticSearchEngine def main(): # 1. 初始化嵌入器 print(初始化Ollama嵌入客户端...) embedder OllamaEmbedder(modelbge-small-zh-v1.5) # 2. 初始化搜索引擎并构建索引 print(初始化语义搜索引擎...) search_engine SemanticSearchEngine(embedder) search_engine.build_index(FAQ_DATABASE, text_fieldquestion) # 3. 交互式搜索 print(\n 简易FAQ语义搜索系统 ) print(输入您的问题输入 quit 或 exit 退出) print(- * 40) while True: query input(\n您的问题: ).strip() if query.lower() in [quit, exit, q]: print(再见) break if not query: continue print(f正在搜索: {query}) results search_engine.search(query, top_k2) if not results: print(未找到相关结果。) continue print(f找到 {len(results)} 个相关结果) for i, res in enumerate(results, 1): data res[data] print(f\n{i}. [相似度: {res[score]:.3f}]) print(f 问题: {data[question]}) print(f 答案: {data[answer]}) print(- * 40) if __name__ __main__: main()5.3 运行演示确保Ollama服务正在运行ollama serve或服务已启动。在项目目录下运行python main.py。根据提示输入问题例如“我拉取模型很慢怎么办”。系统会返回与FAQ库中语义最相近的问题和答案。预期输出示例初始化Ollama嵌入客户端... 初始化语义搜索引擎... 正在为知识库生成嵌入向量请稍候... 索引构建完成共处理 5 条数据。 简易FAQ语义搜索系统 输入您的问题输入 quit 或 exit 退出 ---------------------------------------- 您的问题: 下载模型速度太慢了 正在搜索: 下载模型速度太慢了 找到 2 个相关结果 1. [相似度: 0.832] 问题: 如何解决Ollama拉取模型慢的问题 答案: 可以尝试配置国内镜像源例如通过设置环境变量或使用第三方镜像站地址。 2. [相似度: 0.215] 问题: Ollama支持哪些Embedding模型 答案: Ollama支持多种模型如 bge-small-zh-v1.5, nomic-embed-text, all-minilm 等使用 ollama list 查看。 ----------------------------------------6. 常见问题与排查思路在实际使用Ollama Embedding API的过程中你可能会遇到以下问题。这里提供一份排查清单。问题现象可能原因解决思路ConnectionError/ 无法连接到localhost:114341. Ollama服务未启动。2. 防火墙或端口冲突。3. 服务监听地址不是0.0.0.0。1. 运行ollama serve或检查服务状态。2. 检查端口11434是否被占用 (netstat -ano | findstr :11434)。3. 确保启动时OLLAMA_HOST0.0.0.0。ollama pull速度极慢或失败1. 网络连接问题。2. 国内访问国外源慢。1. 检查网络。2.配置国内镜像源见2.2节。3. 尝试更换网络环境或使用代理。error: pull model manifest: file do1. 网络中断导致下载不完整。2. 镜像源地址失效或模型名错误。1. 删除不完整的模型文件位于OLLAMA_MODELS目录重新拉取。2. 验证模型名拼写 (ollama list查看官方列表)。3. 更换镜像源或直接使用官方源重试。API返回404或Model not found1. 请求的模型名称错误。2. 模型未成功下载。1. 用ollama list确认本地已安装的模型名。2. 用ollama pull model-name重新拉取。向量相似度计算不合理如全为1或01. 向量未归一化直接点积计算余弦相似度有误。2. 模型不适合当前语言或领域。1. 确保使用余弦相似度公式并检查向量是否已归一化某些模型输出已归一化。2. 尝试更换更匹配的Embedding模型。listen tcp 0.0.0.0:11434: bind: address already in use端口11434被其他进程占用。1. 找出占用进程并停止sudo lsof -i :11434(Linux/macOS)。2. 终止该进程或修改Ollama监听端口通过环境变量OLLAMA_HOST0.0.0.0:11435。GPU未调用运行速度慢1. 未安装GPU版本或驱动。2. Ollama未检测到GPU或模型不支持GPU。1. 确保已安装CUDA和对应驱动。2. 运行ollama run model查看输出是否提示使用GPU。3. 某些轻量Embedding模型默认可能只用CPU。Python调用超时1. 模型首次加载需要时间。2. 文本过长或服务器负载高。1. 在请求中增加timeout参数如timeout60。2. 预热模型先发送一个短文本请求。3. 检查服务器资源使用情况。7. 最佳实践与工程建议将Ollama Embedding API用于生产环境或严肃项目时需要考虑以下几点7.1 性能优化批量处理Ollama的/api/embeddings端点原生不支持批量请求。对于需要处理大量文本的场景需要自己实现异步或并发请求例如使用asyncio或concurrent.futures但要注意控制并发数避免压垮本地服务。缓存机制对于不变的文本如知识库文档其Embedding向量也是不变的。务必在本地或数据库如Redis中缓存已计算的向量避免重复计算。在SemanticSearchEngine的build_index中可以将生成的向量保存到文件如.npy或.json下次直接加载。模型选择根据任务选择模型。bge-small-zh-v1.5适合中文nomic-embed-text支持长文本8192 tokensall-minilm速度更快、维度更低。在精度和速度之间做好权衡。服务化部署对于团队使用可以考虑将Ollama Embedding服务封装成独立的HTTP/gRPC服务并添加负载均衡、健康检查、监控和日志。7.2 错误处理与健壮性重试机制网络请求可能失败实现指数退避的重试逻辑。import time from tenacity import retry, stop_after_attempt, wait_exponential retry(stopstop_after_attempt(3), waitwait_exponential(multiplier1, min2, max10)) def get_embedding_with_retry(text): # ... 调用API的代码降级方案当Ollama服务不可用时应有降级策略例如使用本地缓存的向量或切换到一个更简单的文本匹配如TF-IDF。输入验证与清理对输入文本进行长度限制截断或分块避免因文本过长导致服务超时或内存溢出。清理不必要的特殊字符。7.3 生产环境部署资源隔离为Ollama服务分配独立的内存和CPU限制避免影响主机其他服务。可以使用Docker容器化部署。# 简单示例 Dockerfile FROM ollama/ollama:latest # 预拉取模型 RUN ollama pull bge-small-zh-v1.5 EXPOSE 11434 CMD [ollama, serve]监控与告警监控Ollama服务的进程状态、API响应时间、错误率。设置告警当服务宕机或响应缓慢时及时通知。版本管理记录所使用的Ollama版本和模型版本。模型更新可能改变向量空间导致之前存储的向量失效。建议将模型版本与向量数据版本绑定。7.4 安全考虑网络暴露默认OLLAMA_HOST0.0.0.0会使服务监听所有网络接口。在生产环境如果只需本地访问应设置为127.0.0.1。如果需对外提供务必配置防火墙规则限制访问IP或通过反向代理如Nginx添加认证。输入过滤虽然Embedding API相对安全但仍应对输入进行基本的过滤防止注入攻击或资源耗尽攻击。通过以上步骤你不仅能够成功接入Ollama Embedding API还能构建一个健壮、可用的本地语义搜索系统。这套方案将数据隐私、响应速度和开发成本控制在了极佳的水平是中小型项目或对数据安全有要求的场景的理想选择。接下来你可以尝试将其集成到你的知识库系统、智能客服或内容推荐引擎中解锁更多AI应用的可能性。如果在实践中遇到其他问题多关注社区讨论和官方文档更新开源工具的生态总是在快速演进中。