Gọi /v1/embeddings mất khoảng hai mươi dòng code. Phần khó nằm ở chỗ khác: 8.192 token giới hạn mỗi input, hàng trăm nghìn chunk cần backfill, rate limit theo tier, và một ngày bạn đổi model thì toàn bộ index cũ trở nên vô dụng.
Bài này là hướng dẫn thực dụng cho text-embedding-3-small và text-embedding-3-large: gọi API bằng HTTP và Python SDK, batching đúng cách, giảm chiều, xử lý 429, tính chi phí, thiết kế schema, và quy trình nhúng lại khi đổi model.
Mục lục
Cập nhật 2026
- OpenAI vẫn chỉ có hai model embedding:
text-embedding-3-small(1536 chiều) và-large(3072 chiều), cùng input tối đa 8.192 token. Không cótext-embedding-4. - Giá tham khảo ~$0.02 và ~$0.13 cho 1M token. Con số này rẻ đến mức nhiều team bỏ qua phép tính lưu trữ — sai lầm tốn kém hơn.
text-embedding-ada-002là thế hệ cũ; đừng dùng cho dự án mới. SDK Python hiện hành làopenai3.46.0 (2026-11-05).- Batch/Flex giảm khoảng 50% và chạy bất đồng bộ — đúng cho backfill và eval, không phù hợp cho request người dùng đang chờ.
Hai model, chọn cái nào
| Model | Chiều / input / giá 1M token | Dùng khi |
|---|---|---|
text-embedding-3-small |
1536 (cắt được) / 8.192 / ~$0.02 | Mặc định cho search nội bộ, phân loại, dedup quy mô vừa |
text-embedding-3-large |
3072 (cắt được) / 8.192 / ~$0.13 | Corpus lớn, truy vấn tinh, cần chất lượng cao hơn rõ rệt |
Nguyên tắc: bắt đầu bằng 3-small và một tập eval 100–300 truy vấn thật. Chỉ nâng lên 3-large nếu recall@10 còn thiếu và bạn đã loại trừ chunking, hybrid search và rerank. 3-large đắt gấp 6,5 lần và lưu vector gấp đôi; đổi model là đổi cả index, không phải đổi một dòng config.
Gọi API bằng HTTP
curl https://api.openai.com/v1/embeddings \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "text-embedding-3-small",
"input": [
"Chính sách hoàn tiền áp dụng trong 30 ngày.",
"Hướng dẫn cài đặt ứng dụng trên Android."
],
"dimensions": 512
}'
Response có dạng {"object":"list","data":[{"index":0,"embedding":[...]}],"usage":{"prompt_tokens":...,"total_tokens":...}}. Luôn đọc index thay vì giả định thứ tự: API hiện giữ thứ tự, nhưng code dựa vào index sẽ không vỡ nếu điều đó thay đổi. usage là nguồn sự thật duy nhất cho chi phí token; đừng tự ước lượng bằng cách đếm từ.
Gọi bằng Python SDK
# File: embed_openai.py — openai 3.46.0
import os
from openai import OpenAI
client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])
def embed_batch(texts: list[str], dimensions: int = 1536) -> list[list[float]]:
response = client.embeddings.create(
model="text-embedding-3-small",
input=texts,
dimensions=dimensions,
)
# sắp theo index, không theo thứ tự trả về
ordered = sorted(response.data, key=lambda item: item.index)
print("tokens:", response.usage.total_tokens)
return [item.embedding for item in ordered]
vectors = embed_batch([
"Chính sách hoàn tiền áp dụng trong 30 ngày.",
"Hướng dẫn cài đặt ứng dụng trên Android.",
])
print(len(vectors), len(vectors[0])) # 2 1536
Không truyền API key trong code. Với ứng dụng chạy trên server, dùng biến môi trường hoặc secret manager; với worker, inject short-lived credential ở boundary thay vì nhúng vào image.
Batching: theo token, không theo số lượng
API nhận một mảng input trong một request, và giới hạn 8.192 token là cho từng input, không phải cho cả mảng. Nhưng tổng request vẫn có trần token và trần số input theo tier, nên chiến lược đúng là chia lô theo ngân sách token, không theo số phần tử.
- Ước lượng token trước khi gửi bằng
tiktoken; cắt chunk theo token, không theo ký tự. - Giữ mỗi input dưới 8.192 token; đừng dựa vào việc API tự cắt. Một chunk 1.000–1.500 token là hợp lý cho retrieval.
- Bỏ input rỗng hoặc toàn khoảng trắng — chúng vẫn là một phần tử trong lô và làm hỏng tỉ lệ.
- Chọn kích thước lô theo thực nghiệm: bắt đầu vài chục input, tăng đến khi latency hoặc 429 trở thành vấn đề.
- Ghi lại số token thực tế mỗi lô để tính chi phí theo tenant hoặc theo feature.
Với backfill hàng triệu chunk, dùng Batch API thay vì tự viết vòng lặp song song. Batch rẻ hơn khoảng 50%, chạy nền, và tránh việc bạn tự tạo ra một cuộc tấn công rate limit vào chính mình.
Giảm chiều bằng dimensions
Cả hai model hỗ trợ Matryoshka: bạn có thể yêu cầu vector ngắn hơn chiều gốc. Vector 512 chiều chỉ tốn 2 KB float32 thay vì 6 KB, và tìm kiếm nhanh hơn. Nhưng đây là đổi chất lượng lấy dung lượng, không phải phép thuật.
- Chọn 256, 512 hoặc 1024 rồi đo recall@10 trên tập eval; đừng chọn theo cảm giác.
- Giữ nguyên một giá trị chiều cho toàn bộ index. Trộn 512 với 1536 trong cùng một bảng là lỗi schema.
- Kiểm tra norm của vector sau khi nhận. Nếu bạn tự cắt hoặc tự biến đổi vector, hãy chuẩn hóa lại trước khi dùng cosine.
- Nếu sau này tăng chiều, bạn phải nhúng lại — vector 512 không “nở” thành 1536.
Một lợi ích ít người dùng: giảm chiều là cách thử nhanh xem model có phù hợp domain không. Nếu 512 chiều đã đạt recall mục tiêu, 3072 chiều thường là chi phí không cần thiết.
Rate limit, retry và lỗi
- Đọc
429cùng headerRetry-After; backoff lũy thừa có jitter, có giới hạn số lần thử. - Chỉ retry lỗi tạm thời (429, 5xx, timeout mạng). Không retry
400,401,403— retry chỉ che lỗi cấu hình. - Idempotency: mỗi lô có khóa (model, dims, hash nội dung) để chạy lại không tạo bản ghi trùng.
- Rate limit của OpenAI tính theo tier và theo cả RPM lẫn TPM. Đừng hard-code con số từ blog; đọc dashboard của tài khoản bạn.
- Khi bị giới hạn, giảm đồng thời cả kích thước lô và số worker; tăng worker sẽ làm mọi thứ tệ hơn.
Chi phí: ba dòng, không phải một
Chi phí API: 1M token khoảng $0.02 với 3-small. Một corpus 10M token tốn khoảng $0.20 để nhúng — rẻ. Chi phí lưu trữ mới là khoản lớn: 10M chunk × 1536 chiều × 4 byte ≈ 61 GB vector, chưa tính index HNSW và metadata.
Chi phí thứ ba ít được tính: nhúng lại. Mỗi lần đổi model hoặc đổi chiều, bạn trả lại toàn bộ. 10M token là $0.20; 10B token là $200 chỉ cho một lần backfill, cộng thời gian và hạ tầng. Vì vậy hãy coi model embedding là một phần của schema, không phải một tham số có thể đổi tùy ý.
Một phép tính nhỏ để tránh nhầm: 1536 chiều float32 = 6.144 byte ≈ 6 KB mỗi vector; 3072 chiều ≈ 12 KB. Nếu lưu float64, con số gấp đôi mà chất lượng không tăng.
Cache: đừng trả tiền hai lần cho cùng một chunk
Embedding của một đoạn văn bản là hàm thuần túy của (model, dims, nội dung). Vì vậy cache theo hash nội dung là an toàn và rẻ:
- Tính hash của text đã chuẩn hóa (trim, gộp khoảng trắng) + model + dims.
- Tra cache trước khi gọi API; chỉ gọi cho phần chưa có.
- Cache trong DB hoặc Redis, TTL dài cho tài liệu tĩnh; invalidate khi nội dung đổi.
- Không cache embedding của query theo kiểu “gần đúng” — một query khác nghĩa có thể trùng hash sau khi chuẩn hóa.
Với pipeline tài liệu, cache thường giảm 60–90% số token phải trả trong những lần chạy lại sau sự cố, vì phần lớn chunk không đổi. Đây là khoản tiết kiệm dễ nhất và ít rủi ro nhất.
Schema lưu vector
-- PostgreSQL + pgvector 0.8.7
CREATE TABLE chunks (
id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
doc_id text NOT NULL,
chunk_index int NOT NULL,
content text NOT NULL,
content_hash text NOT NULL,
model text NOT NULL,
dims int NOT NULL,
embedding vector(1536) NOT NULL,
created_at timestamptz NOT NULL DEFAULT now(),
UNIQUE (doc_id, chunk_index, model, dims)
);
CREATE INDEX chunks_embedding_hnsw
ON chunks USING hnsw (embedding vector_cosine_ops);
Bốn cột không được bỏ: model, dims, content_hash, created_at. Thiếu chúng, bạn không thể biết vector nào thuộc phiên bản nào, không thể dedup lần nhúng, và không thể chạy hai index song song khi migration.
Nếu corpus lớn, đặt khóa ngoại và partition theo model hoặc theo tháng; nhưng đừng partition trước khi có số đo. Với dưới vài triệu chunk, một bảng và một index HNSW là đủ.
Nhúng lại khi đổi model
Đây là quy trình nên viết thành runbook, không phải làm ứng biến:
- Đo trước. Chạy model mới trên 100–300 query đã gán nhãn, so recall@10 với model cũ. Không đổi nếu không có cải thiện đo được.
- Ghi song song. Thêm cột hoặc bảng cho model mới; backfill bằng Batch API; không ghi đè vector cũ.
- Đánh index riêng. Index mới có tên riêng để có thể bật/tắt độc lập.
- So sánh online. Chuyển một phần traffic, đo p95 latency, chi phí, và tỉ lệ click hoặc tỉ lệ trả lời đúng.
- Cutover và giữ rollback. Chỉ xóa index cũ sau khi model mới chạy ổn định qua một chu kỳ nghiệp vụ.
Đừng trộn vector của hai model trong cùng một index dù chúng cùng số chiều. Khoảng cách giữa hai không gian khác nhau không có ý nghĩa, và kết quả sẽ tệ một cách khó chẩn đoán.
Lỗi thường gặp
- Gửi cả tài liệu 12.000 token trong một input. Vượt giới hạn hoặc bị cắt mất phần cuối. Sửa: chunk theo token bằng
tiktoken. - Tính chi phí bằng số từ. Sửa: dùng
usage.total_tokensvà log lại. - Không sắp theo
index. Vector gán nhầm tài liệu. Sửa: sort theo index trước khi lưu. - Dùng
dimensionskhác nhau cho document và query. Không so sánh được. Sửa: một hằng số cấu hình dùng chung. - Lưu vector vào cột
jsonb. Không index ANN được, chậm và tốn dung lượng. Sửa: kiểuvector(n). - Không có hash nội dung. Chạy lại pipeline là trả tiền lại toàn bộ. Sửa: cache theo hash.
- Đổi model trực tiếp trên index đang chạy. Sửa: dual-write, shadow index, cutover có đo.
Nhìn tới 2027
OpenAI chưa có thế hệ embedding thứ tư, nên kế hoạch ngắn hạn vẫn là 3-small/3-large. Hai điều đáng theo dõi: giá và giới hạn input có thể thay đổi, và các model đa ngữ/đa phương thức từ Cohere, Voyage, Google ngày càng cạnh tranh ở phân khúc giá thấp. Thiết kế schema có cột model ngay từ đầu là cách rẻ nhất để không bị khóa vào một nhà cung cấp.
Checklist
- Bắt đầu bằng
3-small, đo recall@10 trước khi cân nhắc3-large. - Chunk theo token, giữ mỗi input dưới 8.192 token, bỏ input rỗng.
- Batch theo ngân sách token, dùng Batch API cho backfill.
- Chọn
dimensionsbằng đo lường và dùng một giá trị thống nhất. - Xử lý 429 bằng backoff có jitter; không retry lỗi 4xx cấu hình.
- Lưu
model,dims,content_hashvà có runbook nhúng lại.
Đọc tiếp trong series
- Embeddings là gì và vì sao là nòng cốt của AI search — lý thuyết phía sau API này.
- Các trường hợp sử dụng hàng đầu cho embeddings — chọn bài toán trước khi gọi API.
- Triển khai tìm kiếm ngữ nghĩa với index vector — nối vector vào hệ thống tìm kiếm.
- Tokens, cửa sổ ngữ cảnh và chi phí API — phần chi phí và token liên quan.
