Embeddings

Embeddings

Embeddings là biểu diễn số học của văn bản nắm bắt ý nghĩa ngữ nghĩa — chuyển văn bản thành vector (dãy số) có thể dùng cho nhiều tác vụ machine learning. BazaarLink cung cấp một endpoint thống nhất, tương thích với OpenAI Embeddings API, để bạn gọi các mô hình embedding từ nhiều nhà cung cấp qua một giao diện duy nhất.

Phản hồi embedding dùng BazaarLink request ID opaque trùng với x-request-id; dùng nó với GET /v1/generation. Phản hồi không stream cũng có cùng ID trong x-generation-id. usage.cost là số tiền USD đã tính cho khách hàng cho yêu cầu này. Số liệu có thể xuất hiện sau vài giây khi hoàn tất; thử lại 404 trong thời gian ngắn.

Embeddings là gì?

Embeddings biến văn bản thành vector nhiều chiều, trong đó các văn bản có ý nghĩa tương tự nằm gần nhau hơn trong không gian vector — ví dụ, "cat" và "kitten" sẽ có embedding tương tự nhau, còn "cat" và "airplane" sẽ cách xa nhau. Các biểu diễn vector này giúp máy hiểu được mối quan hệ giữa các đoạn văn bản, là nền tảng của nhiều ứng dụng AI.

Các trường hợp sử dụng phổ biến

Tham số

Yêu Cầu Cơ Bản

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

Xử Lý Hàng Loạt

Gửi một mảng chuỗi để embedding nhiều văn bản trong một yêu cầu duy nhất — rẻ hơn và nhanh hơn so với gọi riêng cho từng văn bản.

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")

Đầu Vào Đa Phương Thức (Hình Ảnh + Văn Bản)

Các mô hình hỗ trợ đầu vào hình ảnh (output_modalities gồm "embeddings" và inputModalities gồm "image") chấp nhận các mục đầu vào có dạng {content:[{type:"text",...}, {type:"image_url",...}]}, cho phép bạn embedding riêng một hình ảnh hoặc kết hợp cùng văn bản.

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)}")

Tìm Mô Hình Embedding

Không có endpoint riêng để liệt kê mô hình embedding — gọi GET /v1/models rồi lọc phía client các mục có output_modalities chứa "embeddings", hoặc duyệt trang Models.

Giới Hạn

• Không hỗ trợ streaming — embeddings luôn được trả về dưới dạng phản hồi hoàn chỉnh, khác với chat completions.
• Mỗi mô hình có độ dài đầu vào tối đa; văn bản vượt quá giới hạn đó sẽ bị cắt bớt hoặc từ chối ở upstream.
• Embeddings cho cùng một đầu vào là tất định (deterministic) — không có temperature hay tính ngẫu nhiên.

Thực Hành Tốt Nhất

• Chọn mô hình theo cân bằng tốc độ/chất lượng/chi phí — mô hình nhỏ hơn (ví dụ qwen/qwen3-embedding-4b) rẻ và nhanh hơn; mô hình lớn hơn (ví dụ openai/text-embedding-3-large) thường embedding với độ chính xác cao hơn.
• Gộp nhiều văn bản vào một yêu cầu thay vì gọi riêng cho từng văn bản — giảm số lượt round trip và overhead.
• Lưu cache kết quả — embedding của cùng một đầu vào không bao giờ thay đổi, nên lưu lại thay vì tạo lại.
• So sánh bằng cosine similarity thay vì khoảng cách Euclidean — bất biến theo tỷ lệ và hoạt động tốt hơn với vector nhiều chiều.
• Chú ý độ dài ngữ cảnh của từng mô hình — tài liệu dài có thể cần chia nhỏ (chunking) trước khi embedding.