gte-base-zh API调用教程：curl/Python requests对接Xinference Embedding接口

gte-base-zh API调用教程curl/Python requests对接Xinference Embedding接口1. 引言为什么你需要这个教程如果你正在寻找一个简单、高效的中文文本嵌入模型并且希望快速上手调用它的API那么你来对地方了。gte-base-zh模型由阿里巴巴达摩院训练是一个基于BERT框架的优秀中文文本嵌入模型。它能够将一段文本转换成一个高维度的向量也就是“嵌入向量”这个向量可以用于衡量文本之间的语义相似度是构建智能搜索、推荐系统、问答机器人等应用的核心技术。你可能已经通过Xinference成功部署了gte-base-zh模型看到了Web界面也尝试了手动输入文本进行相似度比对。但真正的生产力来自于自动化——如何让我们的程序、脚本或者应用能够自动调用这个模型批量处理文本获取嵌入向量这正是本教程要解决的问题。我们将手把手教你如何通过两种最主流、最直接的方式——curl命令行和Python requests库来调用Xinference部署的gte-base-zh模型的Embedding接口。无论你是运维工程师、后端开发者还是AI应用的研究者掌握这些方法都能让你事半功倍。2. 准备工作确认你的模型服务在开始调用API之前我们必须确保模型服务正在正常运行。根据你提供的部署信息模型服务通常运行在http://0.0.0.0:9997这个地址和端口上。2.1 验证服务状态打开你的终端执行以下命令来检查服务是否健康curl http://0.0.0.0:9997/v1/models如果服务正常你会看到一个JSON格式的响应其中列出了已加载的模型应该包含gte-base-zh。类似下面这样{ object: list, data: [ { id: gte-base-zh, object: model, created: 1677652288, owned_by: xinference } ] }看到这个恭喜你API的大门已经为你敞开。2.2 理解核心接口gte-base-zh模型通过Xinference暴露了一个标准的Embedding接口。我们主要使用以下端点接口地址http://0.0.0.0:9997/v1/embeddings请求方法POST核心参数我们需要通过JSON格式的请求体告诉模型我们要对哪些文本进行嵌入。接下来让我们进入实战环节。3. 方法一使用curl命令行调用curl是一个强大的命令行工具非常适合快速测试API、编写Shell脚本或是在服务器上进行简单的集成。它的好处是无需依赖任何编程环境。3.1 基础调用为单个文本生成向量假设我们想获取句子“今天天气真好”的嵌入向量。打开终端输入以下命令curl http://0.0.0.0:9997/v1/embeddings \ -H Content-Type: application/json \ -d { model: gte-base-zh, input: 今天天气真好 }命令拆解-H Content-Type: application/json设置HTTP请求头告诉服务器我们发送的数据是JSON格式。-d ...指定请求体-d代表--data。里面的JSON对象包含两个关键字段model: gte-base-zh指定我们要使用的模型。input: 今天天气真好指定要处理的文本。你会看到这样的响应{ object: list, data: [ { object: embedding, embedding: [ 0.0123456, -0.0234567, 0.0345678, ... // 这里是一个很长的浮点数列表通常是768维 ], index: 0 } ], model: gte-base-zh, usage: { prompt_tokens: 6, total_tokens: 6 } }那个长长的embedding列表就是“今天天气真好”这个句子的向量化表示。3.2 进阶调用批量处理多个文本一次处理多个文本能极大提高效率。input字段不仅支持字符串还支持字符串数组。curl http://0.0.0.0:9997/v1/embeddings \ -H Content-Type: application/json \ -d { model: gte-base-zh, input: [ 人工智能是未来的方向, 机器学习是AI的一个分支, 今天午餐吃什么 ] }这次响应中的data会是一个包含三个元素的数组每个元素对应一个输入文本的嵌入向量和索引。3.3 实用技巧将结果保存到文件在脚本中我们通常需要将API返回的向量保存下来供后续使用。curl可以轻松做到curl http://0.0.0.0:9997/v1/embeddings \ -H Content-Type: application/json \ -d {model: gte-base-zh, input: 测试文本} \ -o embedding_result.json-o embedding_result.json参数会将完整的HTTP响应包括状态码、头部等保存到文件。如果你只想保存响应体JSON数据可以结合jq工具需要先安装curl -s http://0.0.0.0:9997/v1/embeddings \ -H Content-Type: application/json \ -d {model: gte-base-zh, input: 测试文本} | jq .data[0].embedding vector.json4. 方法二使用Python requests库调用对于大多数开发场景使用Python是更灵活的选择。requests库让HTTP请求变得异常简单。首先确保你已安装requests库pip install requests4.1 基础Python调用示例创建一个Python脚本例如get_embedding.pyimport requests import json # 定义API端点和服务地址 api_url http://0.0.0.0:9997/v1/embeddings # 准备请求头和数据 headers { Content-Type: application/json } payload { model: gte-base-zh, input: Python是一门强大的编程语言 } # 发送POST请求 response requests.post(api_url, headersheaders, datajson.dumps(payload)) # 检查请求是否成功 if response.status_code 200: result response.json() # 提取嵌入向量 embedding_vector result[data][0][embedding] print(f嵌入向量维度: {len(embedding_vector)}) print(f向量前10个值: {embedding_vector[:10]}) # 你也可以查看token使用情况 print(f使用的token数: {result[usage][prompt_tokens]}) else: print(f请求失败状态码: {response.status_code}) print(f错误信息: {response.text})运行这个脚本你就能在Python程序中获得文本的向量表示。4.2 构建一个实用的Embedding客户端类为了更好的复用性我们可以将其封装成一个类import requests import json from typing import Union, List class GTEBaseClient: def __init__(self, base_url: str http://0.0.0.0:9997): self.base_url base_url.rstrip(/) self.embedding_url f{self.base_url}/v1/embeddings self.headers {Content-Type: application/json} def get_embedding(self, text: Union[str, List[str]]) - List[List[float]]: 获取单个或批量文本的嵌入向量。 参数: text: 可以是字符串也可以是字符串列表。 返回: 嵌入向量列表。如果是单个文本返回包含一个向量的列表。 payload { model: gte-base-zh, input: text } try: response requests.post(self.embedding_url, headersself.headers, datajson.dumps(payload), timeout30) response.raise_for_status() # 如果状态码不是200抛出HTTPError异常 result response.json() # 提取所有嵌入向量 embeddings [item[embedding] for item in result[data]] return embeddings except requests.exceptions.RequestException as e: print(f请求API时发生错误: {e}) return [] except (KeyError, json.JSONDecodeError) as e: print(f解析响应数据时发生错误: {e}) return [] # 使用示例 if __name__ __main__: client GTEBaseClient() # 单个文本 single_text 深度学习需要大量的数据 vec_single client.get_embedding(single_text) print(f单个文本向量维度: {len(vec_single[0]) if vec_single else 0}) # 批量文本 batch_texts [ 天气预报说明天会下雨, 我打算去看一场电影, 这个模型的嵌入效果很不错 ] vec_batch client.get_embedding(batch_texts) print(f批量处理了 {len(vec_batch)} 个文本) for i, vec in enumerate(vec_batch): print(f文本{i1}的向量长度: {len(vec)})这个类提供了错误处理、超时设置并且可以方便地处理单条和批量请求。4.3 计算文本相似度实战案例获取嵌入向量的最终目的往往是计算相似度。我们可以使用余弦相似度。将下面的函数添加到上面的客户端类中或者单独使用import numpy as np 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) # 实战比较三个句子的相似度 client GTEBaseClient() sentences [ 我喜欢吃苹果, 苹果是一种水果, 我正在用苹果手机 ] embeddings client.get_embedding(sentences) if len(embeddings) 3: sim_0_1 cosine_similarity(embeddings[0], embeddings[1]) # “苹果水果” vs “苹果水果” sim_0_2 cosine_similarity(embeddings[0], embeddings[2]) # “苹果水果” vs “苹果品牌” sim_1_2 cosine_similarity(embeddings[1], embeddings[2]) # “苹果水果” vs “苹果品牌” print(f‘{sentences[0]}’ 和 ‘{sentences[1]}’ 的相似度: {sim_0_1:.4f}) print(f‘{sentences[0]}’ 和 ‘{sentences[2]}’ 的相似度: {sim_0_2:.4f}) print(f‘{sentences[1]}’ 和 ‘{sentences[2]}’ 的相似度: {sim_1_2:.4f}) # 预期结果 sim_0_1 应该远高于 sim_0_2 和 sim_1_2通过这个例子你可以看到gte-base-zh模型能够很好地区分“苹果”一词在不同语境下的语义。5. 常见问题与排错指南在调用过程中你可能会遇到一些问题这里是一些常见的排查步骤连接被拒绝 (Connection refused)问题运行curl或Python脚本时提示无法连接到服务器。解决首先确认Xinference服务是否正在运行。检查你启动服务的命令xinference-local --host 0.0.0.0 --port 9997是否成功执行并且没有报错退出。可以通过ps aux | grep xinference查看进程是否存在。404 Not Found 或 模型不存在问题API返回404错误或者提示模型未加载。解决确认API路径是否正确/v1/embeddings。使用curl http://0.0.0.0:9997/v1/models确认gte-base-zh模型是否在列表中。如果不在你需要通过Xinference的Web UI或命令行重新加载该模型。请求超时 (Timeout)问题处理长文本或批量请求时等待时间过长然后超时。解决在Pythonrequests中增加timeout参数如timeout60。检查服务器资源CPU/内存是否充足。处理大批量文本时建议分批次发送请求。输入文本过长问题模型对输入长度有限制通常是512个token。超出限制可能导致错误或结果不准确。解决对于长文档需要先进行切分分句、分段然后分别获取每段的嵌入最后可以再通过池化如取平均得到文档向量。如何提升调用效率批量处理始终将多个文本放在一个请求的数组里这比循环发送多个单条请求快得多。异步请求如果需要处理海量文本可以考虑使用aiohttp库进行异步并发调用。本地缓存对于不变的文本可以将计算出的嵌入向量保存到本地数据库或文件避免重复调用。6. 总结通过本教程你应该已经掌握了通过API调用Xinference部署的gte-base-zh嵌入模型的两种核心方法对于快速测试和脚本任务curl命令简单直接是运维和调试的利器。对于应用开发Pythonrequests库提供了最大的灵活性和控制力配合numpy等库可以轻松实现相似度计算等下游任务。关键在于理解API的基本格式一个指向/v1/embeddings的POST请求附带指定模型和输入文本的JSON数据。无论是单条文本还是批量文本模型都能高效地返回对应的语义向量。现在你可以将这些向量用于构建语义搜索系统实现智能问答中的问题匹配对文档或商品进行聚类分析为推荐系统提供内容理解能力希望这篇教程能帮助你顺利打通从模型部署到实际应用调用的“最后一公里”。动手试试吧用代码让gte-base-zh模型为你工作获取更多AI镜像想探索更多AI镜像和应用场景访问 CSDN星图镜像广场提供丰富的预置镜像覆盖大模型推理、图像生成、视频生成、模型微调等多个领域支持一键部署。