Embeddings

Embeddings adalah representasi numerik teks yang menangkap makna semantik — mengubah teks menjadi vektor (deretan angka) yang dapat digunakan untuk berbagai tugas machine learning. BazaarLink menyediakan endpoint terpadu yang kompatibel dengan OpenAI Embeddings API, sehingga Anda dapat memanggil model embedding dari berbagai penyedia melalui satu antarmuka.

Respons embedding menggunakan ID permintaan BazaarLink yang buram dan sama dengan x-request-id; gunakan ID ini pada GET /v1/generation. Respons non-streaming juga mengembalikan ID yang sama di x-generation-id. usage.cost adalah jumlah USD yang ditagihkan kepada pelanggan untuk permintaan ini. Statistik dapat muncul beberapa detik setelah selesai; coba lagi sebentar jika mendapat 404.

Apa itu Embeddings?

Embeddings mengubah teks menjadi vektor berdimensi tinggi, di mana teks yang secara semantik mirip akan berdekatan dalam ruang vektor — misalnya, "kucing" dan "anak kucing" akan memiliki embedding yang mirip, sedangkan "kucing" dan "pesawat" akan sangat berjauhan. Representasi vektor ini memungkinkan mesin memahami hubungan antar teks, menjadikannya fondasi banyak aplikasi AI.

Kasus Penggunaan Umum

Kasus Penggunaan

Deskripsi

RAG (Generasi Augmented Pengambilan)Membangun sistem yang mengambil konteks relevan dari basis pengetahuan sebelum menghasilkan jawaban — embeddings menemukan dokumen paling relevan untuk disertakan dalam konteks LLM.

Pencarian SemantikMengubah dokumen dan kueri menjadi embeddings, lalu menemukan dokumen paling relevan berdasarkan kemiripan vektor — memahami makna, bukan sekadar mencocokkan kata kunci, sehingga hasilnya lebih baik daripada pencarian kata kunci.

Sistem RekomendasiMenghasilkan embeddings untuk item (produk, artikel, video) dan preferensi pengguna untuk merekomendasikan item serupa — perbandingan vektor menemukan item yang terkait secara semantik meskipun tidak ada kata kunci yang sama.

Clustering & KlasifikasiMengelompokkan dokumen serupa atau mengklasifikasikan teks dengan menganalisis pola embedding — dokumen dengan embedding serupa biasanya termasuk topik atau kategori yang sama.

Deteksi DuplikatMenemukan konten duplikat atau hampir duplikat dengan membandingkan kemiripan embedding — tetap berfungsi meskipun konten telah diparafrasekan.

Deteksi AnomaliMengenali konten yang tidak biasa atau outlier dengan mengidentifikasi embedding yang menyimpang jauh dari pola umum dataset.

POST/v1/embeddings

Note

Jika sumber upstream tidak mendukung model embeddings yang diminta, permintaan dapat mencoba sumber lain yang tersedia. Jika tidak ada yang mendukungnya, permintaan menghasilkan error.

Parameter

modelwajib

string

Model embedding yang digunakan, mis. "openai/text-embedding-3-small".

inputwajib

string | string[] | ContentItem[]

Teks yang akan di-embed — satu string, array string untuk satu panggilan batch, atau (untuk model yang mendukung) array item {content:[...]} yang menggabungkan bagian text dan image_url.

dimensions

integer

Ukuran vektor output yang diminta. Hanya dihormati oleh model yang mendukung dimensi variabel (mis. keluarga OpenAI text-embedding-3); diteruskan apa adanya ke penyedia upstream dan diabaikan oleh model yang tidak mendukungnya.

encoding_format

string

Format encoding embedding yang diminta, mis. "float" atau "base64". Diteruskan apa adanya ke penyedia upstream — dukungan tergantung pada model.

provider

object

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

Permintaan Dasar

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

Pemrosesan Batch

Kirim array string untuk meng-embed beberapa teks dalam satu permintaan — lebih murah dan cepat daripada satu panggilan per teks.

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

Input Multimodal (Gambar + Teks)

Model dengan dukungan input gambar (output_modalities mencakup "embeddings" dan inputModalities mencakup "image") menerima item input berbentuk {content:[{type:"text",...}, {type:"image_url",...}]}, memungkinkan Anda meng-embed gambar sendiri atau bersama teks.

Tergantung model

Hanya sebagian model embedding yang menerima input gambar — periksa modalitas yang didukung model di halaman Models sebelum mengirim konten image_url. Model teks-saja akan menolak bentuk ini.

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

Menemukan Model Embedding

Tidak ada endpoint khusus untuk mendaftar model embedding — panggil GET /v1/models lalu filter di sisi klien untuk entri yang output_modalities-nya mencakup "embeddings", atau jelajahi halaman Models.

Keterbatasan

Tidak ada streaming — embedding selalu dikembalikan sebagai respons lengkap, berbeda dengan chat completions.
Setiap model punya panjang input maksimum; teks yang melebihi batas akan dipotong atau ditolak di upstream.
Embedding untuk input yang identik bersifat deterministik — tidak ada temperature atau keacakan.

Praktik Terbaik

Pilih model sesuai trade-off kecepatan/kualitas/biaya — model lebih kecil (mis. qwen/qwen3-embedding-4b) lebih murah dan cepat; model lebih besar (mis. openai/text-embedding-3-large) umumnya meng-embed dengan fidelitas lebih tinggi.
Gabungkan beberapa teks dalam satu permintaan alih-alih satu panggilan per teks — lebih sedikit round trip, overhead lebih rendah.
Simpan hasil (cache) — embedding untuk input yang sama tidak pernah berubah, jadi simpan alih-alih membuatnya ulang.
Bandingkan dengan cosine similarity, bukan Euclidean distance — bersifat scale-invariant dan lebih baik untuk vektor berdimensi tinggi.
Perhatikan context length setiap model — dokumen panjang mungkin perlu dipecah (chunking) sebelum di-embed.