Gemini 指南
雙子星漫遊指南:本站 Gemini 調用細節總覽。
Gemini 調用方式
對於 Gemini 系列,我們提供原生調用和 Openai 相容這 2 種調用方式。
使用前請執行 pip install google-genai
或 pip install -U google-genai
,安裝(更新)原生依賴。
1️⃣ 原生調用時,需在內部傳入 AiHubMix 密鑰和請求連結。注意這個連結和常規 base_url
寫法不同,請參考範例:
2️⃣ Openai 相容格式則維持通用的 v1
端點:
3️⃣ 針對 2.5 系列,如需顯示推理過程,可用以下 2 種方式:
- 原生調用:傳入
include_thoughts=True
- OpenAI 相容方式:傳入
reasoning_effort
詳細調用請參考下文程式碼範例。
Gemini 2.5 系列「推理」說明
- 2.5 系列皆為推理模型。
- 2.5 flash 為混合模型,類似 claude sonnet 3.7,可用
thinking_budget
控制推理預算以達最佳效果。 - 2.5 pro 為純推理模型,無法關閉 thinking,也不顯式傳遞推理預算。
Python 調用參考如下:
Gemini 2.5 Flash 支持
Openai 相容方式調用參考如下:
- 用於複雜任務時,只需要將模型 id 設置為默認開啟思考的
gemini-2.5-flash-preview-04-17
即可。 - Gemini 2.5 Flash 通過
budget
(思考預算)來控制思考的深度,範圍 0-16K,目前轉發采用的是默認預算 1024,最佳邊際效果為 16K。
多媒體文件
Aihubmix 目前只支持小於 20MB 的多媒體文件(圖片、音頻、視頻),用 inline_data
上傳。
大於 20M 的多媒體需要用 File API(尚未支持),待完善狀態跟踪,返回 upload_url
。
Code Execution
自动代码解析器用例参考:
上下文快取
Gemini 在原生 API 下預設啟用了隱式上下文快取,無需開發者手動操作。每一次 generate_content
請求,系統會自動為輸入內容建立快取。當後續請求與此前內容完全一致時,將直接命中快取,返回上一次的推理結果,大幅提升回應速度並有機會節省 token 消耗。
- 快取自動生效,無需手動配置。
- 快取僅在內容、模型、參數完全一致時生效;任何欄位不同都會視為新請求,不命中快取。
- 快取有效期(TTL)由開發者設定,也可以不設定。如果未指定,預設為 1 小時。無最小或最大時長限制,費用取決於快取 token 數與快取時間。
- 雖然 Google 官方對 TTL 不設上下限,但由於我們作為轉發平台,僅支援有限的 TTL 配置範圍,不保證永久有效。
注意事項
-
無成本節省保證:快取 token 的計費為輸入原價的 25%,理論上輸入部分可最多節省 75% 成本,但 Google 官方並未承諾必然節省,實際帳單還需結合快取命中率、token 類型與儲存時長共同評估。
-
快取命中條件:建議將重複的上下文放在請求前部,將易變內容(如用戶輸入)置於後部,以提高快取命中率。
-
快取命中回饋:如果回應結果命中快取,在
response.usage_metadata
中會包含cache_tokens_details
欄位,並有cached_content_token_count
,開發者可以據此判斷本次請求是否命中快取。
範例回應欄位(命中快取時):
程式碼範例:
命中快取時,
response.usage_metadata
會包含如下結構:
**核心結論:**隱式快取支援自動命中與命中回饋。開發者可以通過 usage_metadata 判斷命中情況。成本節省非保證,實際效果因請求結構和使用場景而異。
Function calling
使用 openai 相容方式調用 Gemini 的 function calling 功能時,需要在請求體內部傳入tool_choice="auto"
,否則會報錯。
輸出結果示例:
Tokens 用量追踪
- Gemini 原生采用
usage_metadata
來追踪使用的 token,其中的字段对应如下:
- prompt_token_count: 輸入 token 數
- candidates_token_count: 輸出 token 數
- thoughts_token_count: 推理使用的 token 數,性質上也是輸出 token
- total_token_count: 總 token 使用量(輸入+輸出)
- 對於 OpenAI 相容格式,則採用
.usage
來追蹤,欄位對應如下:
- usage.completion_tokens: 輸入 token 數
- usage.prompt_tokens: 輸出 token 數(包含推理使用的 token 數)
- usage.total_tokens: 總 token 使用量
使用方法如下: