Embeddings（嵌入）

更新時間：2026-08-12

導讀

Embeddings API 把文字映射為高維浮點向量，使語意相近的句子在向量空間中距離更近。它是語意搜尋、文件去重、推薦召回與 RAG（檢索增強生成） 的基礎設施。本文面向後端與資料工程師，講清端點呼叫、索引流水線、評測方法與生產踩坑。模型 ID、向量維度、token 單價以 OpenAI 文件 與 定價頁 為準，會隨產品迭代變更——生產環境請用設定中心管理 model 名，勿寫死過期型號。

和關鍵字搜尋有什麼本質區別？

維度	關鍵字 / BM25	Embeddings
匹配邏輯	字面重合	語意相似
「退款」能否找到「申請退訂」	常漏召	較易召回
精確 SKU、訂單號	強	弱，應保留 SQL / ES
跨語言近義	需同義詞表	相對友善
生成最終答案	不能	不能，需接 Responses API

分工原則： Embeddings 負責「找片段」，生成模型負責「寫答案」。

API 端點與呼叫要點

標準請求：POST /v1/embeddings。input 支援單字串或字串陣列；批次可減少 HTTP 開銷，但需遵守單次 token 上限（見 API Reference）。

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": ["退貨政策摘要", "如何取消訂閱"],
    "encoding_format": "float"
  }'

from openai import OpenAI

client = OpenAI()
resp = client.embeddings.create(
    model="text-embedding-3-small",  # 以 Models 頁當前 ID 為準
    input="OpenAI 向量 API 按 input token 計費",
)
print(len(resp.data[0].embedding), resp.usage.total_tokens)

生產習慣：

• 文件內容不變則快取向量（DB / Redis / 物件儲存），避免重複 embed
• 大批量索引用佇列 + 限速，遇 429 指數退避
• 日誌記錄 usage.total_tokens，按業務線分攤帳單

模型選擇與版本鎖定

考量	建議做法
成本	先用 small 檔跑 Recall 基線，再對比 large
多語言	用含中文的真實 query 集評測，勿只看英文 benchmark
儲存	部分模型支援 dimensions 降維，需全量 re-embed
升級	換 model = 重建索引 + 回歸測試

鐵律： 索引庫與線上 query 必須使用同一 embedding 模型；混用會導致召回崩潰。

RAG 索引流水線

原始文件 → 清洗 → 切塊 → batch embed → 寫入向量庫（附 metadata）
使用者問題 → embed query → 過濾 + ANN → Top-K → 拼 context → Responses 生成

切塊策略對照

策略	適合	注意
固定 token + overlap	通用 Wiki	512–1024 token，10–20% overlap 起步
按標題 / 章節	技術手冊	單節過長需二次切
父子塊	長報告	小塊檢索、大塊生成
句子級	FAQ	易丟上下文

提升 Recall 的四招

1. 混合檢索：向量 Top-K + BM25，RRF 融合
2. Metadata 預過濾：版本、產品線、權限標籤先篩
3. Query 改寫：輕量模型把口語問題改成檢索友好表述
4. Rerank：Top-20 重排取 Top-5（延遲與成本更高）

生成側約束見 Prompt Engineering 指南。

向量庫與相似度

API 只回傳浮點陣列；持久化與 ANN 需自選：pgvector、Pinecone、Milvus、Elasticsearch dense_vector 等。OpenAI 向量通常已 L2 歸一化，cosine 相似度與 dot product 等價。

選型看：資料量、QPS、混合過濾、維運能力、多租戶隔離。

計費、限流與安全

• 計費：按 input token；全庫索引成本 ≈ 文件總 token × 單價；每次 query 也會 embed（熱門 query 可快取向量）
• 限流：429 應退避；離線索引用 worker 池
• 安全：PII 去識別後再入庫；檢索結果進 prompt 前做權限校驗；查閱 API 資料留存政策

價格：openai.com/api/pricing

可複製 RAG context 模板

[System]
你是企業知識庫助手。只根據提供的 context 回答。
若 context 不足，回答「資料中未提及」並列出需要補充的資訊。
不得編造連結或法規條文。

[User]
context:
"""
[貼上檢索到的去識別段落，附 doc_id]
"""
問題：[使用者問題]

常見問題

Embeddings 和 Fine-tuning 怎麼配合？

Embeddings 管檢索；Fine-tuning 管生成風格與格式。RAG 常見組合是 Embeddings + 基礎模型，不必微調。見 Fine-tuning 指南。

檢索對了，答案仍胡編？

多為生成側未約束「僅依據 context」、塊過大含雜訊、或未要求引用段落 ID。加強 instructions 並在伺服器端校驗。

圖片能直接 embed 嗎？

文字 Embeddings API 面向字串；圖像理解走 Vision 指南，或 OCR 轉文字後再 embed。

開源 embedding 值得換嗎？

開源可本地部署；OpenAI 託管省維運。用業務 query 集測 Recall@K 與 P95 延遲再決策。

降維後要重建索引嗎？

使用 dimensions 降維後，必須對全庫 re-embed 並重建 ANN，再做 A/B。

官方資源

• Embeddings 指南
• API Reference: Embeddings
• OpenAI Platform
• API 定價

下一步閱讀

• Responses API 繁體指南（RAG 生成側首選）
• Fine-tuning（微調）
• Prompt Engineering 指南
• OpenAI API 快速入門

行動路徑

今天：對 3 組近義句與 3 組無關句 embed 後算 cosine，感受語意距離。明天：按 800 token + 15% overlap 切塊一份 Markdown，批次寫入 pgvector。本週：準備 30 條標註問答測 Recall@5，接入 Responses 跑通最小 RAG 閉環。