Blog
跳至主要內容

LiteLLM 上的 DAY 0 支援：Gemini 3

Sameer Kankute
Sameer Kankute
SWE @ LiteLLM (LLM Translation)
Krrish Dholakia
Krrish Dholakia
CEO, LiteLLM
Ishaan Jaffer
Ishaan Jaffer
CTO, LiteLLM
資訊

本指南涵蓋使用 gemini-3-pro-preview 搭配 LiteLLM Proxy 和 SDK 的常見問題與最佳做法。

快速開始​

from litellm import completion
import os

os.environ["GEMINI_API_KEY"] = "your-api-key"

response = completion(
    model="gemini/gemini-3-pro-preview",
    messages=[{"role": "user", "content": "Hello!"}],
    reasoning_effort="low"
)

print(response.choices[0].message.content)

支援的端點​

LiteLLM 提供 Gemini 3 Pro Preview 的完整端對端支援，適用於：

  • ✅ /v1/chat/completions - OpenAI 相容的 chat completions 端點
  • ✅ /v1/responses - OpenAI Responses API 端點（串流與非串流）
  • ✅ /v1/messages - Anthropic 相容的 messages 端點
  • ✅ /v1/generateContent – Google Gemini API 相容端點（程式碼請見：client.models.generate_content(...)）

所有端點都支援：

  • 串流與非串流回應
  • 搭配 thought signatures 的函式呼叫
  • 多輪對話
  • 所有 Gemini 3 特有功能

思維簽章​

什麼是 Thought Signatures？​

Thought signatures 是模型內部推理過程的加密表示。它們對於在多輪對話中維持脈絡至關重要，尤其是在使用函式呼叫時。

Thought Signatures 如何運作​

  1. 自動擷取：當 Gemini 3 傳回函式呼叫時，LiteLLM 會自動從回應中擷取 thought_signature
  2. 儲存：Thought signatures 會儲存在工具呼叫的 provider_specific_fields.thought_signature 中
  3. 自動保留：當您在對話歷史中加入 assistant 的訊息時，LiteLLM 會自動保留並將 thought signatures 傳回 Gemini

範例：多輪函式呼叫​

搭配 Thought Signatures 的串流​

使用 stream_chunk_builder() 的串流模式時，thought signatures 現在會自動保留：

import os
import litellm
from litellm import completion

os.environ["GEMINI_API_KEY"] = "your-api-key"

MODEL = "gemini/gemini-3-pro-preview"

messages = [
    {"role": "system", "content": "You are a helpful assistant. Use the calculate tool."},
    {"role": "user", "content": "What is 2+2?"},
]

tools = [{
    "type": "function",
    "function": {
        "name": "calculate",
        "description": "Calculate a mathematical expression",
        "parameters": {
            "type": "object",
            "properties": {"expression": {"type": "string"}},
            "required": ["expression"],
        },
    },
}]

print("Step 1: Sending request with stream=True...")
response = completion(
    model=MODEL,
    messages=messages,
    stream=True,
    tools=tools,
    reasoning_effort="low"
)

# Collect all chunks
chunks = []
for part in response:
    chunks.append(part)

# Reconstruct message using stream_chunk_builder
# Thought signatures are now preserved automatically!
full_response = litellm.stream_chunk_builder(chunks, messages=messages)
print(f"Full response: {full_response}")

assistant_msg = full_response.choices[0].message

# ✅ Thought signature is now preserved in provider_specific_fields
if assistant_msg.tool_calls and assistant_msg.tool_calls[0].provider_specific_fields:
    thought_sig = assistant_msg.tool_calls[0].provider_specific_fields.get("thought_signature")
    print(f"Thought signature preserved: {thought_sig is not None}")

# Append assistant message (includes thought signatures automatically)
messages.append(assistant_msg)

# Mock tool execution
messages.append({
    "role": "tool",
    "content": "4",
    "tool_call_id": assistant_msg.tool_calls[0].id
})

print("\nStep 2: Sending tool result back to model...")
response_2 = completion(
    model=MODEL,
    messages=messages,
    stream=True,
    tools=tools,
    reasoning_effort="low"
)

for part in response_2:
    if part.choices[0].delta.content:
        print(part.choices[0].delta.content, end="")
print()  # New line

重點：

  • ✅ stream_chunk_builder() 現在會保留 provider_specific_fields，包含 thought signatures
  • ✅ 在將 assistant_msg 附加到對話歷史時，thought signatures 會自動包含在內
  • ✅ 多輪對話可與串流無縫運作

關於 Thought Signatures 的重要注意事項​

  1. 自動處理：LiteLLM 會自動擷取並保留 thought signatures。您不需要手動管理它們。

  2. 平行函式呼叫：當模型進行平行函式呼叫時，只有第一個函式呼叫具有 thought signature。

  3. 序列式函式呼叫：在多步驟函式呼叫中，每一步的第一個函式呼叫都會有其自己的 thought signature，且必須予以保留。

  4. 維持脈絡所必需：Thought signatures 對維持推理脈絡至關重要。沒有它們，模型可能會失去先前推理的脈絡。

對話歷史：從非 Gemini-3 模型切換​

常見問題：從非 Gemini-3 模型切換到 Gemini-3 會破壞對話歷史嗎？​

答案：不會！ LiteLLM 會在需要時自動加入假的 thought signatures 來處理這個情況。

運作方式​

當您從不使用 thought signatures 的模型（例如 gemini-2.5-flash）切換到 Gemini 3 時，LiteLLM 會：

  1. 偵測缺少的簽章：找出沒有 thought signatures 的含工具呼叫 assistant 訊息
  2. 加入假簽章：自動注入假的 thought signature（skip_thought_signature_validator）以確保相容性
  3. 維持對話流程：您的對話歷史可持續無縫運作

範例：在對話中途切換模型​

from openai import OpenAI

client = OpenAI(api_key="sk-1234", base_url="http://localhost:4000")

# Step 1: Start with gemini-2.5-flash (no thought signatures)
messages = [{"role": "user", "content": "What's the weather?"}]

response1 = client.chat.completions.create(
    model="gemini-2.5-flash",
    messages=messages,
    tools=[...],
    reasoning_effort="low"
)

# Append assistant message (no tool call thought signature from gemini-2.5-flash)
messages.append(response1.choices[0].message)

# Step 2: Switch to gemini-3-pro-preview
# LiteLLM automatically adds dummy thought signature to the previous assistant message
response2 = client.chat.completions.create(
    model="gemini-3-pro-preview",  # 👈 Switched model
    messages=messages,  # 👈 Same conversation history
    tools=[...],
    reasoning_effort="low"
)

# ✅ Works seamlessly! No errors, no breaking changes
print(response2.choices[0].message.content)

假簽章詳情​

使用的假簽章是：base64("skip_thought_signature_validator")

這是 Google 建議用來處理來自不支援 thought signatures 的模型之對話歷史的方法。它可讓 Gemini 3：

  • 接受對話歷史而不產生驗證錯誤
  • 無縫延續對話
  • 在模型切換之間維持脈絡

Thinking Level 參數​

reasoning_effort 如何對應到 thinking_level​

對於 Gemini 3 Pro Preview，LiteLLM 會自動將 reasoning_effort 對應到新的 thinking_level 參數：

reasoning_effortthinking_level備註
"minimal""low"對應到低 thinking level
"low""low"多數使用情境的預設值
"medium""high"目前尚未提供中等，對應到高
"high""high"最大推理深度
"disable""low"Gemini 3 無法完全關閉 thinking
"none""low"Gemini 3 無法完全關閉 thinking

預設行為​

LiteLLM 在您省略 thinking_level 時不會設定 reasoning_effort。Gemini API 會套用其原生預設值，與直接呼叫 Google 的結果一致。

使用範例​

from litellm import completion

# Low thinking level (faster, lower cost)
response = completion(
    model="gemini/gemini-3-pro-preview",
    messages=[{"role": "user", "content": "What's the weather?"}],
    reasoning_effort="low"  # Maps to thinking_level="low"
)

# High thinking level (deeper reasoning, higher cost)
response = completion(
    model="gemini/gemini-3-pro-preview",
    messages=[{"role": "user", "content": "Solve this complex math problem step by step."}],
    reasoning_effort="high"  # Maps to thinking_level="high"
)

重要注意事項​

  1. Gemini 3 無法停用 Thinking：與 Gemini 2.5 模型不同，Gemini 3 無法完全停用 thinking。即使您設定 reasoning_effort="none" 或 "disable"，也會對應到 thinking_level="low"。

  2. Temperature 建議：對於 Gemini 3 模型，LiteLLM 預設將 temperature 設為 1.0，並強烈建議維持此預設值。設定 temperature < 1.0 可能導致：

    • 無限迴圈
    • 推理效能下降
    • 複雜任務失敗

  3. Thinking 預設值來自 API：如果您省略 reasoning_effort，LiteLLM 不會 覆寫 thinking_level。當您想要可預測的成本或延遲輪廓時，請設定 reasoning_effort 或原生 thinking 參數（例如 reasoning_effort="low" 以獲得較輕量的推理）。

成本追蹤：Prompt 快取與上下文視窗​

LiteLLM 為 Gemini 3 Pro Preview 提供完整的成本追蹤，包括對 prompt 快取以及依上下文視窗大小分級定價的支援。

Prompt 快取成本追蹤​

Gemini 3 支援 prompt 快取，讓您能快取經常使用的 prompt 前綴以降低成本。LiteLLM 會自動追蹤並計算以下項目的成本：

  • 快取命中權杖：從快取讀取的權杖（以較低費率計費）
  • 快取建立權杖：寫入快取的權杖（一次性成本）
  • 文字權杖：正常處理的一般提示詞權杖

運作方式​

LiteLLM 會從使用量物件中的 prompt_tokens_details 欄位擷取快取資訊：

{
  "usage": {
    "prompt_tokens": 50000,
    "completion_tokens": 1000,
    "total_tokens": 51000,
    "prompt_tokens_details": {
      "cached_tokens": 30000,  # Cache hit tokens
      "cache_creation_tokens": 5000,  # Tokens written to cache
      "text_tokens": 15000  # Regular processed tokens
    }
  }
}

上下文視窗分層定價​

Gemini 3 Pro Preview 最多支援 1M 個上下文權杖，當您的提示詞超過 200k 權杖時，會自動套用分層定價。

自動層級偵測​

LiteLLM 會自動偵測您的提示詞何時超過 200k 權杖門檻，並套用適當的分層定價：

from litellm import completion_cost

# Example: Small prompt (< 200k tokens)
response_small = completion(
    model="gemini/gemini-3-pro-preview",
    messages=[{"role": "user", "content": "Hello!"}]
)
# Uses base pricing: $0.000002/input token, $0.000012/output token

# Example: Large prompt (> 200k tokens)
response_large = completion(
    model="gemini/gemini-3-pro-preview",
    messages=[{"role": "user", "content": "..." * 250000}]  # 250k tokens
)
# Automatically uses tiered pricing: $0.000004/input token, $0.000018/output token

成本明細​

成本計算包含：

  1. 文字處理成本：以基礎或分層費率處理的一般權杖
  2. 快取讀取成本：以折扣費率讀取的快取權杖
  3. 快取建立成本：將權杖寫入快取的一次性成本（若高於 200k，則套用分層費率）
  4. 輸出成本：以基礎或分層費率產生的權杖

範例：檢視成本明細​

您可以使用 LiteLLM 的成本追蹤來檢視詳細成本明細：

from litellm import completion, completion_cost

response = completion(
    model="gemini/gemini-3-pro-preview",
    messages=[{"role": "user", "content": "Explain prompt caching"}],
    caching=True  # Enable prompt caching
)

# Get total cost
total_cost = completion_cost(completion_response=response)
print(f"Total cost: ${total_cost:.6f}")

# Access usage details
usage = response.usage
print(f"Prompt tokens: {usage.prompt_tokens}")
print(f"Completion tokens: {usage.completion_tokens}")

# Access caching details
if usage.prompt_tokens_details:
    print(f"Cache hit tokens: {usage.prompt_tokens_details.cached_tokens}")
    print(f"Cache creation tokens: {usage.prompt_tokens_details.cache_creation_tokens}")
    print(f"Text tokens: {usage.prompt_tokens_details.text_tokens}")

成本最佳化提示​

  1. 使用提示詞快取：對於重複的提示詞前綴，啟用快取可將快取部分的成本最多降低 90%
  2. 監控上下文大小：請留意超過 200k 權杖的提示詞會使用分層定價（輸入 2 倍，輸出 1.5 倍）
  3. 快取管理：快取建立權杖在寫入快取時只收費一次，之後的讀取便宜得多
  4. 追蹤使用量：使用 LiteLLM 內建的成本追蹤來監控不同權杖類型的支出

與 LiteLLM Proxy 整合​

使用 LiteLLM Proxy 時，所有成本追蹤都會自動記錄，並可透過以下方式取得：

  • 使用量記錄：proxy 記錄中的詳細權杖與成本明細
  • 預算管理：根據實際使用量設定預算與警示
  • 分析儀表板：依權杖類型檢視成本趨勢與明細
# config.yaml
model_list:
  - model_name: gemini-3-pro-preview
    litellm_params:
      model: gemini/gemini-3-pro-preview
      api_key: os.environ/GEMINI_API_KEY

litellm_settings:
  # Enable detailed cost tracking
  success_callback: ["langfuse"]  # or your preferred logging service

與 Claude Code CLI 搭配使用​

您可以將 gemini-3-pro-preview 與 Claude Code CLI（Anthropic 的命令列介面）搭配使用。這讓您能以 Claude Code 的原生語法與工作流程使用 Gemini 3 Pro Preview。

設定​

1. 將 Gemini 3 Pro Preview 新增至您的 config.yaml：

model_list:
  - model_name: gemini-3-pro-preview
    litellm_params:
      model: gemini/gemini-3-pro-preview
      api_key: os.environ/GEMINI_API_KEY

litellm_settings:
  master_key: os.environ/LITELLM_MASTER_KEY

2. 設定環境變數：

export GEMINI_API_KEY="your-gemini-api-key"
export LITELLM_MASTER_KEY="sk-1234567890"  # Generate a secure key

3. 啟動 LiteLLM Proxy：

litellm --config /path/to/config.yaml

# RUNNING on http://0.0.0.0:4000

4. 設定 Claude Code 使用 LiteLLM Proxy：

export ANTHROPIC_BASE_URL="http://0.0.0.0:4000"
export ANTHROPIC_AUTH_TOKEN="$LITELLM_MASTER_KEY"

5. 使用 Claude Code 搭配 Gemini 3 Pro Preview：

# Claude Code will use gemini-3-pro-preview from your LiteLLM proxy
claude --model gemini-3-pro-preview

範例用法​

設定完成後，您就可以使用 Claude Code 的原生介面與 Gemini 3 Pro Preview 互動：

$ claude --model gemini-3-pro-preview
> Explain how thought signatures work in multi-turn conversations.

# Gemini 3 Pro Preview responds through Claude Code interface

好處​

  • ✅ 原生 Claude Code 體驗：使用 Gemini 3 Pro Preview 搭配 Claude Code 熟悉的 CLI 介面
  • ✅ 統一驗證：透過 LiteLLM proxy，所有模型共用單一 API 金鑰
  • ✅ 成本追蹤：所有使用量都透過 LiteLLM 集中記錄追蹤
  • ✅ 無縫模型切換：可輕鬆在 Claude 與 Gemini 模型之間切換
  • ✅ 完整功能支援：所有 Gemini 3 功能（thought signatures、function calling 等）都可透過 Claude Code 運作

疑難排解​

Claude Code 找不到模型：

  • 請確認 Claude Code 中的模型名稱完全相符：gemini-3-pro-preview
  • 驗證您的 proxy 是否正在執行：curl http://0.0.0.0:4000/health
  • 檢查 ANTHROPIC_BASE_URL 是否指向您的 LiteLLM proxy

驗證錯誤：

  • 驗證 ANTHROPIC_AUTH_TOKEN 是否與您的 LiteLLM master key 相符
  • 請確認 GEMINI_API_KEY 已正確設定
  • 檢查 LiteLLM proxy 記錄以取得詳細錯誤訊息

Responses API 支援​

LiteLLM 完全支援 Gemini 3 Pro Preview 的 OpenAI Responses API，包括串流與非串流模式。Responses API 提供了一種結構化方式來處理含 function calling 的多輪對話，而 LiteLLM 會自動在整段對話中保留 thought signatures。

範例：將 Responses API 與 Gemini 3 搭配使用​

from openai import OpenAI
import json

client = OpenAI()

# 1. Define a list of callable tools for the model
tools = [
    {
        "type": "function",
        "name": "get_horoscope",
        "description": "Get today's horoscope for an astrological sign.",
        "parameters": {
            "type": "object",
            "properties": {
                "sign": {
                    "type": "string",
                    "description": "An astrological sign like Taurus or Aquarius",
                },
            },
            "required": ["sign"],
        },
    },
]

def get_horoscope(sign):
    return f"{sign}: Next Tuesday you will befriend a baby otter."

# Create a running input list we will add to over time
input_list = [
    {"role": "user", "content": "What is my horoscope? I am an Aquarius."}
]

# 2. Prompt the model with tools defined
response = client.responses.create(
    model="gemini-3-pro-preview",
    tools=tools,
    input=input_list,
)

# Save function call outputs for subsequent requests
input_list += response.output

for item in response.output:
    if item.type == "function_call":
        if item.name == "get_horoscope":
            # 3. Execute the function logic for get_horoscope
            horoscope = get_horoscope(json.loads(item.arguments))
            
            # 4. Provide function call results to the model
            input_list.append({
                "type": "function_call_output",
                "call_id": item.call_id,
                "output": json.dumps({
                  "horoscope": horoscope
                })
            })

print("Final input:")
print(input_list)

response = client.responses.create(
    model="gemini-3-pro-preview",
    instructions="Respond only with a horoscope generated by a tool.",
    tools=tools,
    input=input_list,
)

# 5. The model should be able to give a response!
print("Final output:")
print(response.model_dump_json(indent=2))
print("\n" + response.output_text)

重點：

  • ✅ thought signatures 會在 function calls 中自動保留
  • ✅ 可無縫支援多輪對話
  • ✅ 完整支援所有 Gemini 3 特定功能

Responses API 好處​

  • ✅ 結構化輸出：Responses API 為處理 function calls 與多輪對話提供清楚結構
  • ✅ Thought Signature 保留：LiteLLM 會在串流與非串流模式中自動保留 thought signatures
  • ✅ 無縫整合：可與現有 OpenAI SDK 模式搭配使用
  • ✅ 完整功能支援：所有 Gemini 3 功能（thought signatures、function calling、reasoning）都完整支援

最佳實務​

1. 在對話歷史中一律包含 Thought Signatures​

在建立含 function calling 的多輪對話時：

✅ 請這樣做：

# Append the full assistant message (includes thought signatures)
messages.append(response.choices[0].message)

❌ 不要這樣做：

# Don't manually construct assistant messages without thought signatures
messages.append({
    "role": "assistant",
    "tool_calls": [...]  # Missing thought signatures!
})

2. 使用適當的思考層級​

  • reasoning_effort="low"：適用於簡單查詢、快速回應、成本最佳化
  • reasoning_effort="high"：適用於需要深度推理的複雜問題

3. 將 Temperature 保持在預設值​

對於 Gemini 3 模型，請一律使用 temperature=1.0（預設值）。較低的 temperature 可能會造成問題。

4. 順暢處理模型切換​

當從非 Gemini-3 切換到 Gemini-3 時：

  • ✅ LiteLLM 會自動處理缺少的 thought signatures
  • ✅ 不需要手動介入
  • ✅ 對話歷史會無縫延續

疑難排解​

問題：缺少 Thought Signatures​

症狀：在對話歷史中包含 assistant 訊息時發生錯誤

解決方案：請確保您附加的是回應中的完整 assistant 訊息：

messages.append(response.choices[0].message)  # ✅ Includes thought signatures

問題：切換模型時對話中斷​

症狀：從 gemini-2.5-flash 切換到 gemini-3-pro-preview 時發生錯誤

解決方案：這應該會自動運作！LiteLLM 會加入虛擬 signatures。若看到錯誤，請確認您使用的是最新版 LiteLLM。

問題：無限迴圈或效能不佳​

症狀：模型卡住或產生不佳結果

解決方案：

  • 請確認 temperature=1.0（Gemini 3 的預設值）
  • 檢查 reasoning_effort 是否設定適當
  • 驗證您使用的是正確的模型名稱：gemini/gemini-3-pro-preview

其他資源​

🚅
LiteLLM Enterprise
為正式環境打造的 SSO/SAML、稽核記錄、支出追蹤、多團隊管理與防護欄。
深入瞭解 →