前提条件

• 您已创建API Key，并已正确配置，具体获取及配置请参见1.获取并配置 API Key 。

• 在开通管理页开通所需模型的服务。

• 在模型列表获取所需模型的ID（Model ID），后续调用模型服务时需使用。

  说明

  如您需要控制限流、监控服务指标、加固安全、防护风险等高级能力，您也可通过 Endpoint ID 调用模型服务，具体可以参考获取 Endpoint ID。

• 您已完成环境配置，包括Python以及SDK的安装，具体方法请参见Python。

参数说明

文本向量化 API

示例代码

向量化

import os
from volcenginesdkarkruntime import Ark

client = Ark(api_key=os.environ.get("ARK_API_KEY"))





print("----- embeddings request -----")
resp = client.embeddings.create(
    model="<Model>",
    input=["花椰菜又称菜花、花菜，是一种常见的蔬菜。"]
)
print(resp)

doubao-embedding 模型调用示例代码

import os
from typing import List
import numpy as np
from volcenginesdkarkruntime import Ark

def sliced_norm_l2(vec: List[float], dim=2048) -> List[float]:
    # dim 取值 512,1024,2048
    norm = float(np.linalg.norm(vec[:dim]))
    return [v / norm for v in vec[:dim]]


client = Ark(api_key=os.environ.get("ARK_API_KEY"))





print("----- embeddings request -----")
#  doubao-embedding 模型用于检索场景，query 建议必须添加如下 instruction 前缀保证检索效果
query_instruction = "为这个句子生成表示以用于检索相关文章："
query = "天是什么颜色？"
# 向量索引的 document 则不添加 instruction
document = "天空呈现颜色主要与“瑞利散射”现象有关，具体形成过程如下：太阳光是由红、橙、黄、绿、蓝、靛、紫等多种颜色的光混合而成的。大气中存在着无数的气体分子和其他微粒。当太阳光进入地球大气层时，波长较长的红光、橙光、黄光能穿透大气层，直接射到地面，而波长较短的蓝、紫、靛等色光，很容易被悬浮在空气中的微粒阻挡，从而使光线散射向四方。其中蓝光波长较短，散射作用更强，因此我们眼睛看到的天空主要呈现蓝色。在一些特殊情况下，如傍晚或早晨，阳光斜射角度大，通过大气层的路径较长，蓝光等短波长光被散射得更多，而红光等长波长光散射损失较少，这时天空可能会呈现橙红色等其他颜色。"

resp = client.embeddings.create(
    model="<Model>",
    input=[
        query_instruction + query,  # query text
        document,  # document text
    ]
)

embeddings = [item.embedding for item in resp.data]
query_doc_relevance_score_2048d = np.matmul(
    sliced_norm_l2(embeddings[0], 2048),  # query embedding
    sliced_norm_l2(embeddings[1], 2048)  # document embedding
)
query_doc_relevance_score_1024d = np.matmul(
    sliced_norm_l2(embeddings[0], 1024),  # query embedding，压缩维度
    sliced_norm_l2(embeddings[1], 1024)  # document embedding，压缩维度
)
query_doc_relevance_score_512d = np.matmul(
    sliced_norm_l2(embeddings[0], 512),  # query embedding，压缩维度
    sliced_norm_l2(embeddings[1], 512)  # document embedding，压缩维度
)
print(f"2048 dim relevance score: {query_doc_relevance_score_2048d:6f}")
print(f"1024 dim relevance score: {query_doc_relevance_score_1024d:6f}")
print(f" 512 dim relevance score: {query_doc_relevance_score_512d:6f}")
# 裁剪维度越低，不同内容的区分度越低，检索的准确率、召回率、NDCG 都会变差

设置自定义 header

import os
from volcenginesdkarkruntime._constants import CLIENT_REQUEST_HEADER
from volcenginesdkarkruntime import Ark

client = Ark(api_key=os.environ.get("ARK_API_KEY"))





print("----- embeddings request -----")
resp = client.embeddings.create(
    model="<Model>",
    input=["花椰菜又称菜花、花菜，是一种常见的蔬菜。"],
    # 自定义request id
    extra_headers={CLIENT_REQUEST_HEADER: "202406251728190000B7EA7A9648AC08D9"}
)
print(resp)

异常处理

import os
from volcenginesdkarkruntime._exceptions import ArkAPIError
from volcenginesdkarkruntime import Ark

client = Ark(api_key=os.environ.get("ARK_API_KEY"))





print("----- embeddings request -----")
try:
      resp = client.embeddings.create(
          model="<Model>",
          input=["花椰菜又称菜花、花菜，是一种常见的蔬菜。"]
      )
      print(resp)
except ArkAPIError as e:
    print(e)