Tham Khảo API

Embeddings

Tạo vector embeddings cho tìm kiếm ngữ nghĩa, RAG, phân cụm và phát hiện tương đồng. Truy cập các mô hình từ OpenAI, Cohere, Voyage, BGE-M3 và nhiều hơn nữa qua một endpoint duy nhất.

Endpoint

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

Tham Số Yêu Cầu

Tham SốKiểuBắt BuộcMô Tả
modelstringCóID mô hình embedding (ví dụ: text-embedding-3-large, text-embedding-3-small, voyage-3)
inputstring / arrayCóVăn bản cần nhúng. Truyền một chuỗi cho một embedding hoặc một mảng chuỗi cho batch (tối đa 2048 mục mỗi yêu cầu).
dimensionsintegerKhôngGiảm số chiều đầu ra để tiết kiệm dung lượng lưu trữ và cải thiện tốc độ tìm kiếm. Được hỗ trợ bởi các mô hình text-embedding-3. Phải ≤ số chiều tối đa của mô hình.
encoding_formatstringKhông"float" (mặc định) hoặc "base64" để truyền tải gọn nhẹ.
userstringKhôngĐịnh danh người dùng cuối cho mục đích giám sát lạm dụng.

Embedding Đơn

python
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 Hàng Loạt

Gửi tối đa 2048 đầu vào trong một yêu cầu duy nhất để đạt thông lượng tối đa. Phản hồi giữ nguyên thứ tự đầu vào — response.data[0] tương ứng với 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]}...")

Giảm Số Chiều

Các mô hình như text-embedding-3-large (tối đa 3072 chiều) và text-embedding-3-small (tối đa 1536 chiều) hỗ trợ giảm số chiều đầu ra thông qua tham số dimensions.

Tại sao nên giảm số chiều?

  • Lưu trữ nhỏ hơn: Một vector 256 chiều sử dụng ít hơn 12 lần dung lượng so với 3072 chiều
  • Tìm kiếm nhanh hơn: Ít chiều hơn = tính toán cosine similarity nhanh hơn
  • Chất lượng đủ tốt: Đối với hầu hết trường hợp sử dụng, 256–512 chiều giữ lại ~95%+ chất lượng ngữ nghĩa
Số ChiềuLưu Trữ (trên 1M vector)Chất LượngPhù Hợp Nhất Cho
256~1 GBTốtTìm kiếm quy mô lớn, ứng dụng nhạy cảm về chi phí
512~2 GBRất TốtRAG đa năng và tìm kiếm ngữ nghĩa
1024~4 GBXuất SắcTìm kiếm độ chính xác cao, phân cụm
3072~12 GBTối ĐaĐộ chính xác tối đa, tập dữ liệu nhỏ
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})")
Mẹo hay: Đối với RAG production, hãy kết hợp embeddings với Rerank để tạo pipeline hai giai đoạn: truy xuất thô bằng embeddings (nhanh + rẻ), sau đó sắp xếp lại chính xác trên 20–50 kết quả hàng đầu.

Mô Hình Khả Dụng

Mô HìnhNhà Cung CấpSố Chiều Tối ĐaPhù Hợp Nhất Cho
text-embedding-3-largeOpenAI3072Độ chính xác tối đa, giảm số chiều linh hoạt
text-embedding-3-smallOpenAI1536Tiết kiệm chi phí, chất lượng tốt
Cohere Embed v3Cohere1024Đa ngôn ngữ, hiệu suất tìm kiếm mạnh mẽ
Voyage AIVoyage1024 / 2048Embeddings cho code và tài liệu pháp lý
BGE-M3BAAI1024Mã nguồn mở, đa ngôn ngữ, thân thiện với tự lưu trữ

Xem trang Mô Hình để biết danh mục đầy đủ với giá theo token hiện tại.