gte-base-zh Docker Compose部署：一键编排Xinference+gte-base-zh+WebUI服务栈

gte-base-zh Docker Compose部署一键编排Xinferencegte-base-zhWebUI服务栈1. 引言为什么需要一键部署文本嵌入服务如果你正在做智能客服、文档检索或者内容推荐系统肯定遇到过一个问题怎么让计算机真正“理解”文字的意思比如用户搜索“苹果手机”系统不仅要能返回“iPhone”最好还能把“Apple智能手机”也找出来。这背后依赖的技术就是文本嵌入。文本嵌入模型能把一段文字转换成计算机能理解的数字向量。两个意思相近的句子它们的向量在数学空间里也会靠得很近。今天要介绍的gte-base-zh就是阿里巴巴达摩院专门为中文优化的一个优秀嵌入模型。但模型好部署起来却可能让人头疼。你需要准备环境、下载模型、启动服务、配置接口……每一步都可能遇到坑。为了解决这个问题我为你准备了一个完整的 Docker Compose 方案。它能帮你把Xinference推理框架、gte-base-zh模型和一个直观的 WebUI 界面打包在一起真正做到一键启动开箱即用。读完这篇文章你将能理解gte-base-zh模型的核心价值和应用场景。通过 Docker Compose 一键拉起完整的服务栈。使用 WebUI 界面快速体验文本相似度计算。掌握通过 API 调用嵌入服务的方法。无论你是想快速体验模型效果还是需要为你的应用集成一个稳定的嵌入服务这套方案都能帮你省下大量时间和精力。2. 核心组件介绍gte-base-zh 与 Xinference在开始动手部署之前我们先花几分钟了解一下这套方案里的两个核心“零件”是干什么的这样你用起来会更得心应手。2.1 gte-base-zh你的中文文本“理解官”gte-base-zh是阿里巴巴达摩院基于 BERT 框架训练的中文文本嵌入模型。你可以把它想象成一个非常专业的“翻译官”但它不是把中文翻译成英文而是把任何一段中文文本“翻译”成一段有特定含义的数字序列也就是向量。这个模型厉害在哪里专门为中文优化它在海量的中文文本对比如问题和答案、标题和正文上训练过对中文的语义、词序、上下文理解得更深。用途广泛生成的向量可以用于很多下游任务。最常见的就是计算语义相似度——判断两段话意思是不是相近。除此之外还能用于信息检索让你的搜索系统更智能不仅能匹配关键词还能理解语义。文本重排序对搜索引擎初步返回的结果根据语义相关性进行二次精排。聚类分析把意思相近的文档自动归到一起。上手简单模型已经预训练好了你不需要自己从头训练直接调用就行省时省力。简单来说当你需要让程序“读懂”中文并比较其含义时gte-base-zh是一个可靠的选择。2.2 Xinference模型服务的“万能插座”模型本身是一个“大脑”但它需要在一个“身体”运行环境里才能工作。Xinference 就是这个“身体”更准确地说它是一个开源的模型推理和服务框架。它的作用类似于一个“万能插座”统一管理可以用它来启动、管理多种不同架构的AI模型不仅仅是BERT类。提供标准接口模型通过 Xinference 启动后会对外提供统一的 API比如 HTTP 接口。你的其他程序只需要调用这个 API而不需要关心模型内部复杂的运行细节。简化部署它帮你处理了模型加载、资源调度、请求并发等底层问题。在我们的方案里Xinference 负责把gte-base-zh这个“大脑”启动起来并让它准备好接收外部的文本处理请求。2.3 三者如何协同工作我们把这三个组件放在一起就构成了一个完整、易用的服务栈Docker Compose是“总指挥”负责把 Xinference服务框架、gte-base-zh模型和 WebUI操作界面这三个容器按正确顺序一键启动。Xinference是“引擎”它加载并运行 gte-base-zh 模型。gte-base-zh是“核心”实际执行文本到向量的转换。WebUI是“仪表盘”给你一个可视化界面来测试和体验模型功能。接下来我们就看看怎么让这个“总指挥”把一切都安排妥当。3. 实战部署使用 Docker Compose 一键启动理论说完了我们直接上手。这套部署方案的核心就是一个docker-compose.yml文件。你不需要手动安装Python、配置环境、下载模型只需要安装好 Docker 和 Docker Compose然后执行一条命令。3.1 准备工作确保你的系统已经安装了Docker建议使用较新版本。Docker Compose同样建议使用新版本。你可以在终端输入以下命令检查是否安装成功docker --version docker-compose --version如果都能正确显示版本号就可以继续了。3.2 编写 Docker Compose 配置文件在你的项目目录下比如~/gte-demo创建一个名为docker-compose.yml的文件并将以下内容复制进去version: 3.8 services: xinference: image: registry.cn-hangzhou.aliyuncs.com/modelscope-repo/modelscope:ubuntu20.04-py38-torch2.0.1-tf1.15.5-1.8.1 container_name: gte_xinference restart: unless-stopped ports: - 9997:9997 volumes: # 将模型目录挂载到容器内指定路径 - ./models/gte-base-zh:/usr/local/bin/AI-ModelScope/gte-base-zh # 挂载启动脚本 - ./scripts/launch_model_server.py:/usr/local/bin/launch_model_server.py # 挂载日志目录 - ./logs:/root/workspace command: sh -c # 启动 Xinference 服务后台运行并记录日志 echo 启动 Xinference 服务... xinference-local --host 0.0.0.0 --port 9997 /root/workspace/xinference.log 21 # 等待 Xinference 服务就绪 sleep 10 echo Xinference 服务已启动开始加载 gte-base-zh 模型... # 执行模型加载和注册脚本 python /usr/local/bin/launch_model_server.py /root/workspace/model_server.log 21 # 保持容器运行并打印日志以便观察 tail -f /root/workspace/xinference.log networks: - gte-network webui: image: nginx:alpine container_name: gte_webui restart: unless-stopped ports: - 8080:80 volumes: # 挂载我们准备好的WebUI静态页面 - ./webui:/usr/share/nginx/html depends_on: - xinference networks: - gte-network networks: gte-network: driver: bridge这个配置文件做了以下几件关键事定义了两个服务一个叫xinference模型服务一个叫webui网页界面。配置模型服务使用了一个包含 PyTorch、TensorFlow 等深度学习环境的官方镜像。将本地的gte-base-zh模型目录挂载到容器内的固定路径/usr/local/bin/AI-ModelScope/gte-base-zh。你需要提前将模型文件下载到./models/gte-base-zh目录下。将模型启动脚本挂载到容器内。容器启动后会自动执行命令先启动 Xinference 服务然后运行脚本加载gte-base-zh模型到 Xinference 中。将容器的 9997 端口映射到主机的 9997 端口这样你就能通过http://localhost:9997访问 Xinference 的 API。配置WebUI服务使用轻量的 Nginx 镜像来提供一个网页。将包含前端页面的./webui目录挂载到 Nginx 的网页根目录。将容器的 80 端口映射到主机的 8080 端口这样你就能通过http://localhost:8080访问操作界面。通过depends_on确保 WebUI 在 Xinference 服务启动之后再启动。创建了内部网络让两个容器在同一个网络内可以相互通信。3.3 准备模型、脚本和WebUI文件现在我们需要创建配置文件中提到的几个目录和文件。第一步下载模型你需要从 ModelScope 或阿里云官方渠道下载gte-base-zh模型文件。假设你下载后解压的模型目录名为gte-base-zh将其放置于项目根目录的models/文件夹下。 最终结构如下你的项目目录/ ├── docker-compose.yml ├── models/ │ └── gte-base-zh/ 这里存放所有模型文件如 config.json, pytorch_model.bin 等 ├── scripts/ │ └── launch_model_server.py └── webui/ ├── index.html └── ... (其他前端资源文件)第二步创建模型启动脚本在scripts/目录下创建launch_model_server.py文件内容如下。这个脚本负责调用 Xinference 的接口来注册并启动模型服务。#!/usr/bin/env python3 import time import requests import sys def register_model(): 向本地运行的Xinference服务注册并启动gte-base-zh模型。 xinference_base_url http://localhost:9997 model_uid gte-base-zh # 为模型指定一个唯一标识 # 1. 注册模型如果尚未注册 # 注意这里假设模型文件已经存在于容器内的 /usr/local/bin/AI-ModelScope/gte-base-zh 路径 # Xinference 会从这个路径加载模型 model_registration_payload { model_uid: model_uid, model_name: gte-base-zh, model_type: embedding, model_format: pytorch, model_size_in_billions: 0.11, # 根据模型实际情况填写 quantization: None, model_engine: TransformersEmbedding, model_hub: local, # 关键从本地路径加载 model_path: /usr/local/bin/AI-ModelScope/gte-base-zh, # 容器内的模型路径 } try: print(f正在向 {xinference_base_url} 注册模型 {model_uid}...) resp requests.post(f{xinference_base_url}/v1/models, jsonmodel_registration_payload) if resp.status_code 200: print(f模型 {model_uid} 注册成功。) elif resp.status_code 400 and already exists in resp.text: print(f模型 {model_uid} 已存在跳过注册。) else: print(f模型注册失败: {resp.status_code} - {resp.text}) sys.exit(1) except requests.exceptions.ConnectionError as e: print(f无法连接到Xinference服务请确保服务已启动。错误: {e}) sys.exit(1) # 2. 启动模型 print(f正在启动模型 {model_uid}...) start_resp requests.post(f{xinference_base_url}/v1/models/{model_uid}/start) if start_resp.status_code 200: print(f模型 {model_uid} 启动成功) # 获取模型信息确认状态 model_info requests.get(f{xinference_base_url}/v1/models/{model_uid}).json() print(f模型信息: {model_info}) else: print(f模型启动失败: {start_resp.status_code} - {start_resp.text}) sys.exit(1) if __name__ __main__: # 给Xinference服务一点启动时间 time.sleep(5) register_model()第三步准备WebUI文件在webui/目录下你需要放置前端页面。这里提供一个最简单的index.html示例它包含两个文本框和一个按钮用于演示文本相似度计算。你可以根据需求美化这个界面。!DOCTYPE html html langzh-CN head meta charsetUTF-8 meta nameviewport contentwidthdevice-width, initial-scale1.0 titleGTE-Base-ZH 文本相似度演示/title style body { font-family: sans-serif; margin: 40px; background-color: #f5f5f5; } .container { max-width: 800px; margin: auto; background: white; padding: 30px; border-radius: 10px; box-shadow: 0 2px 10px rgba(0,0,0,0.1); } h1 { color: #333; text-align: center; } .input-group { margin-bottom: 20px; } label { display: block; margin-bottom: 8px; font-weight: bold; color: #555; } textarea { width: 100%; height: 100px; padding: 10px; border: 1px solid #ccc; border-radius: 5px; font-size: 14px; box-sizing: border-box; } button { background-color: #007bff; color: white; padding: 12px 25px; border: none; border-radius: 5px; cursor: pointer; font-size: 16px; display: block; margin: 20px auto; } button:hover { background-color: #0056b3; } #result { margin-top: 25px; padding: 15px; background-color: #e9ecef; border-radius: 5px; white-space: pre-wrap; font-family: monospace; } .loading { display: none; text-align: center; color: #666; } /style /head body div classcontainer h1GTE-Base-ZH 文本相似度计算/h1 p输入两段中文文本计算它们之间的语义相似度余弦相似度。/p div classinput-group label fortext1文本一/label textarea idtext1 placeholder例如今天天气真好适合出去散步。今天天气真好适合出去散步。/textarea /div div classinput-group label fortext2文本二/label textarea idtext2 placeholder例如阳光明媚是个散步的好日子。阳光明媚是个散步的好日子。/textarea /div button onclickcalculateSimilarity()计算相似度/button div classloading idloading计算中.../div div idresult/div /div script async function calculateSimilarity() { const text1 document.getElementById(text1).value.trim(); const text2 document.getElementById(text2).value.trim(); const resultDiv document.getElementById(result); const loadingDiv document.getElementById(loading); if (!text1 || !text2) { resultDiv.innerHTML 请在两段文本框中都输入内容。; return; } // 显示加载中 resultDiv.innerHTML ; loadingDiv.style.display block; try { // 步骤1: 获取文本一的嵌入向量 const embedResp1 await fetch(http://localhost:9997/v1/embeddings, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify({ model: gte-base-zh, input: text1 }) }); const embedData1 await embedResp1.json(); if (!embedResp1.ok) throw new Error(获取文本一向量失败: ${JSON.stringify(embedData1)}); const vector1 embedData1.data[0].embedding; // 步骤2: 获取文本二的嵌入向量 const embedResp2 await fetch(http://localhost:9997/v1/embeddings, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify({ model: gte-base-zh, input: text2 }) }); const embedData2 await embedResp2.json(); if (!embedResp2.ok) throw new Error(获取文本二向量失败: ${JSON.stringify(embedData2)}); const vector2 embedData2.data[0].embedding; // 步骤3: 计算余弦相似度 (前端简易计算) const similarity cosineSimilarity(vector1, vector2); // 显示结果 resultDiv.innerHTML strong文本一/strong ${text1}\n strong文本二/strong ${text2}\n strong语义相似度余弦相似度/strong ${similarity.toFixed(4)}\n small值越接近1表示语义越相似越接近0表示越不相关。/small ; } catch (error) { console.error(Error:, error); resultDiv.innerHTML strong请求出错/strong ${error.message}\n请确保Xinference服务端口9997已正常运行。; } finally { loadingDiv.style.display none; } } // 计算两个向量的余弦相似度 function cosineSimilarity(vecA, vecB) { let dotProduct 0; let normA 0; let normB 0; for (let i 0; i vecA.length; i) { dotProduct vecA[i] * vecB[i]; normA vecA[i] * vecA[i]; normB vecB[i] * vecB[i]; } if (normA 0 || normB 0) return 0; return dotProduct / (Math.sqrt(normA) * Math.sqrt(normB)); } /script /body /html3.4 启动服务栈所有文件准备就绪后在包含docker-compose.yml文件的目录下打开终端执行一条命令docker-compose up -d-d参数表示在后台运行。你会看到 Docker 开始拉取镜像、创建容器、启动服务。第一次运行可能会花费一些时间因为它需要下载基础镜像。启动完成后你可以用以下命令查看服务状态docker-compose ps应该能看到两个容器gte_xinference和gte_webui的状态都是Up。3.5 验证服务服务启动后我们可以从几个方面验证是否成功。1. 检查模型服务日志模型加载可能需要几分钟取决于模型大小和服务器性能。你可以查看模型加载的日志# 查看容器日志 docker logs gte_xinference # 或者直接查看挂载出来的日志文件 cat logs/model_server.log当你看到日志中包含 “模型 gte-base-zh 启动成功” 或类似信息时说明模型已就绪。2. 测试 Xinference API模型启动后Xinference 会提供标准的 OpenAI 兼容 API。你可以用curl命令测试curl http://localhost:9997/v1/models如果返回一个 JSON其中包含gte-base-zh模型的信息说明 API 服务正常。3. 访问 WebUI 界面打开你的浏览器访问http://localhost:8080。 你应该能看到我们刚刚创建的简单界面。在两个文本框里输入一些中文句子点击“计算相似度”按钮。如果一切正常页面会显示一个介于 0 到 1 之间的相似度分数。例如输入“今天天气真好”和“阳光明媚”可能会得到 0.85 左右的高分。输入“今天天气真好”和“我喜欢编程”可能会得到 0.1 左右的低分。至此你的本地gte-base-zh文本嵌入服务栈就已经成功运行起来了4. 如何使用从 WebUI 到 API 调用部署成功只是第一步更重要的是怎么用它。我们分别从可视化操作和编程集成两个角度来看。4.1 通过 WebUI 快速体验我们提供的 WebUI 界面是最简单的测试方式。它的工作原理是你在前端输入两段文本。前端 JavaScript 分别调用http://localhost:9997/v1/embeddings接口获取两段文本的向量。前端计算这两个向量的余弦相似度并展示。这个界面非常适合快速验证部署后立即检查模型是否工作正常。效果演示向同事或客户直观展示文本嵌入和相似度计算的能力。简单测试手动输入一些句子对观察模型的语义理解能力。4.2 通过 API 集成到你的应用对于真正的项目集成你需要通过 API 来调用服务。Xinference 提供了与 OpenAI Embeddings API 兼容的接口使用起来非常简单。获取文本向量向/v1/embeddings发送 POST 请求。curl -X POST http://localhost:9997/v1/embeddings \ -H Content-Type: application/json \ -d { model: gte-base-zh, input: 阿里巴巴是一家中国科技公司 }返回的 JSON 中data[0].embedding就是一个长达 768 维具体维度取决于模型的浮点数数组这就是文本的向量表示。计算相似度服务端示例获取到两个文本的向量后你需要在你的应用程序中计算它们的相似度。以下是一个 Python 示例import requests import numpy as np def get_embedding(text, model_uidgte-base-zh, base_urlhttp://localhost:9997): 获取单段文本的嵌入向量 resp requests.post( f{base_url}/v1/embeddings, json{model: model_uid, input: text} ) resp.raise_for_status() return np.array(resp.json()[data][0][embedding]) def cosine_similarity(vec_a, vec_b): 计算两个向量的余弦相似度 dot_product np.dot(vec_a, vec_b) norm_a np.linalg.norm(vec_a) norm_b np.linalg.norm(vec_b) if norm_a 0 or norm_b 0: return 0.0 return dot_product / (norm_a * norm_b) # 使用示例 text1 今天天气晴朗 text2 阳光明媚的好天气 vec1 get_embedding(text1) vec2 get_embedding(text2) similarity cosine_similarity(vec1, vec2) print(f文本1: {text1}) print(f文本2: {text2}) print(f语义相似度: {similarity:.4f})API 的主要应用场景构建搜索引擎将文档库中的所有文档转换为向量并存入向量数据库如 Milvus, Qdrant。用户查询时将查询语句也转换为向量然后在向量数据库中快速查找最相似的文档。智能客服问答将标准问答对转换为向量。当用户提问时计算问题与知识库中所有问题的相似度返回最相似问题的答案。内容去重与聚类计算文章之间的相似度用于识别重复内容或将相似文章自动归类。推荐系统用向量表示用户兴趣和物品特征通过向量相似度进行匹配推荐。5. 总结通过本文的 Docker Compose 方案我们成功地将gte-base-zh中文嵌入模型、Xinference推理框架和一个简易的WebUI打包成了一个可一键部署的服务栈。回顾一下我们主要完成了三件事理解了核心价值gte-base-zh是一个强大的中文语义理解模型能将文本转换为富含语义信息的向量是构建智能检索、问答、推荐等系统的基石。实现了便捷部署利用 Docker Compose我们通过一个配置文件就定义了完整的服务依赖和启动流程避免了繁琐的手动环境配置。模型、服务、界面三者分离架构清晰。掌握了使用方法既可以通过直观的 Web 界面快速体验和测试也可以通过标准的 HTTP API 轻松集成到任何后端应用程序中为你的项目注入“理解”中文文本的能力。这套方案的优点在于其开箱即用和易于扩展。如果你需要部署其他 Xinference 支持的模型或者定制更复杂的 WebUI只需要修改对应的 Docker Compose 配置和前端文件即可。下一步你可以尝试将向量存储到专业的向量数据库如 Milvus中构建大规模的语义检索系统。利用嵌入向量实现更复杂的 NLP 任务比如文本分类、情感分析作为特征输入。探索gte-base-zh模型的其他参数和配置以优化特定场景下的效果。希望这个一键部署方案能帮助你快速开启中文文本语义处理的大门将先进的 AI 能力轻松整合到你的产品与项目中。获取更多AI镜像想探索更多AI镜像和应用场景访问 CSDN星图镜像广场提供丰富的预置镜像覆盖大模型推理、图像生成、视频生成、模型微调等多个领域支持一键部署。