gte-base-zh保姆级教程：从启动到调用，小白也能玩转文本嵌入

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

运行这个脚本后，它会做几件事：

1. 找到本地的gte-base-zh模型文件。
2. 通过Xinference的接口，将模型注册并启动为一个服务。
3. 这个服务会提供一个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”的模型卡片。点击它，通常会进入一个模型详情或测试页面。

在这个测试页面，你会看到类似这样的功能：

• 示例文本：系统可能预置了一些句子对，比如“今天天气真好”和“阳光明媚的一天”。
• 输入框：允许你自己输入两段文本。
• “相似度比对”或“计算”按钮：点击它，让模型开始工作。

我们来试一下：

1. 在第一个输入框输入：“我喜欢吃苹果”。
2. 在第二个输入框输入：“苹果是一种水果”。
3. 点击“相似度比对”按钮。

稍等片刻，页面会显示一个相似度分数，比如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, json=payload, headers=headers) 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}")

运行这个脚本：

1. 将上面的代码保存为一个文件，比如test_embedding.py。
2. 在终端中，切换到该文件所在目录。
3. 运行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 代码实现

我们将分几步走：

1. 为知识库中的所有文档预先计算好嵌入向量并存储起来（这个过程叫“索引”）。
2. 当用户输入查询语句时，计算它的嵌入向量。
3. 将查询向量与所有文档向量计算余弦相似度。
4. 按相似度从高到低排序，返回最相关的文档。

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, json=payload, headers=headers) 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, json=payload, headers=headers) 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(key=lambda x: x[0], reverse=True) # 6. 输出结果 print("搜索结果（按相关性排序）:") print("-" * 50) for rank, (score, doc, idx) in enumerate(results[:3], start=1): # 显示前3个 print(f"第{rank}名 [相似度: {score:.4f}]") print(f"文档{idx+1}: {doc}") print("-" * 50)

6.3 运行与思考

1. 将上面的代码保存为semantic_search.py并运行。
2. 尝试输入不同的查询，比如：
   • “有什么好吃又健康的水果？”（应该匹配苹果、香蕉、橙子）
   • “编程难学吗？”（应该匹配计算机编程和机器学习）
   • “补充维生素吃什么？”（应该匹配苹果、橙子）

观察结果，你会发现，即使你的查询语句和文档没有相同的字眼（比如“好吃又健康”和“富含维生素”），模型也能基于语义将它们关联起来。这就是嵌入向量的威力。

你可以扩展这个例子，比如从文件读取更大的文档库，或者将向量存入数据库以便快速检索，这就构成了一个真正可用的语义搜索系统的雏形。

7. 总结

跟着这篇教程走下来，你应该已经完成了gte-base-zh从启动、测试到代码调用的全流程。我们回顾一下关键步骤：

1. 启动服务：先后运行Xinference框架和模型启动脚本，让模型在后台待命。
2. 快速体验：通过Web界面，直观感受模型计算文本相似度的能力。
3. 代码调用：掌握了通过Python发送HTTP请求到模型API，获取文本嵌入向量的方法。
4. 实践应用：亲手实现了一个简易的语义搜索器，看到了如何将嵌入向量用于实际任务。

gte-base-zh作为一个开箱即用的中文嵌入模型，为你省去了大量环境配置和模型准备的时间。无论是想体验语义相似度的神奇，还是打算将其集成到你的智能问答、内容推荐、聚类分析等项目中，现在你都有了坚实的基础。

记住，文本嵌入是许多高级NLP应用的基石。理解并会使用它，你就打开了一扇新的大门。多尝试不同的文本，思考向量背后的语义关系，你会对它越来越熟悉。

获取更多AI镜像

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