本文为您介绍 Embedding 模型的接口，以及使用 Restful API 和 OpenAI SDK 调用 Embedding 模型的完整流程。

embedding 接口

/v1/embeddings 接口用于请求 Embedding 服务，通过深度学习神经网络提取文本、图片等非结构化数据里的内容和语义，把文本、图片等变成特征向量。

请求说明

• URI：统一资源标识符，固定为/v1/embeddings。
• 请求头：请求消息类型，固定位Content-Type: application/json。

请求参数

响应示例

以下示例中返回的 embedding 参数，就是您输入的文本或图片返回的 embedding 结果。

{
    "object": "list",
    "model": "ImageSearch-Demo",
    "data": [
        {
            "index": 0,
            "object": "embedding",
            "embedding": [
                -0.40416327118873596,
                0.17097428441047668,
                ......省略若干
                0.1333296298980713,
                0.472359299659729,
                0.05078130215406418]
        }
    ],
    "usage": {
        "prompt_tokens": 0,
        "total_tokens": 0
    }
}

调用 Embedding 模型

本文以调用 Image Embedding 模型为例，Text Embedding 模型的调用方式也相同。

部署模型

首先需要先部署一个 Embedding 模型服务。云搜索服务提供了一个 Image Embedding 模型示例文件（model），您可以自行下载并上传到 TOS Bucket，然后创建模型。
创建一个 Image Embedding 模型，然后创建并启动一个允许私网访问的推理任务。具体操作，请参见二、创建并启动模型。

使用 Restful API 调用模型

模型创建后，您可以在相同 VPC 环境的 ECS 中，通过调用 Embedding 模型的私网访问地址，获取目标对象的向量化结果。

1. 推理任务正常运行后，在推理服务基本信息页面查看模型的调用信息。
   
   

2. 连接 ECS 实例。连接方式请参见连接 ECS 实例。

3. 在 ECS 实例命令行中，直接执行模型的调用信息（需替换**$API_KEY**），获取目标对象的向量结果。
   如何创建调用模型的 API Key，请参见创建 API Key。

   curl http://r-0s0ceg**.escloud.volces.com/d-184717321835220**/v1/embeddings \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer $API_KEY" \
     -X POST \
     -d '{
       "model": "image-search",
       "input": [
          "tos://doc-test/picture/image_temp/aaa.jpg"
       ]
     }'
   

   • model：Image Embedding 模型的名称。
   • input：需要获取向量结果的对象，支持文字和图片。文字示例为White T-shirt，图片示例为 TOS 存放路径tos://doc-test/picture/image_temp/aaa.jpg或 Base64 编码data:image/jpeg;base64,iVBORw0....。
     

使用 OpenAI SDK 调用模型

模型创建后，您可以在相同 VPC 环境的 ECS 中，通过 OpenAI SDK 调用 Embedding 模型，获取目标内容的向量化结果。

1. 推理任务正常运行后，在推理服务基本信息页面查看模型的私网访问地址。
   

2. 连接 ECS 实例。连接方式请参见连接 ECS 实例。

3. 在 ECS 命令行中，安装 openai。

   pip install openai
   

4. 创建一个 Python 脚本，比如embedding.py。

   touch embedding.py
   

5. 在新建的 Python 脚本中添加以下内容。

   import openai
   
   client = openai.OpenAI(
            api_key="$API_KEY",
            base_url="http://r-00g0ki***-18294241573**-private.escloud.ivolces.com:8000/v1",  
   )
   
   response = client.embeddings.create(
              model= "ImageSearch-Demo",
              input=["White T-shirt"])
               
   print(response.model_dump_json(indent=2))
   

   • api_key：调用模型的 API Key。如何创建调用模型的 API Key，请参见创建 API Key。
   • base_url：模型的私网访问地址。
   • model：Image Embedding 模型的名称。
   • input：需要获取向量结果的对象，支持文字和图片。文字示例为White T-shirt，图片示例为 TOS 存放路径tos://doc-test/picture/image_temp/aaa.jpg或 Base64 编码data:image/jpeg;base64,iVBORw0KGg....。

6. 执行以下命令，运行 Python 脚本，获取向量结果。

   python3 embedding.py
   

   

模型使用案列

• Text Embedding 模型使用案例
• Image Embedding 模型使用案列