OpenAI Embeddings 向量怎麼用：text-embedding-3-small 調用、dimensions 縮短、餘弦相似度搜索

本文根據 OpenAI 官方《Vector embeddings》整理，資料核對於 2026-11-05。配圖為本站整理的示意圖，不是介面截圖。本站（bigolab.com）不是 OpenAI 官方網站。API 是按用量計費的獨立服務，與 ChatGPT 訂閱分開計算，Key 的獲取見 /guides/openai-api-key。

適用於誰

• 想給自己的文檔、客服問答、筆記做“按意思搜尋”的開發者；
• 聽說過 RAG、向量數據庫，但不知道第一步“生成向量”到底怎麼調的人；
• 想知道向量模型選哪個、向量太長怎麼縮短的人。

結論先說

1. embedding 就是一串浮點數。 官方說，兩個向量的距離衡量兩段文字的相關度：距離小表示相關度高，距離大表示相關度低。
2. 調用很簡單：embeddings.create，給模型名和文本，拿回向量。
3. 官方的兩個第三代模型是 text-embedding-3-small 和 text-embedding-3-large，預設向量長度分別是 1536 和 3072。
4. 可以用 dimensions 參數縮短向量，省存儲和計算。
5. 距離函數官方推薦餘弦相似度；OpenAI 的向量已經歸一化到長度 1，所以用點積算餘弦更快，排序結果也和歐氏距離一致。
6. 按輸入的 token 數計費。 價格以官方價格頁當天為準，見 /guides/openai-api-price-official-table。

圖：本站根據 OpenAI 官方《Vector embeddings》 整理的示意圖，流程順序為本站歸納

一、第一次調用

Python（需 pip install openai，密鑰設定見 /guides/openai-api-python-quickstart）：

python
from openai import OpenAI

client = OpenAI()

response = client.embeddings.create(
    input="你好，這裏是要變成向量的文字",
    model="text-embedding-3-small",
)

vector = response.data[0].embedding
print(len(vector))   # 預設 1536
print(vector[:5])

Node.js（儲存為 .mjs）：

javascript
import OpenAI from "openai";

const openai = new OpenAI();

const embedding = await openai.embeddings.create({
  model: "text-embedding-3-small",
  input: "你好，這裏是要變成向量的文字",
  encoding_format: "float",
});

console.log(embedding.data[0].embedding.length);

響應裏的 data[0].embedding 就是向量，usage 裏有這次消耗的 token 數。你可以把向量存進向量數據庫，之後用於各種用途。input 也可以一次傳一個字符串列表，官方的數據集示例就是這樣一次嵌入多條文字（示例裏先把換行符換成空格再嵌入）。

二、選哪個模型

官方頁面的對照：

圖：本站根據 OpenAI 官方《Vector embeddings》 整理的示意圖

官方說它提供兩個第三代向量模型（模型名裏帶 -3）。更大的模型成績更高但更貴，具體費用以官方價格頁當天為準。同一個知識庫裏，文檔和問題必須用同一個模型生成向量，不同模型的向量不能互相比較，這一條是向量搜尋的基本要求，官方示例也都是同模型比較。

三、dimensions：縮短向量

向量越長，存儲、內存和計算越貴。官方說兩個新模型的訓練方式允許你去掉向量末尾的一部分數字，而不丟失它表示概念的能力，做法是在請求裏加 dimensions 參數：

python
response = client.embeddings.create(
    model="text-embedding-3-large",
    input="需要更短的向量",
    dimensions=1024,
)
print(len(response.data[0].embedding))  # 1024

官方給的例子：向量數據庫只支持最多 1024 維時，仍然可以用 text-embedding-3-large，把 dimensions 設為 1024，用一點準確度換更小的向量。官方還說，在 MTEB 評測上，text-embedding-3-large 縮短到 256 維，成績仍高於未縮短的 text-embedding-ada-002（1536 維）。

如果你是生成之後手動截斷，必須再做一次歸一化（L2），官方的示例就是先取前 256 個數，再除以向量長度。能在請求時用 dimensions 就用它，官方說這是推薦做法。

四、一個最小的語義搜尋

下面是本站寫的最小版本，思路對應官方「用 embeddings 做文本搜尋」：先給所有文檔生成向量，再給問題生成向量，按餘弦相似度排序。因為 OpenAI 向量長度已是 1，直接用點積即可：

python
import numpy as np
from openai import OpenAI

client = OpenAI()
MODEL = "text-embedding-3-small"

docs = [
    "怎麼申請 API Key",
    "帳單頁面在哪裏查看用量",
    "請求太頻繁會返回 429 錯誤",
]

def embed(texts):
    res = client.embeddings.create(model=MODEL, input=texts)
    return np.array([d.embedding for d in res.data])

doc_vecs = embed(docs)                  # 形狀：(3, 1536)
query_vec = embed(["為什麼提示請求太多"])[0]

scores = doc_vecs @ query_vec           # 點積 = 餘弦相似度
best = int(np.argmax(scores))
print(docs[best], float(scores[best]))

文檔很多時，別每次都全部重新算。官方 FAQ 的建議是：要快速找最近的 K 個向量，用向量數據庫。官方的 Cookbook 裏有與各種向量數據庫配合的例子。向量搜尋只是幫你找出相關的文字，最後的回答通常還要交給聊天模型，寫法見 /guides/openai-responses-api。

五、數 token 和費用

官方 FAQ 提供了用 tiktoken 數 token 的方法，三代向量模型用 cl100k_base 編碼：

python
import tiktoken

def num_tokens(text, encoding_name="cl100k_base"):
    return len(tiktoken.get_encoding(encoding_name).encode(text))

print(num_tokens("tiktoken is great!"))

這樣能在發請求前估算輸入多長、大約花多少，也能避免超過模型的最大輸入。數量巨大的文檔集，可以考慮用 Batch API 做，寫法見 /guides/openai-api-batch，該文件的端點要填 /v1/embeddings。

常見問題

Q：向量模型知道最近的事嗎？

官方說，text-embedding-3-large 和 text-embedding-3-small 不了解 2021 年 9 月之後發生的事件。對大多數搜尋場景影響不大，個別情況下會降低效果。

Q：我能把向量公開分享嗎？

官方 FAQ 的回答是可以：客戶擁有自己輸入和模型輸出的內容，包括向量。但你要自己保證輸入的內容不違反適用法律和使用條款。

Q：用餘弦相似度還是歐氏距離？

官方推薦餘弦相似度，並說距離函數的選擇通常影響不大。因為向量已歸一化，兩者排序結果相同。

Q：請求報 429？

見 /guides/openai-api-429-error。

參考資料

• OpenAI 官方：Vector embeddings — https://developers.openai.com/api/docs/guides/embeddings