章节导航

嵌入向量

嵌入向量（Embeddings）是能捕捉语义的数值表示法——把文字转换成向量（一串数字），可用于各种机器学习任务。BazaarLink 提供与 OpenAI Embeddings API 相容的统一端点，让您透过同一组接口调用多家供应商的嵌入模型。

Embedding 响应使用不透明的 BazaarLink 请求 ID，与 x-request-id 相同；可配合 GET /v1/generation 使用。非流式响应也会在 x-generation-id 返回同一个 ID。usage.cost 是此请求向客户收取的美元金额。统计数据可能在完成后几秒才可用；若收到 404，请稍后短暂重试。

什么是嵌入向量？

嵌入向量把文字转换成高维度向量，语义相近的文字在向量空间里的距离也会更接近——例如「猫」与「小猫」的嵌入会很相似，但「猫」与「飞机」会相距很远。这种向量表示法让机器能够理解文字之间的关联，是许多 AI 应用的基础。

常见应用场景

场景

说明

RAG（检索增强生成）打造能在生成答案前，先从知识库中检索相关内容的系统——嵌入向量能找出最相关的文件，放进 LLM 的上下文。

语义搜索把文件和查询都转成嵌入向量，再用向量相似度找出最相关的文件——比单纯比对关键字更能理解语义、效果更好。

推荐系统为商品、文章、视频等项目与用户偏好生成嵌入向量，借由向量比对推荐相近项目——即使没有共同关键字也能找到语义相关的内容。

分群与分类透过分析嵌入向量的模式，把相似的文件分群或分类——嵌入向量相近的文件通常属于相同主题或类别。

重复内容检测透过比对嵌入向量的相似度找出重复或近似重复的内容——即使内容经过改写或换句话说也能检测到。

异常检测找出嵌入向量明显偏离数据集一般模式的内容，借此识别异常或离群的内容。

POST/v1/embeddings

Note

若上游来源不支持所需的嵌入模型，请求可以改试其他可用来源；若没有来源支持该模型，请求会返回错误。

参数

model必填

string

要使用的嵌入模型，例如 "openai/text-embedding-3-small"。

input必填

string | string[] | ContentItem[]

要嵌入的文本 —— 可以是单个字符串、一次批量调用用的字符串数组，或（支持的模型）混合 text 和 image_url 部分的 {content:[...]} 项数组。

dimensions

integer

请求的输出向量维度。仅支持可变维度的模型会采用（例如 OpenAI text-embedding-3 系列）；原样转发给上游供应商，不支持的模型会忽略此参数。

encoding_format

string

请求的嵌入编码格式，例如 "float" 或 "base64"。原样转发给上游供应商 —— 是否支持取决于模型。

provider

object

Unsupported. The entire object is ignored and removed before forwarding; it cannot select an upstream or price tier.

基本请求

1
2
3
4
5
6
7
8
9
10
11
12
13
from openai import OpenAI

client = OpenAI(
    base_url="https://api.bazaarlink.ai/v1",
    api_key="sk-bl-YOUR_API_KEY",
)

response = client.embeddings.create(
    model="openai/text-embedding-3-small",
    input="The quick brown fox jumps over the lazy dog",
)

print(response.data[0].embedding)  # 1536-dimensional vector

批量处理

发送字符串数组，可在单次请求中嵌入多段文本 —— 比逐条调用更便宜也更快。

1
2
3
4
5
6
7
8
9
10
11
response = client.embeddings.create(
    model="openai/text-embedding-3-small",
    input=[
        "Machine learning is a subset of artificial intelligence",
        "Deep learning uses neural networks with multiple layers",
        "Natural language processing enables computers to understand text",
    ],
)

for i, item in enumerate(response.data):
    print(f"Embedding {i}: {len(item.embedding)} dimensions")

多模态输入（图片＋文本）

支持图片输入的模型（output_modalities 含 "embeddings"、inputModalities 含 "image"）接受 {content:[{type:"text",...}, {type:"image_url",...}]} 形式的输入项，可以单独嵌入图片，或图片与文本一起嵌入。

取决于模型

只有部分嵌入模型接受图片输入 —— 发送 image_url 内容前，请先在 Models 页面确认该模型支持的模态。纯文本模型会拒绝这种格式。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
import requests

response = requests.post(
    "https://api.bazaarlink.ai/v1/embeddings",
    headers={
        "Authorization": "Bearer sk-bl-YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "model": "google/gemini-embedding-2-preview",
        "input": [{
            "content": [
                {"type": "text", "text": "A scenic boardwalk through a green meadow"},
                {"type": "image_url", "image_url": {"url": "https://example.com/boardwalk.jpg"}},
            ]
        }],
        "encoding_format": "float",
    },
)

embedding = response.json()["data"][0]["embedding"]
print(f"Embedding dimension: {len(embedding)}")

查找嵌入模型

没有专门的嵌入模型列表端点 —— 调用 GET /v1/models，在前端筛选 output_modalities 包含 "embeddings" 的条目，或直接前往 Models 页面浏览。

限制

不支持流式传输 —— 与 chat completions 不同，嵌入向量始终以完整响应形式返回。
每个模型都有输入长度上限；超过上限的文本会在上游被截断或拒绝。
相同输入的嵌入结果是确定性的（deterministic）—— 不涉及 temperature 或随机性。

最佳实践

根据速度／质量／成本的取舍选择模型 —— 较小的模型（如 qwen/qwen3-embedding-4b）更便宜更快；较大的模型（如 openai/text-embedding-3-large）通常嵌入精度更高。
把多段文本合并为一次请求，而不是逐条调用 —— 减少往返次数与额外开销。
缓存结果 —— 相同输入的嵌入结果永远不变，应该存储起来而不是重新生成。
比较时用余弦相似度（cosine similarity），而不是欧氏距离 —— 具有尺度不变性，对高维向量效果更好。
留意每个模型的上下文长度 —— 长文档在嵌入前可能需要先分块（chunking）。