gte-base-zh实战教程：使用curl/postman直连9997端口调用Embedding API
gte-base-zh实战教程：使用curl/postman直连9997端口调用Embedding API
1. 引言：快速上手文本嵌入服务
你是不是正在寻找一个简单易用的中文文本嵌入方案？想要快速将文本转换为向量表示，又不想折腾复杂的模型部署？那么你来对地方了。
gte-base-zh是由阿里巴巴达摩院训练的中文文本嵌入模型，基于BERT框架专门针对中文场景优化。它能将任意中文文本转换为高质量的向量表示，广泛应用于语义搜索、文本相似度计算、智能推荐等场景。
本教程将手把手教你如何通过xinference部署gte-base-zh模型，并使用最常用的curl和Postman工具直接调用9997端口的Embedding API。无需复杂的环境配置，无需深度学习背景，跟着步骤走，10分钟就能让模型跑起来！
2. 环境准备与模型部署
2.1 模型位置确认
首先确认gte-base-zh模型已经存在于你的系统中。模型的标准安装路径为：
/usr/local/bin/AI-ModelScope/gte-base-zh如果你的模型不在这个路径，请根据实际安装位置进行调整。这个目录包含了模型的所有必要文件，包括配置文件、权重文件等。
2.2 启动xinference服务
使用以下命令启动xinference服务，监听所有网络接口的9997端口：
xinference-local --host 0.0.0.0 --port 9997这个命令会启动一个本地的模型服务，对外提供API接口。--host 0.0.0.0表示服务监听所有网络接口，--port 9997指定服务端口。
2.3 启动模型服务
通过专门的启动脚本发布模型服务：
/usr/local/bin/launch_model_server.py这个脚本会自动加载gte-base-zh模型，并将其注册到xinference服务中，使其可以通过API接口调用。
3. 服务验证与状态检查
3.1 检查服务启动状态
模型初次加载需要一些时间，具体取决于你的硬件配置。可以通过查看日志文件来确认服务状态：
cat /root/workspace/model_server.log当看到类似下面的输出时，表示模型服务已成功启动：
Model loaded successfully Service started on port 9997 Embedding API ready for requests如果日志显示模型正在加载中，请耐心等待几分钟。大型模型的加载通常需要一些时间。
3.2 访问Web管理界面
在浏览器中打开xinference的Web管理界面，通常地址为http://你的服务器IP:9997。界面会显示当前运行的模型列表和服务状态。
在模型列表中找到gte-base-zh，确认其状态为"已加载"或"运行中"。这个界面也提供了简单的测试功能，你可以输入文本并查看嵌入结果。
4. 使用curl调用Embedding API
4.1 基础调用示例
使用curl工具可以直接通过命令行调用Embedding API：
curl -X POST "http://localhost:9997/v1/embeddings" \ -H "Content-Type: application/json" \ -d '{ "model": "gte-base-zh", "input": "这是一个测试文本" }'这个请求会返回一个JSON响应，包含文本的向量表示。向量通常是一个768维的浮点数数组。
4.2 批量处理多个文本
如果需要同时处理多个文本，可以这样调用：
curl -X POST "http://localhost:9997/v1/embeddings" \ -H "Content-Type: application/json" \ -d '{ "model": "gte-base-zh", "input": [ "今天天气真好", "人工智能技术发展迅速", "文本嵌入很有用" ] }'API会返回每个文本对应的嵌入向量，方便批量处理。
4.3 高级参数设置
gte-base-zh模型支持一些高级参数，比如指定返回的向量格式：
curl -X POST "http://localhost:9997/v1/embeddings" \ -H "Content-Type: application/json" \ -d '{ "model": "gte-base-zh", "input": "高级参数示例", "encoding_format": "base64" }'encoding_format参数支持float（默认）、base64等格式，可以根据需要选择。
5. 使用Postman调用API
5.1 Postman基础配置
对于喜欢图形化界面的用户，Postman是个不错的选择。首先新建一个POST请求：
- URL:
http://localhost:9997/v1/embeddings - Method: POST
- Headers:
Content-Type: application/json
在Body中选择raw格式，然后输入JSON格式的请求数据。
5.2 单个文本嵌入请求
在Postman的Body中输入：
{ "model": "gte-base-zh", "input": "使用Postman调用嵌入API" }点击Send按钮，右侧会显示服务器返回的响应，包含嵌入向量和其他元数据。
5.3 批量请求和参数调整
对于批量请求，只需将input改为数组格式：
{ "model": "gte-base-zh", "input": [ "第一个文本", "第二个文本", "第三个文本" ] }你还可以添加其他参数，如user字段用于标识请求用户，方便后续的用量统计和审计。
6. 实际应用示例
6.1 语义相似度计算
获取两个文本的嵌入向量后，可以计算它们的余弦相似度：
import numpy as np from sklearn.metrics.pairwise import cosine_similarity # 假设emb1和emb2是两个文本的嵌入向量 similarity = cosine_similarity([emb1], [emb2])[0][0] print(f"语义相似度: {similarity:.4f}")这种方法可以用于文档去重、推荐系统、问答匹配等场景。
6.2 简单搜索引擎实现
利用文本嵌入可以构建一个简单的语义搜索引擎：
def semantic_search(query, documents, top_k=5): # 获取查询的嵌入向量 query_embedding = get_embedding(query) # 计算与每个文档的相似度 similarities = [] for doc in documents: doc_embedding = get_embedding(doc['text']) similarity = cosine_similarity([query_embedding], [doc_embedding])[0][0] similarities.append((doc, similarity)) # 按相似度排序并返回前top_k个结果 similarities.sort(key=lambda x: x[1], reverse=True) return similarities[:top_k]6.3 文本分类特征提取
文本嵌入向量可以作为机器学习模型的输入特征：
from sklearn.svm import SVC from sklearn.model_selection import train_test_split # 获取所有文本的嵌入向量 embeddings = [get_embedding(text) for text in texts] # 划分训练测试集 X_train, X_test, y_train, y_test = train_test_split( embeddings, labels, test_size=0.2, random_state=42 ) # 训练分类器 classifier = SVC() classifier.fit(X_train, y_train) # 评估性能 accuracy = classifier.score(X_test, y_test) print(f"分类准确率: {accuracy:.4f}")7. 常见问题与解决方案
7.1 服务连接问题
如果遇到连接拒绝错误，首先检查服务是否正常启动：
# 检查端口监听状态 netstat -tlnp | grep 9997 # 检查服务进程 ps aux | grep xinference确保xinference服务正在运行并监听正确的端口。
7.2 模型加载失败
如果模型加载失败，检查模型文件是否完整：
# 检查模型目录结构 ls -la /usr/local/bin/AI-ModelScope/gte-base-zh/确保所有必要的模型文件都存在且有读取权限。
7.3 性能优化建议
对于生产环境使用，可以考虑以下优化措施：
- 启用批处理功能，提高吞吐量
- 使用GPU加速（如果可用）
- 调整服务线程数以适应硬件配置
- 实现缓存机制，避免重复计算相同文本
8. 总结
通过本教程，你已经学会了如何使用curl和Postman直接调用gte-base-zh模型的Embedding API。这种方式的优势很明显：
- 简单直接：无需复杂的客户端库，HTTP请求就能搞定
- 跨平台兼容：任何能发送HTTP请求的工具都能使用
- 快速集成：几分钟就能接入现有系统
- 灵活性强：支持单文本和批量处理
无论是开发原型还是生产部署，直接调用API都是个不错的选择。记得在实际应用中处理好错误异常，添加适当的超时和重试机制，确保服务的稳定性。
现在就去试试吧，让你的应用获得强大的文本理解能力！
获取更多AI镜像
想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。