Gemini API Embeddings 文本向量怎麼用:gemini-embedding 調用、任務類型(task_type)與維度裁剪

用 Gemini API 搭 RAG 知識庫或做語義搜尋時,gemini-embedding-001 怎麼調?本文按官方文檔整理單條與批量向量化代碼、8 種 task_type 選型表、維度裁剪(768/1536)及 L2 歸一化必做步驟。

NNathaniel bigo··原創首發·AI 輔助撰寫
9 分鐘讀完
資料核對於 2026-11-18 · 依據官方文檔與公開資料整理 其他 帳號

結論先說

  1. 主力文本向量模型是 gemini-embedding-001:通過 client.models.embed_content 調用,contents 既能傳單條字符串,也能傳字符串列表一次生成多條向量。
  2. 做 RAG 檢索時,入庫和查詢必須分設不同的 task_type:文檔切片入庫時設 RETRIEVAL_DOCUMENT,用戶搜問題時設 RETRIEVAL_QUERY,專門對齊非對稱檢索空間。
  3. 支持用 output_dimensionality 按需裁剪維度:預設輸出 3072 維,官方推薦的輕量化檔位是 1536 或 768,能大幅減少向量庫存儲和檢索內存佔用。
  4. 裁剪維度後必須手動補一步 L2 歸一化:官方明確提醒,預設 3072 維返回時已是單位向量,但縮減到低維後的子向量不再保持模長為 1,算點積或餘弦相似度前要先歸一化。
  5. 谷歌帳號準備與多工具訂閱入口:使用 Gemini、Google AI Studio 與 Antigravity 需具備符合地區與年齡要求的個人谷歌帳號,缺號可查看本站 谷歌帳號購買說明(含帶 2FA 的 谷歌電郵成品號),跨平台付費訂閱總覽見 AI 會員充值中心。

Gemini Embeddings 任務類型與維度配置

圖:本站根據 Gemini API 官方文檔:Embeddings 整理的示意圖

本文根據 Google AI for Developers 官方文檔《Embeddings》《Gemini Developer API pricing》整理,資料核對於 2026-11-18。配圖為本站整理的示意圖,不是介面截圖。本站(bigolab.com)不是 Google 官方網站。

適用於誰

  • 準備用 Gemini API 給本地 Markdown、PDF、客服問答庫做向量化入庫(RAG)的開發者;
  • 搜「gemini embedding api」,想知道 task_type 該填哪一個、文檔入庫和用戶提問為什麼要填不同值的人;
  • 向量數據庫(如 pgvector、Milvus、Qdrant)嫌 3072 維太佔內存或受索引上限限制,想安全縮減到 768 或 1536 維的人。

一、基礎調用:單條與多條文本一次轉向量

先確認本地已裝好 google-genai 並配好環境變量 GEMINI_API_KEY(未配置見 Gemini API Key 申請與配置教學)。調用 embed_content 把多段文本轉成浮點數向量只需幾行代碼:

python
from google import genai
from google.genai import types

client = genai.Client()

result = client.models.embed_content(
    model="gemini-embedding-001",
    contents=[
        "支持七天無理由退貨,拆封後需保留完整原包裝。",
        "工作日 16:00 前下單當天發出,預設發順豐快遞。",
    ],
    config=types.EmbedContentConfig(
        task_type="RETRIEVAL_DOCUMENT",
        output_dimensionality=768,
    ),
)

for idx, emb in enumerate(result.embeddings):
    print(f"第 {idx + 1} 條向量維度:{len(emb.values)},前 4 維:{emb.values[:4]}")

如果有幾十萬條歷史文檔要離線建庫,還可以走官方批量向量異步接口(client.batches.create_embeddings)享標準價五折優惠,速率限制與計費口徑見 Gemini API 免費額度與限速說明 與 Gemini API 價格說明。

二、task_type 八種任務類型怎麼選(別全用預設)

在 RAG 知識庫場景裏,用戶問的是短短一句「怎麼退貨」,庫裏存的是幾百字的售後規則——兩者長度和語體不對等。指定任務類型能讓模型把向量投影到最適合該下游任務的子空間:

task_type 參數值適用場景配套用法說明
RETRIEVAL_DOCUMENT知識庫文檔入庫給待檢索的文章段落生成向量,可配合 title 傳標題
RETRIEVAL_QUERY用戶搜尋詞向量化在線檢索時把用戶的提問轉成向量,匹配 RETRIEVAL_DOCUMENT
CODE_RETRIEVAL_QUERY自然語言搜代碼輸入功能描述,去代碼片段庫裏檢索對應函數
QUESTION_ANSWERING標準問答對匹配問題側用此類型,答案段落側搭配 RETRIEVAL_DOCUMENT
FACT_VERIFICATION事實核查找證據待核實的陳述句用此類型,去語料庫裏找支撐原文
SEMANTIC_SIMILARITY兩段話語義判重對稱比較兩句話意思是否相近,兩邊填同一個類型
CLASSIFICATION文本分類特徵把向量餵給下游分類器識別工單類別或情緒標籤
CLUSTERING無監督話題聚類把大批用戶反饋自動聚成若干熱點主題簇

一句話記憶:對稱比相似用 SEMANTIC_SIMILARITY;短問題搜長文檔,存用 RETRIEVAL_DOCUMENT,查用 RETRIEVAL_QUERY。橫向對比 OpenAI 同類模型見 OpenAI Embeddings 向量使用教學。

三、維度裁剪(MRL)與必做的 L2 歸一化代碼

維度裁剪與 L2 歸一化檢索四步

圖:本站根據 Gemini API 官方文檔:Embeddings 整理的示意圖

gemini-embedding-001 採用套娃表示學習(MRL)訓練,最重要特徵集中在最前面的維度。通過 output_dimensionality 把預設的 3072 維截斷成 1536 或 768 維時,無需重訓模型即可把存儲壓降一半到四分之三,也兼容部分向量索引的 2000 維上限。

注意一個關鍵數學細節:官方說明 3072 維完整向量出廠已是單位向量,直接點積等於餘弦相似度;但裁剪成 768 或 1536 維後模長不再等於 1。入庫和檢索前請務必補做 L2 歸一化:

python
import numpy as np
from google import genai
from google.genai import types

client = genai.Client()

def l2_normalize(vec: list[float]) -> np.ndarray:
    arr = np.array(vec, dtype=np.float32)
    norm = np.linalg.norm(arr)
    return arr / norm if norm > 0 else arr

docs = ["退款會在審核通過後 1 至 3 個工作日原路退回。", "修改收貨地址請在發貨前聯絡在線客服。"]
doc_res = client.models.embed_content(
    model="gemini-embedding-001",
    contents=docs,
    config=types.EmbedContentConfig(task_type="RETRIEVAL_DOCUMENT", output_dimensionality=768),
)
doc_matrix = np.vstack([l2_normalize(e.values) for e in doc_res.embeddings])

query_res = client.models.embed_content(
    model="gemini-embedding-001",
    contents="申請退錢之後多久能到賬?",
    config=types.EmbedContentConfig(task_type="RETRIEVAL_QUERY", output_dimensionality=768),
)
scores = doc_matrix @ l2_normalize(query_res.embeddings[0].values)
best_idx = int(np.argmax(scores))
print(f"最匹配文檔:{docs[best_idx]}(相似度:{scores[best_idx]:.4f})")

若準備海外開發環境時需要獨立 Google 帳號開通 AI Studio 和 API 項目,可查看本站 谷歌帳號購買說明 或瀏覽 充值服務總覽。

常見問題

問:能不能入庫時存 768 維,查詢時忘記傳維度用預設 3072 維去搜?

答:不能。維度不一致在任何向量數據庫裏都會直接報錯,建庫與在線檢索必須鎖定同一個模型名稱和同一個維度數字。

問:升級向量模型後需要重跑全庫索引嗎?

答:必須全量重新生成向量(Re-index)。不同模型的向量空間互不相通,即便把維度裁成一樣的數字,算出的餘弦距離也沒有意義。

問:單條文本最長能塞多少字進去轉向量?

答:向量模型的單條輸入上限(數千 token 級)遠小於對話模型的百萬窗口,以官方 Models 頁標註為準。長文檔建議按 300 至 800 字做語義分塊(Chunking)效果更穩。

問:沒有可用的個人谷歌帳號,或者同時想開其他主流 AI 會員怎麼辦?

答:本站提供即買即發的 谷歌電郵成品號(登入方法見 谷歌帳號購買頁),同時支持支付寶、微信支付與 AlipayHK 自助充值 ChatGPT Plus、Claude Code 等主流服務,實時價格與質保細則以各商品頁說明為準。

相關教學

參考資料

  • Gemini API 官方文檔:Embeddings — https://ai.google.dev/gemini-api/docs/embeddings
  • Gemini Developer API pricing — https://ai.google.dev/gemini-api/docs/pricing

Nathaniel 的更多內容

  1. 01

    獨立開發者用 ChatGPT + Codex 跑通產品全流程:市場驗證、PRD、原型到代碼上線覆盤清單

    單人做獨立產品最容易陷入「閉門寫兩個月代碼上線零用戶」或「AI 寫到一半目錄越改越崩」。本文整理「ChatGPT 負責市場驗證、PRD 與覆盤 + Codex 負責工程實現與測試」的五階段雙軌流程,附起手提示詞與 7 項上線覆盤清單。

    ChatGPTCodex0
  2. 02

    用 ChatGPT 批量生成規範文件命名規則、整理混亂目錄樹與合併零散發票抬頭清單腳本

    面對滿桌面的「新建文件夾」「最終版2」和上百張零散電子發票,手工改名抄台帳耗時又容易漏重。本文分享先脫敏取樣、再用 ChatGPT 生成帶預演和回滾日誌的本地 Python 腳本,離線安全完成目錄整理與發票抬頭合併去重的實戰流程。

    ChatGPT0
  3. 03

    用 ChatGPT 做海外電郵營銷(EDM)受眾分層文案、A/B 主題行測試與防進垃圾箱自檢

    做海外獨立站或出海 SaaS 電郵營銷(EDM),最怕千人一面群發被直接送進垃圾箱。本文結合 Gmail/Yahoo 批量發件人規範,梳理用 ChatGPT 設計受眾分層文案、批量生成 A/B 主題行矩陣並開展發前垃圾詞與合規自檢的實戰提示詞。

    ChatGPT0
  4. 04

    用 ChatGPT 寫 Notion Formula 2.0 公式、Obsidian Dataview 查詢與 Airtable 自動化腳本

    給 Notion 數據庫寫多條件 Formula 2.0 公式、給 Obsidian 寫 Dataview 動態看板,或在 Airtable 裏寫自動化腳本,經常因為一個小括號或類型不匹配報錯半天。本文整理三大工具的通用上下文喂料規範與三套直接可複製的生成提示詞。

    ChatGPT其他 AI 工具0
  5. 05

    用 ChatGPT 處理複雜 JSON / YAML / XML 字段映射、格式轉換與校驗規則編寫實戰

    對接第三方 API、遷移 Kubernetes 配置或解析政企 XML 報文時,手工對照幾百行嵌套字段既慢又容易漏掉空值與類型邊界。本文整理用 ChatGPT 完成字段映射表梳理、生成確定性轉換腳本以及編寫 JSON Schema / Pydantic / XSD 校驗規則的實戰流。

    ChatGPT其他 AI 工具0
  6. 06

    用 ChatGPT 準備本科/碩士畢業論文答辯:提煉答辯 PPT 結構、模擬導師犀利追問與 3 分鐘自述稿

    畢業論文寫完後,要在 3–5 分鐘內講清研究價值並頂住答辯評委的連環追問並不輕鬆。本文整理在嚴格遵守高校學術規範的前提下,用 ChatGPT 提煉答辯 PPT 結構、打磨 3 分鐘口語自述稿並開展模擬導師犀利追問的排練流程與提示詞。

    ChatGPT0

同模型

  1. 01

    用 Google Takeout 單獨備份導出 NotebookLM 筆記本與 Gemini 記錄:只勾選指定服務不下載整個雲端硬碟的步驟

    想把 NotebookLM 裏的幾十個研究筆記本、來源副本與音頻概覽,連同 Gemini 聊天記錄一起備份到本地,又怕 Google Takeout 把整個雲端硬碟和相冊全打包?本文講清先取消全選、精準勾選兩項服務、解壓目錄查看與跨號遷移的做法。

    Gemini0
  2. 02

    Google Workspace 企業/教育版管理員怎麼在後台給成員開啟 Gemini 應用、NotebookLM 與設定年齡訪問權限

    團隊成員或學校師生登入 Google Workspace 帳號時提示無權使用 Gemini 或打不開 NotebookLM?本文按 Google 管理控制檯官方文檔整理服務開關路徑、組織部門(OU)與群組放行、18 歲年齡訪問權限設定及對話保留合規配置。

    Gemini0
  3. 03

    安卓手機預設助手換成 Gemini 後設鬧鐘、發短訊或控制智能家居失靈怎麼辦:Workspace 與實用程序擴展開啟步驟

    安卓手機把預設語音助手從 Google Assistant 換成 Gemini 後,喊它定鬧鐘、開手電筒、發短訊或開關智能燈全都沒反應?本文按官方幫助中心整理實用程序(Utilities)、Google Home 與 Workspace 關聯應用開啟步驟及鎖屏放行設定。

    Gemini0
  4. 04

    Gemini 寫長代碼或長文檔到一半突然停住、格式截斷怎麼無縫續寫:錨點接續指令與 Canvas 分塊修改技巧

    讓 Gemini 寫幾百行代碼或萬字長文時經常寫到一半突然停住、Markdown 代碼塊沒閉合,直接回「繼續」又重頭抄一遍?本文整理字面錨點續寫指令、代碼塊防亂碼補齊法與 Canvas 局部圈選修改工作流。

    Gemini0
  5. 05

    NotebookLM 中文音頻播客(Audio Overview)高階玩法:用自定義引導詞控制對談深度、受眾水平與重點章節(附模板)

    NotebookLM 生成的中文音頻播客總是泛泛而談、漏掉核心章節或夾雜生僻英文縮寫?本文按官方幫助中心整理來源勾選過濾、四種播客格式搭配與三維自定義引導詞寫法,附 4 套可直接複製的中文控場模板。

    Gemini0
  6. 06

    NotebookLM 添加 YouTube 影片、網頁或掃描版 PDF 提示「無法導入來源」怎麼辦:無字幕、反爬與純圖 PDF 逐項解決

    往 NotebookLM(Gemini Notebook)塞 YouTube 連結、外文網頁或掃描教材時總是亮紅歎號提示無法導入來源?本文按官方幫助中心逐項排查無字幕影片、反爬動態頁與加密純圖 PDF 的替代導入步驟。

    Gemini0

同產品的其他教學

  1. 01

    iPhone 操作按鈕(Action Button)或鎖屏小組件一鍵開啟 ChatGPT / Gemini 實時語音對話配置教學

    每次在 iPhone 上練口語或語音提問都要解鎖、找圖標、再點耳機按鈕太繁瑣?本文整理利用 iPhone 操作按鈕(Action Button)、iOS 18 鎖屏底部控制項、控制中心與背面輕點一鍵直達 ChatGPT 實時語音或 Gemini Live 的完整步驟。

    ChatGPTGemini0
  2. 02

    Firebase Studio(原 Project IDX)是什麼、怎麼用:瀏覽器雲端全棧開發環境搭配 Gemini 智能體實戰

    以前收藏的 Project IDX 網址為什麼跳到了 Firebase Studio?本文按 Google 官方文檔講清它的全棧雲端定位、App Prototyping 原型智能體、Code 視圖切換、.idx/dev.nix 環境定製與免費工作區上限。

    Gemini其他 AI 工具0
  3. 03

    Google Colab 內置 Gemini 編程助手怎麼用:免費雲端 GPU 筆記本自動生成數據分析代碼、修報錯與限額說明

    不用配本地 Python 環境,怎麼在 Google Colab 雲端筆記本里免費用 Gemini 自動寫數據分析代碼、一鍵修復紅字報錯並跑 Data Science Agent?本文整理四大入口用法、Secrets 密鑰管理與免費版限額。

    Gemini其他 AI 工具0
  4. 04

    Gemini API Token 計數(count_tokens)與多模態計費規則:圖片解像度、音頻秒數與影片幀率怎麼折算 Token

    傳一張高清截圖或一段 10 分鐘影片給 Gemini API 到底扣多少 Token?本文按官方文檔拆解 258 圖片切片、每秒 32 音頻與每秒 263 影片折算公式,附 count_tokens 免費預估與降本代碼。

    Gemini0
  5. 05

    Gemini API 回答被安全策略攔截(SAFETY / PROHIBITED_CONTENT)怎麼辦:閾值調節邊界與合規提示詞排查

    調用 Gemini API 翻譯文檔或分析安全日誌時返回空白、報 finish_reason: SAFETY 或 PROHIBITED_CONTENT 怎麼辦?本文詳解四類可調安全閾值代碼寫法、不可關閉的硬性紅線區別與誤報排查步驟。

    Gemini0
  6. 06

    Gemini API 圖像生成與多輪改圖怎麼調:用 google-genai SDK 出圖、局部修改與寬高比控制參數

    怎麼用 Python 代碼調用 Gemini API 生成高清配圖並像聊天一樣連續局部改圖?本文詳解 google-genai SDK 原生生圖代碼、多輪對話改圖、參考圖融合與 aspect_ratio 寬高比配置。

    Gemini0

0 條評論

登入 後參與評論

還沒有評論,來搶沙發~