Embeddings API — TokSpan 文件

端點

http
POST https://api.tokspan.com/v1/embeddings

請求參數

參數	類型	必要	說明
model	string	是	Embedding 模型 ID（例如 `text-embedding-3-large`、`text-embedding-3-small`、`voyage-3`）
input	string / array	是	要進行 Embedding 的文字。傳遞字串以獲取單一 Embedding，或傳遞字串陣列進行批次處理（每次請求最多 2048 個項目）。
dimensions	integer	否	降低輸出維度以節省儲存空間並提升搜尋速度。text-embedding-3 模型支援。必須小於等於模型的最大維度。
encoding_format	string	否	`"float"`（預設）或 `"base64"` 用於緊湊傳輸。
user	string	否	用於濫用監控的最終使用者識別碼。

單一 Embedding

from openai import OpenAI

client = OpenAI(
    api_key="sk-your-key",
    base_url="https://api.tokspan.com/v1",
)

response = client.embeddings.create(
    model="text-embedding-3-large",
    input="Your text string for embedding",
    dimensions=1024,  # Optional: reduce dimensions
)

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

批次 Embedding

在單一請求中發送最多 2048 個輸入以獲得最大吞吐量。回應保持輸入順序 — response.data[0] 對應 input[0]。

python
# Batch embedding — process up to 2048 inputs per request
texts = ["First document", "Second document", "Third document"]

response = client.embeddings.create(
    model="text-embedding-3-large",
    input=texts,
    dimensions=1024,
)

for i, data in enumerate(response.data):
    print(f"Text {i}: vector[:5] = {data.embedding[:5]}...")

維度縮減

如 text-embedding-3-large（最大 3072 維度）和 text-embedding-3-small（最大 1536 維度）等模型支援透過 dimensions 參數降低輸出維度。

為何要降低維度？

更小的儲存空間：256 維度的向量比 3072 維度節省 12 倍空間
更快的搜尋速度：越少維度 = 越快的餘弦相似度計算
足夠的品質：對於大多數用例，256–512 維度可保留約 95% 以上的語義品質

維度	儲存空間（每百萬向量）	品質	最適合
256	~1 GB	良好	大規模搜尋、成本敏感應用
512	~2 GB	優秀	通用 RAG 和語義搜尋
1024	~4 GB	卓越	高精度搜尋、聚類分析
3072	~12 GB	最高	最高精度、小型語料庫

語義搜尋方案

python
import numpy as np

def cosine_similarity(a, b):
    return np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b))

# Embed your document corpus (do this once, store results)
doc_embeddings = client.embeddings.create(model="text-embedding-3-large", input=documents)

# Embed a search query
query_embedding = client.embeddings.create(model="text-embedding-3-large", input="How do I reset my password?")

# Find most similar documents
scores = [cosine_similarity(query_embedding.data[0].embedding, d.embedding) for d in doc_embeddings.data]
top_idx = np.argmax(scores)
print(f"Best match: {documents[top_idx]} (score: {scores[top_idx]:.3f})")

專業提示：在生產環境 RAG 中，將 Embeddings 與 Rerank 搭配使用，實作兩階段管線：先用 Embeddings 進行粗略檢索（快速且便宜），再對前 20–50 筆結果進行精確重排序。

可用模型

模型	供應商	最大維度	最適合
text-embedding-3-large	OpenAI	3072	最高精度、靈活的維度縮減
text-embedding-3-small	OpenAI	1536	成本效益高、品質良好
Cohere Embed v3	Cohere	1024	多語言、強大搜尋效能
Voyage AI	Voyage	1024 / 2048	程式碼和法律文件 Embedding
BGE-M3	BAAI	1024	開源、多語言、適合自託管

請參閱模型頁面了解完整目錄及目前每 Token 定價。