Embeddings

POST https://tokens.bd/v1/embeddings হলো OpenAI-compatible embeddings endpoint। আপনি text পাঠান, প্রতিটা input-এর জন্য একটা করে vector ফেরত পান। এই vector জমিয়ে রেখে semantic search, RAG-এর retrieval, duplicate খোঁজা বা clustering-এ ব্যবহার করা যায়। gateway আগে আপনার key, plan আর সীমা যাচাই করে, তারপর body-টা যে model-এর নাম দিয়েছেন তার upstream provider-এর কাছে পাঠিয়ে দেয়।

এই endpoint শুধু embedding model-এর সাথে চলে। deepseek/deepseek-v4.1-flash-এর মতো chat model এখানে কাজ করে না, পাঠালে fail করবে। তাই আগে পরের section-টা পড়ে নিন।

Embedding model খুঁজে নেওয়া#

Tokens GET /v1/models-এ কোনো capability flag যোগ করে না, তাই ওই list-এ শুধু id-ই থাকে। embedding model খুঁজতে এভাবে এগোন:

1. model catalog খুলে embed লিখে search করুন। search মেলে model-এর নাম, id আর provider ধরে।
2. model-এর পেজ খুলে context window আর প্রতি million token-এর input price দেখে নিন।
3. আপনার key দিয়ে model-টা call করা যায় কি না দেখুন: ওই key-র জন্য GET /v1/models-এ id-টা থাকতে হবে (কোনো model কেন বাদ পড়ে)।

catalog-এ একটাও embedding model না থাকলে বুঝবেন আপনার অ্যাকাউন্টে এখনো কোনোটা চালু নেই, আর /v1/embeddings-এর দেওয়ার মতো কিছু নেই। তালিকায় না আসা পর্যন্ত এখনকার embedding provider-ই ব্যবহার করতে থাকুন। catalog বদলায় বলে এই পেজে কোনো model-এর নাম দেওয়া হয়নি। নিচের উদাহরণগুলো id-টা environment variable থেকে পড়ে নেয়:

export EMBEDDING_MODEL="the-id-from-the-catalog"

Embeddings তৈরি করা#

curl https://tokens.bd/v1/embeddings \
  -H "Authorization: Bearer $TOKENS_API_KEY" \
  -H "Content-Type: application/json" \
  -d @- <<EOF
{
  "model": "$EMBEDDING_MODEL",
  "input": ["How do I reset my password?", "Where can I change my billing email?"],
  "encoding_format": "float"
}
EOF

import os
from openai import OpenAI

client = OpenAI(base_url="https://tokens.bd/v1", api_key=os.environ["TOKENS_API_KEY"])

resp = client.embeddings.create(
    model=os.environ["EMBEDDING_MODEL"],
    input=["How do I reset my password?", "Where can I change my billing email?"],
    encoding_format="float",
)

vectors = [item.embedding for item in resp.data]
print(len(vectors), "vectors of", len(vectors[0]), "numbers")
print(resp.usage)

import OpenAI from "openai";

const client = new OpenAI({ baseURL: "https://tokens.bd/v1", apiKey: process.env.TOKENS_API_KEY });

const resp = await client.embeddings.create({
  model: process.env.EMBEDDING_MODEL!,
  input: ["How do I reset my password?", "Where can I change my billing email?"],
  encoding_format: "float",
});

const vectors = resp.data.map((item) => item.embedding);
console.log(vectors.length, "vectors of", vectors[0].length, "numbers");
console.log(resp.usage);

Content-Type: application/json header-টা ভুলবেন না। এটা না থাকলে gateway body পড়তে পারে না, আর model field দেওয়া থাকলেও 400 invalid_request দিয়ে বলে যে request-এ model field নেই।

Request-এর field#

body চলে OpenAI-র embeddings format মেনে। OpenAI-র API reference-এর সাথে 2026 সালের অক্টোবরে মিলিয়ে দেখা হয়েছে।

request body সব মিলিয়ে 10 MB পর্যন্ত হতে পারে। এর চেয়ে বড় হলে 413 request_entity_too_large আসে।

Python SDK default-এ base64 চায়#

encoding_format না দিলে OpenAI-র Python SDK নিজে থেকে "base64" পাঠায় আর result নিজেই decode করে (SDK-র source দেখে মিলিয়েছি, অক্টোবর 2026)। এটা তখনই চলে, যখন model-এর provider base64 সমর্থন করে। call fail করলে বা vector অদ্ভুত এলে উপরের উদাহরণের মতো encoding_format="float" দিয়ে দিন। Node.js SDK-তেও স্পষ্ট করে দিয়ে দিলে কোনো ক্ষতি নেই।

Response-এর উদাহরণ#

এখানে vector ছোট করে দেখানো হয়েছে। আসল vector-এ শ'য়ে শ'য়ে বা হাজার হাজার সংখ্যা থাকে, তাই request-এর তুলনায় response body অনেক বড় হয়।

{
  "object": "list",
  "data": [
    { "object": "embedding", "index": 0, "embedding": [0.0123, -0.0456, 0.0789] },
    { "object": "embedding", "index": 1, "embedding": [0.0311, -0.0127, 0.0644] }
  ],
  "model": "the-id-from-the-catalog",
  "usage": { "prompt_tokens": 14, "total_tokens": 14 }
}

data-তে প্রতিটা input-এর জন্য একটা করে entry থাকে, একই ক্রমে। index হলো input-টার অবস্থান। body আসে provider থেকে, তাই বাড়তি field আসতে পারে, আর vector কত বড় হবে সেটা model ঠিক করে। completion_tokens নেই, কারণ embedding request কোনো text তৈরি করে না।

দুটো vector তুলনা করা#

একই model-এর vector-গুলো cosine similarity দিয়ে তুলনা করা যায়। Python-এ ছোট একটা উদাহরণ:

import math

def cosine(a, b):
    dot = sum(x * y for x, y in zip(a, b))
    return dot / (math.sqrt(sum(x * x for x in a)) * math.sqrt(sum(y * y for y in b)))

print(cosine(vectors[0], vectors[1]))

আলাদা model-এর vector, বা একই model-এর আলাদা dimensions-এর vector, কখনো একসাথে তুলনা বা index করবেন না। প্রতিটা vector-এর পাশে model-এর id আর dimensions রেখে দিন, তাহলে কখন আবার embed করতে হবে সেটা বোঝা যাবে।

Billing আর সীমা#

• হিসাব। embeddings-এর বিল হয় provider-এর জানানো usage.prompt_tokens ধরে, model-এর প্রতি million token-এর input price-এ। output-এর দিক নেই। প্রতিটা model-এর দাম model catalog আর pricing-এ আছে। provider usage না পাঠালে gateway request আর response-এর size দেখে আন্দাজ করে নেয়।
• max_tokens নেই। chat-এর মতো এখানে output-এর জন্য কিছু আটকে রাখা হয় না। admission শুধু request-এর size থেকে সবচেয়ে খারাপ ক্ষেত্রের খরচ ধরে রাখে, তাই আপনার ব্যালান্স ওই আন্দাজ মেটাতে না পারলে তবেই টাকার অভাবে request ফিরিয়ে দেওয়া হয়। দাম দিতে হয় আসল usage-এর।
• Rate limit। প্রতিটা embeddings request আপনার per-minute limit-এ একটা request হিসেবে গোনা হয় আর চলার সময় একটা concurrency slot ধরে রাখে, request ছোট হোক বা বড়। তাই প্রতি text-এর জন্য আলাদা request না পাঠিয়ে, model-এর provider-এর সীমার ভেতরে অনেকগুলো input এক input array-তে দিন। rate limits পেজ দেখুন।
• Fail করা request-এর বিল হয় না। provider 400 বা তার ওপরের status দিলে সেটা কোনো চার্জ ছাড়াই আপনার কাছে ফেরত আসে।
• Stream হয় না। embeddings-এ stream mode নেই।

Embeddings endpoint-এ chat model দিলে#

এখানে chat model পাঠানোই সবচেয়ে চেনা ভুল। কী দেখবেন, সেটা model-এর provider-এর ওপর নির্ভর করে, Tokens-এর কোনো বাঁধা নিয়ম নেই:

সব ক্ষেত্রেই catalog থেকে একটা embedding model বেছে নিন। upstream-এর message বদলে একটা সাধারণ message বসানো হয়, তাই Support-এর সাথে যোগাযোগ করার সময় x-tokens-request-id header-টা দিন। পুরো তালিকা errors পেজে।

Error#

gateway-র error OpenAI-র error shape-এ আসে, সাথে থাকে একটা code, যা ধরে আপনি branch করতে পারেন। প্রতিটা response-এ x-tokens-request-id header থাকে। এখানে সবচেয়ে বেশি যেগুলো পাবেন:

বড় আকারে bulk indexing চালালে rate limits পেজের মতো backoff সহ retry যোগ করুন, আর একসাথে চলা request-এর সংখ্যা plan-এর concurrency limit-এর নিচে রাখুন।

আরও পড়ুন#

• Chat completions: text তৈরির জন্য।
• Token counting: অনেক বড় corpus embed করার আগে input-এর size আন্দাজ করতে।
• Models and usage: GET /v1/models আর GET /v1/tokens/usage-এর জন্য।