您可以使用文本向量化模型服务，将文本转化为表达文本语义的向量，并通过计算向量计算出文本之间语义差距。在检索、个性化推荐、智能对话等场景进行文本的分类、聚类、检索、生成等自然语言处理任务。

当前支持文本向量化的模型请参见文本向量化能力。

• 获取 API Key 。
  • 使用 Access Key 鉴权请参考Access Key 签名鉴权。
• 开通模型服务。
• 在模型列表获取所需 Model ID 。
  • 通过 Endpoint ID 调用模型服务请参考获取 Endpoint ID（创建自定义推理接入点）。

文本字符串转换向量

通过调用doubao-embedding-text-240715模型，将输入的文本字符串转换为向量表示，并输出向量维度和前10维数值。

import os
from volcenginesdkarkruntime import Ark
# 初始化客户端
client = Ark(
    # 从环境变量中读取您的方舟API Key
    api_key=os.environ.get("ARK_API_KEY"),
    base_url="https://ark.cn-beijing.volces.com/api/v3"
)
response = client.embeddings.create(
    model="doubao-embedding-text-240715",
    input="Function Calling 是一种将大模型与外部工具和 API 相连的关键功能",
    encoding_format="float"  
)
# 打印结果
print(f"向量维度: {len(response.data[0].embedding)}")
print(f"前10维向量: {response.data[0].embedding[:10]}")

输入文本文件逐行转换

向量化模型可以基于您上传的文档生成嵌入向量。此处以embedding_text.txt作为示例文件，您可以通过代码对文本文件逐行转化成向量。

embedding_text.txt

未知大小

import os
from volcenginesdkarkruntime import Ark
client = Ark(
    # 从环境变量中读取您的方舟API Key
    api_key=os.environ.get("ARK_API_KEY"),
    base_url="https://ark.cn-beijing.volces.com/api/v3"
)
# 从文件读取文本并生成向量
with open("embedding_text.txt", "r", encoding="utf-8") as f:
    # 按行分割文本（每行作为一个独立输入）
    texts = [line.strip() for line in f if line.strip()]
    
    response = client.embeddings.create(
        model="doubao-embedding-text-240715",
        input=texts,
        encoding_format="float"
    )
# 打印结果
print(f"处理文本数量: {len(response.data)}")
print(f"首个文本向量维度: {len(response.data[0].embedding)}")

通过上述示例完成基础向量生成后，您可以基于使用场景对向量进行更深层次的处理与分析，常用的功能包括相似度计算与维度优化。

相似度计算

• Doubao-embedding向量间相似度得分可以使用余弦相似度作为计算方式，余弦相似度计算拆分为下面两步：
  • 第一步: 请求doubao-embedding接口得到embedding，将embedding向量L2_norm处理;
  • 第二步: 对norm处理后的向量进行点积计算得到余弦相似度;

向量降维

向量化是通过向量来表征文本、图像等非结构化数据的过程，让计算机能明白语言、图像等的含义。其中标注词义的维度是描述向量化后向量中数字的个数。在文本向量化场景，每个维度对应文本的一个特征。

• 维度更多：以更多独立特征标注词语来捕捉语义细节，提升表征精度。但会导致数据量膨胀，带来更高的存储成本（内存/磁盘占用）和计算开销（相似度计算、模型推理耗时）。
• 维度更低：以更少特征标注词语，可能损失部分细节。但数据量缩减，存储效率与计算速度会提升，资源消耗以及成本更低。

下列模型支持多种维度，您可通过向量降维，选择合适的维度来向量化文本，平衡“语义精度”、”计算速度“与“资源成本”三者成本。

示例代码

• 推荐用法：常规降维方式以doubao-embedding-text-240715模型为例，最高维度2560可以压缩到512, 1024, 2048维度存储检索，维度越高越接近最高维度效果。
  • 如何降维度&计算相似度？
    1. 降维度: 将embedding接口获取的向量直接截取前dim维度;
    2. 计算相似度: 对截取后的embedding做余弦相似度计算;

# 降维 + L2_norm
def sliced_norm_l2(vec: List[float], dim=2560) -> List[float]:
    # dim 取值 512,1024,2048
    norm = float(np.linalg.norm(vec[ :dim]))
    return [v / norm for v in vec[ :dim]]
    
# 余弦相似度计算
query_doc_relevance_score_2560d = np.matmul(
    sliced_norm_l2(embeddings[0], 2560), #查询向量
    sliced_norm_l2(embeddings[1], 2560)  #文档向量
)

• 针对doubao-embedding-large-text-250515模型，需要降维后L2归一化使用。模型支持多种嵌入维度：[2048、1024、512、256] ，即使在较低维度下性能下降也较小。
  • 如何降维度&计算相似度？
    1. 降维度: 将embedding接口获取的向量直接截取前dim维度;
    2. 归一化：使用 L2 归一化统一向量长度，确保余弦相似度计算准确。
    3. 计算相似度: 对截取后的embedding做余弦相似度计算;

def encode(
    client, inputs: List[str], is_query: bool = False, mrl_dim: Optional[int] = None
):
    # 处理查询文本（添加指令模板优化检索性能）
    if is_query:
        inputs = [f"Instruct: Given a web search query...\nQuery: {i}" for i in inputs]  
    # 调用API获取原始向量（未归一化）
    resp = client.embeddings.create(
        model="doubao-embedding-large-text-250515",
        input=inputs,
        encoding_format="float",
    )
    # 转换为张量并降维（截取前mrl_dim维度）
    embedding = torch.tensor([d.embedding for d in resp.data], dtype=torch.bfloat16)
    if mrl_dim is not None:
        assert mrl_dim in [256, 512, 1024, 2048], "仅支持256/512/1024/2048维"
        embedding = embedding[:, :mrl_dim]  
    # 必须执行归一化：L2归一化后才能计算余弦相似度
    embedding = torch.nn.functional.normalize(embedding, dim=1, p=2).float().numpy()
    return embedding

场景概述

下列程序实现了将查询文本和资料库文本向量匹配的功能。我们以embedding_text.txt的多行文本作为资料库，通过调用Doubao-embedding模型生成文本向量。当程序接收到用户的查询文本时，将其向量化并通过余弦相似度匹配资料库的向量，最终返回最相关的前3条文本及对应相似度分数。

第一步：客户端初始化

导入所需的库包，并设置 API Key，为后续的数据处理和分析做准备。

import os
# 导入火山引擎大模型SDK
from volcenginesdkarkruntime import Ark
# 初始化客户端
client = Ark(
    api_key=os.environ.get("ARK_API_KEY"),
    base_url="https://ark.cn-beijing.volces.com/api/v3"
)

第二步：从文件读取文本并生成向量

读取包含文本的embedding_text.txt文件，调用文本向量模型 API 逐行生成文本对应的向量，并将文本和向量保存为 JSON 文件。

embedding_text.txt

未知大小

def generate_and_save_embeddings(file_path="embedding_text.txt", output_path="embeddings.json"):
    with open(file_path, "r", encoding="utf-8") as f:
        texts = [line.strip() for line in f if line.strip()]
    # 调用向量化API
    response = client.embeddings.create(
        model="doubao-embedding-text-240715",
        input=texts,
        encoding_format="float"
    )
    # 构建结果并保存
    results = [{"text": text, "embedding": data.embedding} 
              for text, data in zip(texts, response.data)]
    
    with open(output_path, "w", encoding="utf-8") as f:
        json.dump(results, f)
    
    print(f"已生成并保存 {len(results)} 条向量至 {output_path}")
    return results

第三步：加载预计算的向量数据

从 JSON 文件加载预计算的文本向量数据，为后续的相似度计算做准备。

def load_embeddings(file_path="embeddings.json"):
    with open(file_path, "r", encoding="utf-8") as f:
        return json.load(f)

第四步：定义计算余弦相似度函数和搜索相似文本函数

利用余弦相似度来度量文本之间的相似性，实现了一个基于内容的文本搜索功能。
用户可以通过输入查询文本，检索与该查询文本最相关的文本。

# 定义计算余弦相似度函数
def cosine_similarity(a, b):
    a = np.array(a)
    b = np.array(b)
    return np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b))
    
# 定义search_similar_text 函数：搜索与查询文本最相似的前N条文本
def search_similar_text(query_text, embeddings, top_n=3):
    # 生成查询文本的向量
    query_response = client.embeddings.create(
        model="doubao-embedding-text-240715",
        input=[query_text],
        encoding_format="float"
    )
    query_embedding = query_response.data[0].embedding
    # 计算相似度
    for item in embeddings:
        item["similarity"] = cosine_similarity(item["embedding"], query_embedding)
    # 排序并返回结果
    sorted_results = sorted(embeddings, key=lambda x: x["similarity"], reverse=True)
    return sorted_results[:top_n]

第五步：测试搜索功能

测试搜索功能，调用 search_similar_text 函数查询与query变量相关的文本，并返回与该查询文本最相关的前 3 条文本及其相似度分数。

# 示例：生成向量并搜索
if __name__ == "__main__":
    # 生成或加载向量
    try:
        embeddings = load_embeddings()
        print(f"已加载 {len(embeddings)} 条预计算向量")
    except FileNotFoundError:
        print("未找到预计算向量，将从文件生成...")
        embeddings = generate_and_save_embeddings()
    
    # 执行搜索（示例查询：上下文缓存机制）
    query = "上下文缓存（Context API）是方舟提供的一个高效的缓存机制，旨在为您优化生成式AI在不同交互场景下的性能和成本。"
    results = search_similar_text(query, embeddings, top_n=3)
    
    # 打印结果
    print(f"\n搜索查询: '{query}'")
    for i, result in enumerate(results, 1):
        print(f"\nTop {i} (相似度: {result['similarity']:.4f}):")
        print(f"{result['text'][:200]}...")  # 显示前200个字符

结果示例

运行上述程序后，结果将展示与查询文本相似度最高的前3条文本内容，并分别标注其相似度分数。

已加载 7 条预计算向量
搜索查询: '上下文缓存（Context API）是方舟提供的一个高效的缓存机制，旨在为您优化生成式AI在不同交互场景下的性能和成本。'
Top 1 (相似度: 0.9085):
上下文缓存（Context API）通过缓存数据优化AI性能与成本...
Top 2 (相似度: 0.7384):
文本生成可理解文本并进行对话回复...
Top 3 (相似度: 0.7201):
批量推理适用于大计算量非即时任务，享高配额与低价...