# 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 引擎过载。 稍后重试。
在线咨询
体验中心