如果你每次呼叫 Gemini API 前,都得先把試算表轉成 CSV,這個步驟現在可以省下來了。自 2026 年 11 月 18 日起,Gemini API 能直接處理 Word、Excel 與 PowerPoint 檔案;Google 的說法是,系統可以「只處理並針對」你選定的內容切片付費(Google AI Studio 變更記錄)。
不過,想省成本就必須明確指定切片範圍;否則仍可能處理整個檔案,讀者 @zg0820 也特別提醒了這點。
為什麼舊版 Excel 流程很難用
舊版文件描述的行為,是只會把 XLSX 的第一個工作表讀成 CSV。這代表你得先調整工作表順序,或把活頁簿拆成多個檔案:
「文件現在仍寫著,XLSX 只會讀取第一個工作表,而且格式是 CSV。」— @aitrackerbot
11 月 18 日的更新,改以原生 Office 與 OpenDocument 輸入,搭配提示詞和函式回應中的內容切片,取代這套繞路做法(DocsWatch 分析)。
11 月 18 日更新到底帶來哪些變化
這次更新是在 11 月 5 日加入 PPT、ODP 與 ODS 支援的基礎上,再增加兩項能力:
- 直接讀取 Office 與 OpenDocument 檔案。 Word、PowerPoint 和 Excel 不必先轉成 PDF 或純文字,就能直接送入。
- 內容切片。 可以選擇頁面範圍、工作表分頁、A1 儲存格範圍、時間區間,或頁面影像、擷取文字、公式與逐字稿等內容層。
切片同時適用於提示詞與 FunctionResponse 部分,因此工具可以只回傳某個工作表範圍,而不是整本活頁簿(AI Index 摘要)。
現在能傳哪些檔案,以及支援哪些模型
Firebase 的輸入需求頁面在 2026 年 11 月 18 日(UTC)更新後,將 Office 支援列為 Gemini 4.x models 的功能(Firebase AI Logic 文件):
| 系列 | 副檔名 | MIME 類型 |
|---|---|---|
| Word | .doc、.docx、.dotx | application/msword、application/vnd.openxmlformats-officedocument.wordprocessingml.document、application/vnd.openxmlformats-officedocument.wordprocessingml.template |
| PowerPoint | .ppt、.pptx | application/vnd.ms-powerpoint、application/vnd.openxmlformats-officedocument.presentationml.presentation |
| Excel | .xls、.xlsx | application/vnd.ms-excel、application/vnd.openxmlformats-officedocument.spreadsheetml.sheet |
| OpenDocument | .odt、.odp、.ods | application/vnd.oasis.opendocument.text、application/vnd.oasis.opendocument.presentation、application/vnd.oasis.opendocument.spreadsheet |
| 基礎支援 | .pdf、.txt | application/pdf、text/plain |
官方限制如下,使用切片並不會提高上限:
- 每個檔案上限 50 MB、每個檔案 1,000 頁、每次請求最多 3,000 個文件檔案。
- 內嵌 base64 資料的請求總大小上限為 20 MB;更大的檔案必須使用 Cloud Storage URL。
另有一項尚未驗證的社群說法,這裡特別分開列出:一名變更記錄讀者表示,Office 檔案可能有約 2,000 頁或投影片的專屬上限(@lawson_ste3476)。Google 尚未記錄這項限制,因此不要以它作為系統設計依據。
Word 與 PowerPoint:指定頁面範圍與內容層
公開的 v1beta/v1alpha Discovery 文件中可以看到 DocumentMetadata,但穩定版 v1 尚未提供(ORIENS schema 報告):
startPage:起始頁,從 1 開始計算,包含該頁。endPage:結束頁,從 1 開始計算,包含該頁。contentLayers:PAGE_IMAGE(轉換後的頁面影像;有 metadata 但未指定內容層時,據報告會是預設值)或PAGE_TEXT(擷取出的文字)。
需要保留版面、投影片設計或處理掃描頁面時,選 PAGE_IMAGE;要搜尋合約等文字內容,則選 PAGE_TEXT。Firebase 說明了背後的計算方式:PDF 會視為影像處理,每頁算一張影像;若影像的長寬都不超過 384 px,每張會計 258 tokens(Firebase AI Logic 文件)。
Excel:工作表、儲存格範圍與三種內容層
根據 Discovery schema,SpreadsheetMetadata 會附加在透過 inline_data 或 file_data 提供的檔案部分上,並可放在輸入的 Part 或 FunctionResponsePart 中(ORIENS schema 報告):
sheetIndex:按照活頁簿順序編號,從 1 開始。Discoveryv1beta文字說明,省略時會選取所有工作表;Python 和 JavaScript SDK 的文字則表示會選第一個工作表。實務上每次都應明確設定。visibleCells:例如A1:G35這樣的 A1 範圍;省略時,會選取指定工作表中實際有內容的區域。contentLayers:DATA(值、合併儲存格、格式)、FORMULAS(公式與計算結果)、VISUAL(轉換後的影像)。據報告,預設值為[DATA, FORMULAS]。
進行稽核時使用 DATA 搭配 FORMULAS;需要檢查版面或合併儲存格脈絡時,再加入 VISUAL;若只是查詢單一項目,就把 visibleCells 範圍縮到最小。
只送出需要的切片:Python REST 範例
以下欄位名稱對應 Discovery revision 20261116;目前格式仍屬 beta,穩定版 v1 尚未提供,因此正式上線前請先對照你安裝的 SDK 版本確認。
import os
from google import genai
import requests
client = genai.Client() # reads GEMINI_API_KEY
workbook = client.files.upload(
file="q3_revenue.xlsx",
config={"mime_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"},
)
api_key = os.environ["GEMINI_API_KEY"]
url = f"https://generativelanguage.googleapis.com/v1beta/models/gemini-4-hydrogen:generateContent?key={api_key}"
payload = {
"contents": [{
"parts": [
{
"fileData": {
"fileUri": workbook.uri,
"mimeType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
},
"spreadsheetMetadata": {
"sheetIndex": 2,
"visibleCells": "A1:G35",
"contentLayers": ["DATA", "FORMULAS"],
},
},
{"text": "Summarize revenue variance in this range using computed values."},
]
}]
}
r = requests.post(url, json=payload, timeout=120)
r.raise_for_status()
print(r.json()["candidates"][0]["content"]["parts"][0]["text"])處理 Word 時,將 "documentMetadata": {"startPage": 12, "endPage": 18, "contentLayers": ["PAGE_TEXT"]} 放入請求,並改用 .docx 的 MIME 類型即可。PowerPoint 也是相同的 documentMetadata 格式,搭配 .pptx MIME 類型和投影片頁碼。
計費怎麼算:什麼時候切片真的能省錢
變更記錄或 Firebase 定價說明中,沒有獨立的切片 SKU;實際節省的金額,就是少處理的輸入 tokens,並按照標準費率計算。變更記錄列出的 gemini-4-hydrogen 價格是每 1M input tokens $1.50。
以下用一份 200 頁的報告示範,假設實際只需要第 12–18 頁;其中每頁文字 800 tokens 是本例假設值,不是官方公布的費率:
- 切片前:200 頁以影像處理,每頁至少 258 tokens x 200 = 51,600 input tokens。費用:51,600 / 1,000,000 x $1.50 = $0.0774。
- 切片後:7 頁擷取文字,每頁假設 800 tokens,共 5,600 input tokens。費用:5,600 / 1,000,000 x $1.50 = $0.0084。
- 節省:這次請求的輸入成本約減少 89%,尚未計入輸出 tokens。實際應以你測得的頁面密度替換假設值。
建議直接用自己的活頁簿測試範圍大小:切得太碎、發出大量小型請求,總成本可能反而高於一次選好範圍的請求(@zg0820)。
讓流程穩定運作:驗證與遷移清單
檔案成功上傳,不代表內容就一定解析成功。每條處理流程都應逐項驗證:
- 確認解析結果。 要求模型回傳資料列數、工作表名稱或頁數,再與來源檔案比對。
- 每個選擇器都要明確設定。 包括
sheetIndex、visibleCells或頁面範圍,以及contentLayers。 - 根據問題選擇內容層。 圖表與版面需要
VISUAL或PAGE_IMAGE;稽核需要DATA搭配FORMULAS;搜尋則使用PAGE_TEXT。 - 在 staging 測試超出範圍的行為。 Schema 沒有說明輸入無效頁碼或範圍時,系統會報錯、限制到有效範圍,還是直接回傳空內容。
- 留意上傳上限。 60 MB 的檔案仍會因超過 50 MB 上限而失敗;超過 20 MB 的內嵌資料請改用 Cloud Storage URL。
- 按照這個順序遷移。 Excel 拆分器改用
sheetIndex加visibleCells;報告點陣化流程改用頁面範圍搭配PAGE_TEXT(只有需要版面時才使用PAGE_IMAGE);整份檔案的工具回傳則改成切片後的函式回應。
引用的來源沒有交代以下情況:隱藏列、合併儲存格、圖表、嵌入圖片,以及受密碼保護、啟用巨集或損毀檔案的處理方式,都未在上述切片公告或 Firebase 輸入需求頁面中說明。請使用自己的範本逐一驗證。
常見問題
函式回應中的內容也能切片嗎?
可以。工具可以回傳檔案 URI 搭配 SpreadsheetMetadata 或 DocumentMetadata,讓模型只看到指定摘錄,特別適合代理型文件工作流程。
哪個 API 版本支援切片?
目前在 Discovery revision 20261116 的 v1beta 和 v1alpha 中觀察到這項功能,穩定版 v1 尚未提供。正式環境前請固定版本,並在目標模型上測試。
為什麼 Gemini 說它看不到我上傳的檔案?
先對照上方的表格與限制,檢查 MIME 類型、檔案大小和明確指定的選擇器;接著要求模型回傳工作表名稱或頁數,確認檔案是否成功解析。
延伸閱讀:Gemini 4 Carbon vs Hydrogen API guide,了解如何選擇 Office 流程背後使用的模型。