Embeddings API
Chuyển văn bản thành vector số (embeddings) để tìm kiếm ngữ nghĩa, RAG pipeline, phân cụm nội dung và đo độ tương đồng.
Xem nhanh cách dùng Embeddings + Rerank + Chat để dựng một RAG mini khoảng 40 dòng Python:
Endpoint
POST https://platform.beeknoee.com/v1/embeddings
Request
Headers
| Header | Value | Required |
|---|---|---|
Authorization | Bearer YOUR_API_KEY | ✅ |
Content-Type | application/json | ✅ |
Body Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
model | string | ✅ | Model ID (VD: gemini-embedding-001, text-embedding-3-small, voyageai/voyage-4, baai/bge-m3) — xem danh sách ở dưới |
input | string hoặc array | ✅ | Văn bản cần chuyển thành vector: 1 chuỗi, hoặc mảng chuỗi (mỗi phần tử ra 1 vector, cùng thứ tự). Mỗi phần tử không dài quá ngữ cảnh của model (ghi trên thẻ model) — vượt thì nhận lỗi 400, không trừ tiền |
encoding_format | string | ❌ | Định dạng output: float (default) hoặc base64 |
dimensions | number | ❌ | Rút ngắn số chiều vector — chỉ model OpenAI text-embedding-3-*. Model khác không nhận tham số này: đừng gửi |
Models khả dụng
Danh sách đầy đủ, số chiều, ngữ cảnh tối đa và giá: Text & Embedding Models → tab Embedding — đó là nơi duy nhất luôn khớp với bảng giá đang chạy, docs cố ý không chép số. Có hơn 30 model, chia thành ba nhóm:
Google — có suất miễn phí mỗi ngày
gemini-embedding-001 và gemini-embedding-2 — 3072 chiều, ngữ cảnh 2K / 8K token. Đa ngôn ngữ, tiếng Việt tốt, và là nhóm duy nhất có suất miễn phí hằng ngày (xem Free Quota).
OpenAI
text-embedding-3-small (1536 chiều), text-embedding-3-large (3072 chiều), openai/text-embedding-ada-002 (1536 chiều) — ngữ cảnh 8K token. Dùng khi bạn đang trong hệ sinh thái OpenAI hoặc cần rút ngắn vector bằng dimensions.
Đa hãng (từ 03/10/2026)
| Hãng | Model ID | Ngữ cảnh | Thế mạnh |
|---|---|---|---|
| Voyage AI | voyageai/voyage-4 · voyage-4-lite · voyage-4-large · voyage-code-4 · voyage-multimodal-3.5 | 32K | Tìm kiếm chất lượng cao; voyage-code-4 cho mã nguồn |
| Qwen | qwen/qwen3-embedding-4b (2560 chiều) · qwen3-embedding-8b (4096 chiều) | 32K | Đa ngôn ngữ, chất lượng cao, giá tốt |
| Mistral | mistralai/mistral-embed-2312 · codestral-embed-2505 | 8K | codestral-embed cho mã nguồn |
| Perplexity | perplexity/pplx-embed-v1-0.6b · pplx-embed-v1-4b | 32K | Tìm kiếm web / tài liệu dài |
| NVIDIA | nvidia/nemotron-3-embed-1b:free · llama-nemotron-embed-vl-1b-v2:free | 32K / 131K | Ngữ cảnh rất dài, giá thấp |
| BAAI | baai/bge-m3 (đa ngôn ngữ, 8K) · bge-base-en-v1.5 · bge-large-en-v1.5 | 8K / 512 | bge-m3 là lựa chọn đa ngôn ngữ rẻ và mạnh |
| E5 / GTE | intfloat/multilingual-e5-large · e5-base-v2 · e5-large-v2 · thenlper/gte-base · gte-large | 512 | Rẻ, đoạn văn ngắn; multilingual-e5-large có tiếng Việt |
| Sentence Transformers | sentence-transformers/all-minilm-l6-v2 · all-minilm-l12-v2 · all-mpnet-base-v2 · multi-qa-mpnet-base-dot-v1 · paraphrase-minilm-l6-v2 | 512 | Rẻ nhất, tiếng Anh, khối lượng lớn |
| LiquidAI | liquid/lfm-2.5-embedding-350m:free | 512 | Model nhỏ, giá thấp |
Gọi model nào cũng cùng một endpoint, cùng khuôn request/response ở trên — chỉ đổi model. Số chiều, ngữ cảnh và giá chính xác của từng model ghi trên thẻ model.
💡 Chọn nhanh: muốn miễn phí để bắt đầu ⇒
gemini-embedding-001. Tiếng Việt / đa ngôn ngữ, chất lượng cao ⇒voyageai/voyage-4hoặcqwen/qwen3-embedding-8b. Mã nguồn ⇒voyageai/voyage-code-4. Hàng triệu đoạn văn, cần rẻ nhất ⇒sentence-transformers/all-minilm-l6-v2(tiếng Anh) hoặcbaai/bge-m3(đa ngôn ngữ). Lưu ý: vector của hai model khác nhau không so sánh được với nhau — đổi model là phải tạo lại toàn bộ vector đã lưu.
Response
Success Response
{
"object": "list",
"data": [
{
"object": "embedding",
"index": 0,
"embedding": [0.0023064255, -0.009327292, 0.015797347, ...]
}
],
"model": "gemini-embedding-001",
"usage": {
"prompt_tokens": 5,
"total_tokens": 5
}
}
Response Fields
| Field | Description |
|---|---|
data | Array chứa kết quả embedding |
data[].embedding | Vector số (array of floats) |
data[].index | Index tương ứng với input text |
model | Model đã sử dụng |
usage.prompt_tokens | Số token đầu vào đã tính tiền (cũng là usage.total_tokens) |
Ví dụ
1. Basic Embedding
curl -X POST https://platform.beeknoee.com/v1/embeddings \
-H "Authorization: Bearer sk-bee-your-key" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-embedding-001",
"input": "Beeknoee là nền tảng AI proxy tốt nhất Việt Nam"
}'
from openai import OpenAI
client = OpenAI(
api_key="sk-bee-your-key",
base_url="https://platform.beeknoee.com/v1"
)
# Tạo embedding cho 1 văn bản
response = client.embeddings.create(
model="gemini-embedding-001",
input="Trí tuệ nhân tạo đang thay đổi thế giới"
)
vector = response.data[0].embedding
print(f"Dimensions: {len(vector)}") # 3072
print(f"First 5 values: {vector[:5]}")
import OpenAI from 'openai';
const client = new OpenAI({
apiKey: 'sk-bee-your-key',
baseURL: 'https://platform.beeknoee.com/v1',
});
const response = await client.embeddings.create({
model: 'gemini-embedding-001',
input: 'Trí tuệ nhân tạo đang thay đổi thế giới',
});
const vector = response.data[0].embedding;
console.log(`Dimensions: ${vector.length}`); // 3072
2. Batch Embeddings — nhiều văn bản cùng lúc
from openai import OpenAI
client = OpenAI(
api_key="sk-bee-your-key",
base_url="https://platform.beeknoee.com/v1"
)
texts = [
"Cách nấu phở bò Hà Nội",
"Hướng dẫn lập trình Python cơ bản",
"Đánh giá iPhone 16 Pro Max",
"Top 10 địa điểm du lịch Đà Nẵng"
]
response = client.embeddings.create(
model="gemini-embedding-001",
input=texts
)
for i, item in enumerate(response.data):
print(f"Text {i}: {len(item.embedding)} dimensions")
3. Tìm kiếm ngữ nghĩa (Semantic Search)
import numpy as np
from openai import OpenAI
client = OpenAI(
api_key="sk-bee-your-key",
base_url="https://platform.beeknoee.com/v1"
)
# Bước 1: Tạo embeddings cho kho tài liệu
documents = [
"Python là ngôn ngữ lập trình phổ biến nhất thế giới",
"Cách nấu bún bò Huế ngon đúng vị",
"React và Next.js là framework frontend hàng đầu",
"Hà Nội là thủ đô của Việt Nam với lịch sử nghìn năm",
"Machine Learning giúp máy tính học từ dữ liệu",
]
doc_response = client.embeddings.create(
model="gemini-embedding-001",
input=documents
)
doc_vectors = [item.embedding for item in doc_response.data]
# Bước 2: Tạo embedding cho câu hỏi
query = "làm sao để học code?"
query_response = client.embeddings.create(
model="gemini-embedding-001",
input=query
)
query_vector = query_response.data[0].embedding
# Bước 3: Tính cosine similarity
def cosine_similarity(a, b):
return np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b))
scores = [cosine_similarity(query_vector, doc_vec) for doc_vec in doc_vectors]
# Bước 4: Sắp xếp theo điểm cao nhất
results = sorted(zip(documents, scores), key=lambda x: x[1], reverse=True)
print("🔍 Kết quả tìm kiếm cho:", query)
for doc, score in results[:3]:
print(f" [{score:.4f}] {doc}")
# Output:
# 🔍 Kết quả tìm kiếm cho: làm sao để học code?
# [0.8234] Python là ngôn ngữ lập trình phổ biến nhất thế giới
# [0.7891] React và Next.js là framework frontend hàng đầu
# [0.6123] Machine Learning giúp máy tính học từ dữ liệu
4. RAG Pipeline — kết hợp với Chat Completions
from openai import OpenAI
client = OpenAI(
api_key="sk-bee-your-key",
base_url="https://platform.beeknoee.com/v1"
)
# Bước 1: Tìm tài liệu liên quan (dùng embeddings)
def find_relevant_docs(query, documents, doc_vectors, top_k=3):
query_resp = client.embeddings.create(
model="gemini-embedding-001",
input=query
)
query_vec = query_resp.data[0].embedding
import numpy as np
scores = [np.dot(query_vec, dv) / (np.linalg.norm(query_vec) * np.linalg.norm(dv))
for dv in doc_vectors]
ranked = sorted(zip(documents, scores), key=lambda x: x[1], reverse=True)
return [doc for doc, _ in ranked[:top_k]]
# Bước 2: Gửi context + câu hỏi tới Chat Completions
relevant = find_relevant_docs("làm sao deploy Next.js?", documents, doc_vectors)
context = "\n".join(f"- {doc}" for doc in relevant)
response = client.chat.completions.create(
model="deepseek/deepseek-v3.2",
messages=[
{"role": "system", "content": f"Trả lời dựa trên context sau:\n{context}"},
{"role": "user", "content": "làm sao deploy Next.js?"}
]
)
print(response.choices[0].message.content)
Free Quota
Mỗi ngày, bạn được gọi miễn phí các model Google (gemini-embedding-001, gemini-embedding-2) theo plan:
| Plan | Free Requests/ngày |
|---|---|
| FREE | 50 |
| BASIC | 100 |
| ADVANCED+ / ULTRA | 200 |
- Free quota tự động reset hàng ngày lúc 0:00 (UTC+7)
- Khi hết free quota → tự động tính phí vào ví VNĐ (ví không đủ ⇒ lỗi
400 insufficient_balance, không trừ tiền) - Quota hiển thị realtime trên trang Text & Embedding Models
- Các model OpenAI và đa hãng không có suất miễn phí — tính tiền ngay từ lượt đầu, nhưng giá rất thấp (xem thẻ model)
Billing — Cách tính phí
- Tính theo số token đầu vào (
usage.total_tokenstrong response) × đơn giá / 1M token của model — đầu ra (vector) không tính - Trước khi gọi, hệ thống giữ chỗ theo ước tính (nghiêng về dư) rồi trừ đúng số token thật sau khi có kết quả; lượt lỗi không bị trừ tiền
- Trừ trực tiếp vào ví VNĐ. Giá từng model xem tại Text & Embedding Models; số tiền của từng lần gọi nằm ở API Usage
Tích hợp với LangChain
from langchain_openai import OpenAIEmbeddings
embeddings = OpenAIEmbeddings(
model="gemini-embedding-001",
openai_api_key="sk-bee-your-key",
openai_api_base="https://platform.beeknoee.com/v1"
)
# Sử dụng với FAISS vector store
from langchain_community.vectorstores import FAISS
texts = ["Tài liệu 1...", "Tài liệu 2...", "Tài liệu 3..."]
vectorstore = FAISS.from_texts(texts, embeddings)
# Tìm kiếm
results = vectorstore.similarity_search("query của bạn", k=3)
Tích hợp với LlamaIndex
from llama_index.embeddings.openai import OpenAIEmbedding
from llama_index.core import Settings
Settings.embed_model = OpenAIEmbedding(
model="gemini-embedding-001",
api_key="sk-bee-your-key",
api_base="https://platform.beeknoee.com/v1"
)
# Sử dụng với VectorStoreIndex
from llama_index.core import VectorStoreIndex, SimpleDirectoryReader
documents = SimpleDirectoryReader("data").load_data()
index = VectorStoreIndex.from_documents(documents)
query_engine = index.as_query_engine()
response = query_engine.query("Hỏi gì đó?")
Error Handling
| HTTP | error.code | Ý nghĩa | Trừ tiền? |
|---|---|---|---|
| 400 | invalid_request | input rỗng, phần tử không phải chuỗi, văn bản dài quá ngữ cảnh của model, hoặc model từ chối request — message ghi rõ lý do | ❌ Không |
| 400 | insufficient_balance | Hết free quota (model Google) và ví không đủ cho ước tính lượt này | ❌ Không |
| 401 | invalid_api_key | API key không hợp lệ hoặc đã thu hồi | ❌ Không |
| 403 | insufficient_permissions | API key bị giới hạn danh sách model, không gồm model này | ❌ Không |
| 404 | model_not_found | Model không có / đã tắt — xem GET /models/embeddings (gửi sai tên liên tục ⇒ 429) | ❌ Không |
| 429 | rate_limit_exceeded | Vượt RPM/RPD của gói, hoặc model đang quá tải — thử lại sau Retry-After giây | ❌ Không |
| 502 / 503 / 504 | unknown_error (type: server_error) | Model tạm lỗi / hết giờ — thử lại sau hoặc đổi model | ❌ Không |
import time
from openai import OpenAI, RateLimitError
client = OpenAI(
api_key="sk-bee-your-key",
base_url="https://platform.beeknoee.com/v1"
)
def embed_with_retry(text, max_retries=3):
for attempt in range(max_retries):
try:
response = client.embeddings.create(
model="gemini-embedding-001",
input=text
)
return response.data[0].embedding
except RateLimitError:
wait = 2 ** attempt # Exponential backoff
print(f"Rate limited, waiting {wait}s...")
time.sleep(wait)
raise Exception("Max retries exceeded")
Best Practices
- Batch requests — Gửi nhiều texts trong 1 request thay vì gọi nhiều lần
- Cache embeddings — Lưu vectors vào database, không cần tạo lại mỗi lần
- Chọn model phù hợp —
gemini-embedding-001miễn phí & đa ngôn ngữ;voyageai/voyage-4/qwen/qwen3-embedding-8bchất lượng cao; MiniLM / BAAI base khi cần rẻ nhất. Chọn xong thì giữ nguyên — vector của model khác nhau không so được với nhau - Normalize vectors — Một số vector store yêu cầu normalize trước khi lưu
- Chunk text hợp lý — Chia văn bản dài thành các đoạn 200-500 từ để embedding chính xác hơn
Tiếp theo
- Rerank — Xếp lại kết quả tìm bằng embeddings theo độ liên quan thật (bước 2 của RAG)
- Decisions — Phân loại / định tuyến bằng đáp án có xác suất, không cần bóc nhãn từ văn bản
- Chat Completions — Kết hợp embeddings với chat để tạo RAG
- Text Models — Chọn model chat phù hợp cho RAG pipeline
- API Usage — Theo dõi chi phí embedding