章節導覽

嵌入向量

嵌入向量（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）。