前提条件

• 您已在火山方舟控制台在线推理页面创建了推理接入点 ，接入向量模型并获取接入点 ID。
  
• 您已参考安装与初始化中的步骤完成 SDK 安装和访问凭证配置。

示例代码

向量化

import os
from volcenginesdkarkruntime import Ark

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

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