gte-base-zh保姆级教程从启动到调用小白也能玩转文本嵌入1. 引言让机器读懂你的文字你有没有想过怎么让电脑理解“苹果”这个词指的是水果公司还是可以吃的水果或者怎么让一个系统知道“我喜欢编程”和“我对写代码充满热情”说的其实是同一件事这就是文本嵌入要解决的问题。简单说它能把一段文字变成一串有意义的数字也叫向量意思相近的文字它们的数字串也会很接近。有了这个能力机器就能做很多聪明事比如帮你从海量文章里精准找到想要的内容或者把相似的评论自动归类。今天我们要玩的gte-base-zh就是干这个的专家。它由阿里巴巴达摩院打造专门为中文优化理解力相当不错。最棒的是现在你不用折腾复杂的安装配置通过CSDN星图镜像几分钟就能把它跑起来。这篇文章我会手把手带你走一遍全过程从启动服务、测试模型到写代码调用它。就算你之前没接触过这类技术跟着做也能搞定。2. 准备工作认识你的工具箱在开始动手前我们先花两分钟了解一下你要用到的“工具箱”里都有什么。这样后面操作起来你心里更有底。这个gte-base-zh镜像已经为你准备好了所有东西模型本体就是gte-base-zh这个“大脑”本身它已经躺在镜像的/usr/local/bin/AI-ModelScope/gte-base-zh路径下了。模型服务启动器一个Python脚本 (/usr/local/bin/launch_model_server.py)。它的作用是把上面那个“大脑”启动起来变成一个可以通过网络访问的API服务。你不用管脚本里面具体怎么写会用就行。推理服务框架 (Xinference)你可以把它想象成一个“服务托管平台”。我们通过运行xinference-local命令启动它它会在后台运行管理我们启动的模型服务。Web操作界面一个可以通过浏览器访问的图形化界面。在这里你可以点点按钮就能测试模型效果非常直观不用写代码。它们之间的关系我用一个简单的图帮你理清你通过浏览器访问 ↓ [ Xinference Web界面 ] ↓ (发送测试请求) [Xinference 服务框架] (运行在9997端口) ↓ (调用模型API) [ gte-base-zh 模型服务 ] (由启动脚本激活) ↓ (核心计算) [ gte-base-zh 模型文件 ]整个过程就是你通过Web界面或自己的代码发出请求 → Xinference服务接收到请求 → 它去调用已经启动好的gte-base-zh模型服务 → 模型进行计算并返回结果。了解这些之后我们开始第一步把服务跑起来。3. 第一步启动模型服务现在我们来启动核心的模型服务。因为模型文件比较大第一次启动需要一点时间加载请耐心等待。3.1 启动Xinference服务框架首先我们需要让Xinference这个“服务托管平台”在后台运行起来。它会监听一个端口比如9997等待我们的指令。打开你的终端或命令行工具输入以下命令xinference-local --host 0.0.0.0 --port 9997命令解释xinference-local启动本地Xinference服务。--host 0.0.0.0让服务可以被同一网络下的其他设备访问如果只在本机测试用127.0.0.1也行。--port 9997指定服务运行的端口号是9997。执行后你会看到一些启动日志输出。只要没有报错退出就说明服务已经在后台运行了。你可以让它保持运行然后新开一个终端窗口进行下一步。3.2 启动gte-base-zh模型服务接下来我们要在这个“平台”上把gte-base-zh模型服务启动起来。镜像已经提供了一个现成的脚本。在新打开的终端窗口中运行python /usr/local/bin/launch_model_server.py运行这个脚本后它会做几件事找到本地的gte-base-zh模型文件。通过Xinference的接口将模型注册并启动为一个服务。这个服务会提供一个API端点专门用于处理文本嵌入的请求。第一次运行提示 由于是首次加载模型需要从磁盘读取庞大的模型参数到内存中这个过程可能需要一两分钟。期间终端可能会“卡住”或持续输出加载信息这是正常的请耐心等待直到出现成功的提示或脚本执行完毕。3.3 验证服务是否启动成功怎么知道模型服务启动好了呢最直接的方法是查看日志。在终端中运行cat /root/workspace/model_server.log如果看到日志中包含模型加载完成、服务启动成功的字样例如显示模型名称、可用设备等信息就说明一切就绪。如果日志显示还在加载就再等一会儿。如果看到明显的错误信息请检查前两步的命令是否有误或者模型文件路径是否正确。好了服务已经在后台默默运行了。现在让我们通过一个更友好的方式去“看看”它。4. 第二步通过Web界面快速体验这是最简单直观的一步不需要写任何代码就能感受gte-base-zh的能力。4.1 访问Web操作界面首先确保你的Xinference服务xinference-local命令还在运行。然后打开你的浏览器在地址栏输入http://你的服务器IP地址:9997注意将“你的服务器IP地址”替换为实际地址。如果你就在运行服务的本机上操作可以输入http://127.0.0.1:9997或http://localhost:9997。回车后你应该能看到Xinference的Web管理界面。4.2 找到并测试gte-base-zh模型在Web界面中你应该能看到一个名为“gte-base-zh”的模型卡片。点击它通常会进入一个模型详情或测试页面。在这个测试页面你会看到类似这样的功能示例文本系统可能预置了一些句子对比如“今天天气真好”和“阳光明媚的一天”。输入框允许你自己输入两段文本。“相似度比对”或“计算”按钮点击它让模型开始工作。我们来试一下在第一个输入框输入“我喜欢吃苹果”。在第二个输入框输入“苹果是一种水果”。点击“相似度比对”按钮。稍等片刻页面会显示一个相似度分数比如0.65。这个分数介于0到1之间越接近1表示两句话意思越相似。试试其他例子“我喜欢编程” vs “我对写代码充满热情”分数应该较高例如0.8“猫在沙发上睡觉” vs “今天股市大涨”分数应该很低例如0.1-通过这个界面你可以随意测试直观地感受模型对语义的理解能力。玩够了之后我们进入更强大的环节用代码调用它。5. 第三步通过代码调用API通过Web界面点点按钮很方便但真正要把gte-base-zh用到你自己的项目里还是得通过代码来调用它的API。别担心我带你一步步来。5.1 理解API接口首先我们需要知道怎么跟这个模型服务“说话”。gte-base-zh模型服务启动后会提供一个标准的HTTP API接口。核心信息如下这些通常在模型服务启动日志或Xinference界面中可以找到以下为常见格式API地址 (Base URL)http://127.0.0.1:9997/v1假设Xinference运行在本机9997端口模型名称gte-base-zh嵌入接口路径/embeddings我们向这个接口发送一个POST请求里面包含我们想要转换的文本它就会返回对应的“数字指纹”向量。5.2 使用Python调用推荐Python是最常用的方式。你需要先安装requests库如果还没安装在终端里运行pip install requests。下面是一个完整的Python脚本示例import requests import json # 1. 定义API地址和模型信息 API_BASE http://127.0.0.1:9997/v1 # 根据你的实际地址修改 MODEL_NAME gte-base-zh EMBEDDING_URL f{API_BASE}/embeddings # 2. 准备请求数据我们想让模型为这两句话生成嵌入向量 texts_to_embed [我喜欢吃苹果, 苹果是一种水果] payload { model: MODEL_NAME, input: texts_to_embed } # 3. 设置请求头告诉服务器我们发送的是JSON格式数据 headers { Content-Type: application/json } # 4. 发送POST请求 try: response requests.post(EMBEDDING_URL, jsonpayload, headersheaders) response.raise_for_status() # 如果请求失败如4xx, 5xx错误抛出异常 # 5. 解析返回的JSON数据 result response.json() print(API调用成功) print(f返回的数据类型: {type(result)}) # 6. 提取嵌入向量 # 返回数据通常是一个列表里面每个元素对应一个输入文本的嵌入信息 if data in result: for i, embedding_info in enumerate(result[data]): # embedding_info[embedding] 就是我们要的向量一长串数字 vector embedding_info[embedding] print(f\n文本 {texts_to_embed[i]} 的嵌入向量) print(f 向量长度: {len(vector)}) print(f 向量前10个值预览: {vector[:10]}) # 只打印前10个值看看 except requests.exceptions.RequestException as e: print(f请求出错: {e}) except json.JSONDecodeError as e: print(f解析返回的JSON数据出错: {e}) except KeyError as e: print(f返回的数据结构可能和预期不符缺少键: {e}) print(f完整的返回内容: {response.text})运行这个脚本将上面的代码保存为一个文件比如test_embedding.py。在终端中切换到该文件所在目录。运行python test_embedding.py。如果一切正常你会看到输出显示两段文本对应的向量长度通常是768维以及向量的前几个数字。5.3 计算文本相似度拿到向量后怎么计算相似度呢最常用的方法是计算余弦相似度。两个向量的方向越接近余弦值越接近1表示语义越相似。我们可以用numpy库轻松计算。先安装pip install numpy。接着上面的代码我们添加相似度计算import numpy as np # ... (前面的代码成功获取到两个向量 vector_a 和 vector_b) ... # 假设我们从上面的结果中拿到了两个向量 # 为了演示这里我们模拟两个简单的向量实际中请替换为API返回的真实向量 # vector_a result[data][0][embedding] # vector_b result[data][1][embedding] # 示例模拟两个3维向量实际是768维 vector_a np.array([0.1, 0.2, 0.3]) vector_b np.array([0.15, 0.25, 0.35]) # 计算余弦相似度 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) return dot_product / (norm_a * norm_b) similarity cosine_similarity(vector_a, vector_b) print(f\n文本A与文本B的余弦相似度为: {similarity:.4f})将API返回的真实向量替换掉示例向量你就能计算出任意两段文本的语义相似度分数了。这个分数和你在Web界面看到的是一个原理。6. 第四步动手实践构建一个简易语义搜索器光看例子不过瘾我们来做个小项目用一个简单的列表模拟文档库实现输入一个问题找出库中最相关的文档。6.1 项目准备假设我们有一个关于水果的简易“知识库”documents [ 苹果是一种常见的水果富含维生素和纤维。, 香蕉是一种热带水果口感软糯富含钾元素。, 计算机编程是编写指令让计算机执行任务的过程。, 橙子酸甜多汁维生素C含量很高。, 学习机器学习需要掌握数学和编程基础。 ]我们的目标是当用户输入“有什么好吃又健康的水果”时程序能返回最相关的文档比如关于苹果、香蕉、橙子的描述。6.2 代码实现我们将分几步走为知识库中的所有文档预先计算好嵌入向量并存储起来这个过程叫“索引”。当用户输入查询语句时计算它的嵌入向量。将查询向量与所有文档向量计算余弦相似度。按相似度从高到低排序返回最相关的文档。import requests import json import numpy as np from typing import List, Tuple # 配置API和前面一样 API_BASE http://127.0.0.1:9997/v1 MODEL_NAME gte-base-zh EMBEDDING_URL f{API_BASE}/embeddings headers {Content-Type: application/json} def get_embedding(text: str) - List[float]: 获取单段文本的嵌入向量 payload {model: MODEL_NAME, input: [text]} try: response requests.post(EMBEDDING_URL, jsonpayload, headersheaders) response.raise_for_status() result response.json() return result[data][0][embedding] except Exception as e: print(f获取文本嵌入失败: {e}) return None def get_embeddings_batch(texts: List[str]) - List[List[float]]: 批量获取多段文本的嵌入向量更高效 payload {model: MODEL_NAME, input: texts} try: response requests.post(EMBEDDING_URL, jsonpayload, headersheaders) response.raise_for_status() result response.json() return [item[embedding] for item in result[data]] except Exception as e: print(f批量获取文本嵌入失败: {e}) return [] def cosine_similarity(vec_a: List[float], vec_b: List[float]) - float: 计算两个向量的余弦相似度 a np.array(vec_a) b np.array(vec_b) dot_product np.dot(a, b) norm_a np.linalg.norm(a) norm_b np.linalg.norm(b) if norm_a 0 or norm_b 0: return 0.0 return dot_product / (norm_a * norm_b) # 1. 定义我们的简易知识库 documents [ 苹果是一种常见的水果富含维生素和纤维。, 香蕉是一种热带水果口感软糯富含钾元素。, 计算机编程是编写指令让计算机执行任务的过程。, 橙子酸甜多汁维生素C含量很高。, 学习机器学习需要掌握数学和编程基础。 ] print(正在为知识库文档生成嵌入向量...) # 批量获取所有文档的向量 document_vectors get_embeddings_batch(documents) if not document_vectors: print(文档向量生成失败退出。) exit() print(f成功为 {len(document_vectors)} 个文档生成向量。) # 2. 用户输入查询 query input(\n请输入你的问题例如有什么好吃又健康的水果: ) print(f\n你的问题是: {query}) print(正在搜索最相关的文档...\n) # 3. 获取查询语句的向量 query_vector get_embedding(query) if query_vector is None: print(无法获取查询语句的向量退出。) exit() # 4. 计算查询与每个文档的相似度 results [] for i, doc_vec in enumerate(document_vectors): similarity cosine_similarity(query_vector, doc_vec) results.append((similarity, documents[i], i)) # 5. 按相似度降序排序 results.sort(keylambda x: x[0], reverseTrue) # 6. 输出结果 print(搜索结果按相关性排序:) print(- * 50) for rank, (score, doc, idx) in enumerate(results[:3], start1): # 显示前3个 print(f第{rank}名 [相似度: {score:.4f}]) print(f文档{idx1}: {doc}) print(- * 50)6.3 运行与思考将上面的代码保存为semantic_search.py并运行。尝试输入不同的查询比如“有什么好吃又健康的水果”应该匹配苹果、香蕉、橙子“编程难学吗”应该匹配计算机编程和机器学习“补充维生素吃什么”应该匹配苹果、橙子观察结果你会发现即使你的查询语句和文档没有相同的字眼比如“好吃又健康”和“富含维生素”模型也能基于语义将它们关联起来。这就是嵌入向量的威力。你可以扩展这个例子比如从文件读取更大的文档库或者将向量存入数据库以便快速检索这就构成了一个真正可用的语义搜索系统的雏形。7. 总结跟着这篇教程走下来你应该已经完成了gte-base-zh从启动、测试到代码调用的全流程。我们回顾一下关键步骤启动服务先后运行Xinference框架和模型启动脚本让模型在后台待命。快速体验通过Web界面直观感受模型计算文本相似度的能力。代码调用掌握了通过Python发送HTTP请求到模型API获取文本嵌入向量的方法。实践应用亲手实现了一个简易的语义搜索器看到了如何将嵌入向量用于实际任务。gte-base-zh作为一个开箱即用的中文嵌入模型为你省去了大量环境配置和模型准备的时间。无论是想体验语义相似度的神奇还是打算将其集成到你的智能问答、内容推荐、聚类分析等项目中现在你都有了坚实的基础。记住文本嵌入是许多高级NLP应用的基石。理解并会使用它你就打开了一扇新的大门。多尝试不同的文本思考向量背后的语义关系你会对它越来越熟悉。获取更多AI镜像想探索更多AI镜像和应用场景访问 CSDN星图镜像广场提供丰富的预置镜像覆盖大模型推理、图像生成、视频生成、模型微调等多个领域支持一键部署。