all-MiniLM-L6-v2部署教程Ollama中启用HTTP API并对接FastAPI后端服务想快速搭建一个属于自己的文本语义理解服务吗今天我们来聊聊如何用Ollama部署轻量级嵌入模型all-MiniLM-L6-v2并让它通过HTTP API与你的FastAPI后端服务“握手”合作。整个过程就像搭积木一样简单即使你之前没怎么接触过模型部署也能跟着一步步搞定。all-MiniLM-L6-v2是个“小而美”的模型。它专门负责把一段文字比如一句话或一个段落转换成计算机能理解的数字向量。这个向量就像是这段文字的“数字指纹”包含了它的核心语义。有了这个指纹计算机就能轻松判断两段文字是不是在说同一件事或者帮你从海量文档里找到最相关的内容。它最大的优点就是快和省资源特别适合咱们自己动手搭建服务。1. 环境准备与Ollama部署在开始之前我们需要准备好运行环境。整个过程可以概括为三步安装Ollama、拉取模型、启动服务。1.1 安装OllamaOllama是一个强大的工具它能让你像管理软件包一样轻松管理各种大语言模型和嵌入模型。首先访问Ollama的官方网站根据你的操作系统Windows、macOS或Linux下载对应的安装程序。对于Linux或macOS用户通常也可以通过一行命令来安装curl -fsSL https://ollama.ai/install.sh | sh安装完成后在终端输入ollama --version如果能看到版本号说明安装成功。1.2 拉取all-MiniLM-L6-v2模型Ollama安装好后获取模型就变得异常简单。all-MiniLM-L6-v2模型已经收录在Ollama的官方库中。我们只需要打开终端执行一条命令ollama pull all-minilm:l6-v2这条命令会从Ollama的服务器下载模型文件。由于all-MiniLM-L6-v2模型非常轻量只有约22.7MB下载过程会很快。完成后你可以用ollama list命令查看本地已安装的模型确认all-minilm:l6-v2在列表中。1.3 启动模型服务并启用HTTP API默认情况下Ollama运行的服务只监听本地localhost。为了让我们的FastAPI后端能访问它需要以特定的方式启动。在终端中运行以下命令ollama serve这个命令会启动Ollama服务。但默认配置下它只允许本机访问。为了启用对外的HTTP API我们需要修改启动方式或配置。更常见的做法是直接运行模型并指定主机和端口使其对外提供服务OLLAMA_HOST0.0.0.0 ollama run all-minilm:l6-v2或者你可以先设置环境变量再启动服务export OLLAMA_HOST0.0.0.0 ollama run all-minilm:l6-v2关键点在于OLLAMA_HOST0.0.0.0这告诉Ollama监听所有网络接口而不仅仅是本地回环地址。这样同一网络内的其他服务比如你的FastAPI后端就能通过IP地址访问到它了。服务启动后默认会在11434端口监听。你可以在浏览器中访问http://你的服务器IP:11434如果看到Ollama的API文档页面或类似响应说明HTTP API已经成功启用。2. 理解Ollama的Embedding API在对接之前我们先花两分钟了解一下我们要打交道的API长什么样。这能让你后面写代码时心里更有底。Ollama为模型提供了一个统一的HTTP API接口。对于嵌入模型我们主要使用其中的/api/embed端点。这个接口接收一段文本返回它的向量表示。一个最简单的调用示例是这样的使用curl命令curl http://localhost:11434/api/embed -d { model: all-minilm:l6-v2, prompt: 这是一个测试句子。 }它会返回一个JSON格式的响应核心内容就是一个浮点数数组也就是我们想要的“文本指纹”向量。{ embedding: [0.123, -0.456, 0.789, ...] // 一个长度为384的数组 }这里有几个关键参数你需要知道model: 指定使用哪个模型这里固定是all-minilm:l6-v2。prompt: 需要被转换成向量的文本内容。all-MiniLM-L6-v2模型最大支持256个token对于中文大约相当于120-150个汉字超出部分会被截断。了解这个接口的请求和响应格式后我们就能用代码来调用它了。3. 构建FastAPI后端服务现在我们来搭建一个简单的FastAPI应用它作为中间层接收用户的请求然后去调用Ollama的API获取向量最后把结果返回给用户。3.1 创建项目与安装依赖首先创建一个新的项目目录并建立一个Python虚拟环境这能避免包版本冲突mkdir embedding_service cd embedding_service python -m venv venv # 激活虚拟环境 # Windows: venv\Scripts\activate # macOS/Linux: source venv/bin/activate激活虚拟环境后安装必要的Python包。我们主要需要fastapi来创建Web服务以及httpx或requests来发送HTTP请求调用Ollama。这里使用httpx因为它对异步支持更好。pip install fastapi httpx uvicorn3.2 编写核心服务代码在项目根目录下创建一个名为main.py的文件我们将在这里编写所有代码。首先导入必要的模块并初始化FastAPI应用from fastapi import FastAPI, HTTPException from pydantic import BaseModel import httpx from typing import List app FastAPI(title文本嵌入向量服务, description基于Ollama all-MiniLM-L6-v2模型) # 定义Ollama API的地址根据你的实际部署IP修改 OLLAMA_API_URL http://localhost:11434/api/embed接下来我们定义数据模型。使用Pydantic的BaseModel可以自动处理请求数据的验证。class EmbeddingRequest(BaseModel): text: str # 用户输入的文本 model: str all-minilm:l6-v2 # 默认模型也可允许用户指定 class EmbeddingResponse(BaseModel): embedding: List[float] # 返回的向量列表 model: str text_length: int然后编写最核心的API端点。这个端点接收用户提交的文本将其转发给Ollama服务并将得到的向量返回。app.post(/embed, response_modelEmbeddingResponse, summary获取文本的嵌入向量) async def get_embedding(request: EmbeddingRequest): 接收一段文本调用Ollama中的all-MiniLM-L6-v2模型返回其语义嵌入向量。 # 准备请求Ollama的数据 ollama_payload { model: request.model, prompt: request.text } async with httpx.AsyncClient(timeout30.0) as client: try: # 向Ollama服务发送POST请求 response await client.post(OLLAMA_API_URL, jsonollama_payload) response.raise_for_status() # 如果请求失败4xx或5xx抛出异常 result response.json() # 构建返回给用户的数据 return EmbeddingResponse( embeddingresult[embedding], modelrequest.model, text_lengthlen(request.text) ) except httpx.RequestError as e: # 处理网络连接错误 raise HTTPException(status_code503, detailf无法连接到Ollama服务: {str(e)}) except httpx.HTTPStatusError as e: # 处理Ollama返回的错误状态码 raise HTTPException(status_codee.response.status_code, detailfOllama服务错误: {e.response.text}) except KeyError: # 处理响应格式不符合预期的情况 raise HTTPException(status_code500, detailOllama服务返回了意外的响应格式。)这段代码做了几件事定义了一个/embed的POST接口。使用httpx.AsyncClient异步地调用Ollama的API这样不会阻塞服务处理其他请求。添加了完善的错误处理包括网络问题、Ollama服务错误等并返回友好的错误信息。最后我们可以再添加一个简单的根路径访问点用于健康检查。app.get(/) async def root(): return {message: 文本嵌入向量服务正在运行。请访问 /docs 查看API文档。}3.3 运行与测试服务代码写好了让我们来启动它。在终端中确保你在项目目录下并且虚拟环境已激活然后运行uvicorn main:app --reload --host 0.0.0.0 --port 8000main:app指定了模块名和FastAPI应用实例。--reload参数使得在代码修改后服务器会自动重启方便开发。--host 0.0.0.0让服务对外可访问。--port 8000指定服务运行在8000端口。服务启动后你可以做两件事来测试访问自动API文档打开浏览器访问http://你的服务器IP:8000/docs。你会看到Swagger UI生成的交互式文档可以直接在页面上尝试调用/embed接口。使用命令行工具测试打开另一个终端用curl命令测试curl -X POST http://localhost:8000/embed \ -H Content-Type: application/json \ -d {text: 今天天气真好适合去公园散步。}你应该会收到一个包含384维向量的JSON响应。4. 进阶使用与对接示例基础服务跑通了我们来看看它能怎么用以及如何集成到更复杂的场景里。4.1 实现文本相似度计算嵌入向量最常见的用途就是计算文本相似度。我们可以在FastAPI服务里新增一个接口专门处理这个需求。在main.py中新增一个数据模型和接口class SimilarityRequest(BaseModel): text1: str text2: str model: str all-minilm:l6-v2 class SimilarityResponse(BaseModel): similarity: float model: str app.post(/similarity, response_modelSimilarityResponse, summary计算两段文本的语义相似度) async def calculate_similarity(request: SimilarityRequest): 计算两段文本的余弦相似度。 # 分别获取两段文本的向量 async with httpx.AsyncClient() as client: # 获取第一段文本的向量 resp1 await client.post(OLLAMA_API_URL, json{model: request.model, prompt: request.text1}) vec1 resp1.json()[embedding] # 获取第二段文本的向量 resp2 await client.post(OLLAMA_API_URL, json{model: request.model, prompt: request.text2}) vec2 resp2.json()[embedding] # 计算余弦相似度 import numpy as np v1 np.array(vec1) v2 np.array(vec2) cosine_sim np.dot(v1, v2) / (np.linalg.norm(v1) * np.linalg.norm(v2)) return SimilarityResponse(similarityfloat(cosine_sim), modelrequest.model)这个接口接收两段文本分别获取它们的向量然后使用余弦相似度公式计算它们之间的相似度得分范围在-1到1之间越接近1表示越相似。4.2 集成到现有应用假设你有一个简单的文档管理系统现在想增加一个“查找相似文档”的功能。你可以这样利用我们刚搭建的服务在你的文档管理应用代码中例如另一个Python脚本import httpx import json async def find_similar_documents(query_text, document_list): 根据查询文本从文档列表中找出最相似的几个文档。 # 1. 获取查询文本的向量 async with httpx.AsyncClient() as client: query_resp await client.post(http://你的FastAPI服务地址:8000/embed, json{text: query_text}) query_vector query_resp.json()[embedding] similarities [] # 2. 为每个文档获取向量并计算相似度这里简化实际可批量处理 for doc in document_list: doc_resp await client.post(http://你的FastAPI服务地址:8000/embed, json{text: doc[content]}) doc_vector doc_resp.json()[embedding] # 计算余弦相似度这里需要numpy仅示意逻辑 # ... 计算相似度 ... # sim calculate_cosine_similarity(query_vector, doc_vector) # similarities.append((doc[id], sim)) # 3. 按相似度排序并返回Top N结果 # similarities.sort(keylambda x: x[1], reverseTrue) # return similarities[:5] return [] # 返回示例通过这种方式你就将强大的语义理解能力以服务的形式轻松集成到了自己的应用中而无需关心模型加载、推理等底层细节。5. 总结回顾一下我们今天完成了几件有意思的事部署了轻量级模型利用Ollama我们几乎零配置地拉取并运行了all-MiniLM-L6-v2嵌入模型并通过设置使其提供对外的HTTP API。搭建了代理服务我们创建了一个FastAPI后端它充当了一个友好、易用的中间层。你的应用只需要和这个FastAPI服务对话它负责去和Ollama“沟通”所有复杂的事情。扩展了应用场景我们不仅提供了基础的向量生成接口还示范了如何在此基础上构建更实用的功能比如文本相似度计算并探讨了如何将其集成到现有系统中。这种架构的好处非常明显解耦和易维护。模型服务Ollama和业务逻辑服务FastAPI是分开的。你可以独立升级模型版本或者扩展FastAPI的功能而不会影响到对方。对于想要快速验证想法、构建AI功能原型的朋友来说这是一条非常高效的路径。下一步你可以考虑为FastAPI服务增加更多功能比如批量处理文本、支持更多模型、添加缓存机制来提升性能或者用Docker把整个环境打包实现一键部署。希望这个教程能帮你顺利迈出构建AI应用服务的第一步。获取更多AI镜像想探索更多AI镜像和应用场景访问 CSDN星图镜像广场提供丰富的预置镜像覆盖大模型推理、图像生成、视频生成、模型微调等多个领域支持一键部署。