# Embedding & Rerank 服务_HTTP协议
# 1. 接口说明
本文档介绍了 Embedding 和 Rerank 两种服务(API)的调用方法。
- Embedding 服务: 用于将文本转换为向量表示。
- Rerank 服务: 用于对一组文档根据查询进行相关性重排序。
# 1.1 通用信息
- 协议: HTTP
- 请求方法: POST
- 默认请求根地址:
https://maas-api.cn-huabei-1.xf-yun.com/v1 - Embedding 服务路径:
/embeddings - Rerank 服务路径:
/rerank
完整的请求地址由 根地址 + 服务路径 组成。
# 1.2 Python 调用示例
下面是一个完整的 Python Demo,展示了如何使用 openai SDK 调用 Embedding 和 Rerank 服务。
import openai
import httpx
# 必填:从服务管控页面获取对应服务的APIKey和API Base
api_key = "<YOUR_API_KEY>"
base_url = "https://maas-api.cn-huabei-1.xf-yun.com/v1"
client = openai.OpenAI(api_key=api_key, base_url=base_url)
def get_embedding(text, model="sde0a5839"):
"""
调用 Embedding API。
:param text: 需要进行向量化的一段或多段文本。
:param model: 使用的 embedding 模型 ID。
"""
try:
response = client.embeddings.create(
model=model,
input=text,
)
return response.data
except Exception as e:
print(f"Embedding 请求出错: {e}")
return None
def get_rerank(query, documents, model="s125c8e0e"):
"""
调用 Rerank API。
:param query: 查询语句。
:param documents: 需要重排序的文档列表。
:param model: 使用的 rerank 模型 ID。
"""
try:
# 注意:OpenAI SDK 没有原生的 rerank 方法,需要通过 client.post 发起原始请求
response = client.post(
"/rerank",
body={
"model": model,
"query": query,
"documents": documents,
},
cast_to=httpx.Response,
)
return response.json()
except Exception as e:
print(f"Rerank 请求出错: {e}")
return None
if __name__ == "__main__":
# --- Embedding Demo ---
print("********* 1. Embedding API 调用 *********")
embedding_text = "夏天最好吃的水果是西瓜"
embeddings = get_embedding(embedding_text)
if embeddings:
for i, embedding_data in enumerate(embeddings):
print(f"文本片段 {i} 的向量 (前5维): {embedding_data.embedding[:5]}...")
print(f"向量总维度: {len(embedding_data.embedding)}")
# --- Rerank Demo ---
print("********* 2. Rerank API 调用 *********")
query = "夏天最好吃的水果是?"
documents = ["西瓜", "草莓", "荔枝"]
rerank_results = get_rerank(query, documents)
if rerank_results:
print(f"查询: {query}")
print("重排序结果:")
# 注意:rerank 返回的 results 列表并未按分数排序,需要自行处理
for result in rerank_results.get("results", []):
doc_index = result.get('index')
score = result.get('relevance_score')
print(f" - 文档: '{documents[doc_index]}' (相关性得分: {score})")
# 2. Embedding API
# 2.1 接口地址
POST https://maas-api.cn-huabei-1.xf-yun.com/v1/embeddings
# 2.2 请求参数
| 参数 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| model | string | 是 | 指定要调用的 Embedding 模型ID,例如 sde0a5839。 |
| input | string / array | 是 | 需要进行向量化的文本或文本数组。 |
| encoding_format | string | 否 | 返回的 embedding 格式,默认为 float。 |
| dimensions | int | 否 | 输出向量的维度,具体支持范围请参考模型说明。 |
# 2.2.1 请求示例
{
"model": "sde0a5839",
"input": "夏天最好吃的水果是西瓜"
}
# 2.3 响应数据
# 成功响应示例
{
"id": "xxxxx",
"object": "list",
"created": 1754981944,
"model": "xop3qwen0b6embedding",
"data": [
{
"index": 0,
"object": "embedding",
"embedding": [
0.012559599,
-0.083535939,
...
]
}
],
"usage": {
"prompt_tokens": 10,
"total_tokens": 10
}
}
# 响应参数说明
| 字段名 | 类型 | 字段说明 |
|---|---|---|
| id | string | 本次调用的唯一ID。 |
| object | string | 对象类型,通常为 list。 |
| created | int | 响应生成的Unix时间戳。 |
| model | string | 实际调用的模型名称。 |
| data | array | 包含 embedding 结果的数组。 |
| data.index | int | 对应输入文本的索引。 |
| data.object | string | 对象类型,通常为 embedding。 |
| data.embedding | array | 生成的向量。 |
| usage | object | Token 使用统计信息。 |
# 3. Rerank API
# 3.1 接口地址
POST https://maas-api.cn-huabei-1.xf-yun.com/v1/rerank
# 3.2 请求参数
| 参数 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| model | string | 是 | 指定要调用的 Rerank 模型ID,例如 s125c8e0e。 |
| query | string | 是 | 用于排序的查询语句。 |
| documents | array | 是 | 需要进行重排序的文档字符串列表。 |
# 3.2.1 请求示例
{
"model": "s125c8e0e",
"query": "夏天最好吃的水果是?",
"documents": ["西瓜", "草莓", "荔枝"]
}
# 3.3 响应数据
# 成功响应示例
{
"id": "xxx",
"object": "xxxx",
"created": 1737030836,
"model": "xop3qwen0b6reranker",
"results": [
{
"index": 0,
"relevance_score": 0.2704802
},
{
"index": 2,
"relevance_score": 0.0011695
},
{
"index": 1,
"relevance_score": 0.0002780
}
],
"usage": {
"prompt_tokens": 131,
"total_tokens": 131
}
}
注意:
results数组中的document字段已在较新版本中移除,仅返回索引和分数。
# 响应参数说明
| 字段名 | 类型 | 字段说明 |
|---|---|---|
| id | string | 本次调用的唯一ID。 |
| object | string | 对象类型。 |
| created | int | 响应生成的Unix时间戳。 |
| model | string | 实际调用的模型名称。 |
| results | array | 包含排序结果的数组,注意:此数组默认不按分数排序。 |
| results.index | int | 对应原始 documents 数组中的索引。 |
| results.relevance_score | float | 文档与查询的相关性得分。 |
| usage | object | Token 使用统计信息。 |
# 4. 通用错误码
| 错误码 | 原因 | 解决方案 |
|---|---|---|
| 401 | 身份验证无效或API密钥不正确。 | 检查API密钥和组织信息。 |
| 403 | 无权访问该模型或地区受限。 | 确认模型权限或联系支持。 |
| 429 | 请求速率或配额超限。 | 控制请求频率或增加配额。 |
| 500 | 服务器内部错误。 | 稍后重试,或联系支持。 |
| 503 | 引擎过载。 | 稍后重试。 |
在这篇文章中: