gemini 3 1 pro preview vs customtools comparison guide zh hant image 0 图示

gemini-3.1-pro-preview vs customtools: 6 個關鍵區別幫你選對 Agent 模型

作者:

gemini-3.1-pro-preview 和 gemini-3.1-pro-preview-customtools 是谷歌同一天發佈的兩個模型端點，價格相同、推理能力相同，但行爲截然不同。本文從 6 個關鍵維度 對比兩者差異，幫你在 Agent 開發中做出正確選擇。

核心價值: 看完本文，你將清楚知道什麼場景該用標準版、什麼場景該用 customtools 版，避免在 Agent 開發中踩坑。

gemini-3-1-pro-preview-vs-customtools-comparison-guide-zh-hant 图示

先說結論: 什麼時候用哪個版本

如果你趕時間，直接看這個表:

你的場景 選哪個 原因
純對話/問答 標準版 質量最穩定
文本翻譯/分析 標準版 不涉及工具調用
代碼生成 （無工具） 標準版 直接輸出代碼
編碼助手 （有 view_file 等工具） customtools 版 確保工具被正確調用
DevOps Agent （bash + 自定義工具） customtools 版 避免模型總用 bash 繞過工具
MCP 工作流 customtools 版 工具優先級保障
不確定？ 先用標準版，遇到工具被跳過就換 customtools 谷歌官方建議

🎯 谷歌官方原話: "If you are using gemini-3.1-pro-preview and the model ignores your custom tools in favor of bash commands， try the gemini-3.1-pro-preview-customtools model instead."

區別 1: 工具調用優先級 — 核心差異

這是兩個版本唯一的本質區別。當模型同時擁有「bash 執行」和「自定義工具」兩種能力時，它怎麼選擇？

標準版的問題: 偷偷用 bash

當你給標準版註冊了 view_file 工具，但讓它查看一個文件時:

用戶: "查看 src/main.py 的內容"
標準版行爲: 執行 bash 命令 `cat src/main.py`  ← 跳過了你的工具！

在 Hacker News 的開發者討論中，多位開發者反饋了類似問題:

  • 「模型嘗試用奇怪的方式編輯文件，而不是使用提供的文本編輯工具」
  • 「工具調用能力較差，經常繞道」
  • 「容易陷入循環，無法前進」

customtools 版的修正: 尊重你的工具

用戶: "查看 src/main.py 的內容"
customtools 版行爲: 調用 view_file（"src/main.py"）  ← 使用你註冊的工具 ✓
場景 標準版行爲 customtools 版行爲
查看文件 cat src/main.py （bash） view_file（"src/main.py"）
搜索代碼 grep -r "TODO" *.py （bash） search_code（"TODO"， "*.py"）
編輯文件 sed -i 's/old/new/' file （bash） edit_file（path， old， new）
列出文件 ls -la src/ （bash） list_files（"src/"）
運行測試 pytest tests/ （bash） run_tests（"tests/"）

區別 2: 通用質量表現 — 標準版更穩定

谷歌在官方文檔中明確提出了一個重要警告:

"While gemini-3.1-pro-preview-customtools is optimized for agentic workflows that use custom tools and bash， you may see quality fluctuations in some use cases which don't benefit from such tools."

這意味着 customtools 版在以下場景中可能不如標準版穩定:

場景類型 標準版質量 customtools 版質量 說明
純文本對話 ⭐⭐⭐⭐⭐ ⭐⭐⭐⭐ 可能有微小波動
長文寫作 ⭐⭐⭐⭐⭐ ⭐⭐⭐⭐ 不涉及工具，標準版更優
數學推理 ⭐⭐⭐⭐⭐ ⭐⭐⭐⭐⭐ 推理核心能力相同
代碼生成 （無工具） ⭐⭐⭐⭐⭐ ⭐⭐⭐⭐ 標準版略優
Agent + 自定義工具 ⭐⭐⭐ ⭐⭐⭐⭐⭐ customtools 明顯更好
bash + 自定義工具混用 ⭐⭐⭐ ⭐⭐⭐⭐⭐ customtools 的核心優勢

關鍵認知: customtools 版不是「更強」的模型，而是「更專注於工具調用」的調優版。在不涉及工具的場景中，標準版反而更好。

💡 選擇建議: 如果你的應用有 50% 以上的請求不涉及工具調用，建議保持標準版作爲默認，僅在 Agent 工作流中切換到 customtools 版。API易 apiyi.com 支持在代碼中根據場景動態切換 model 參數。

區別 3: 模型參數和規格 — 完全相同

兩個版本在「硬件規格」層面完全一致:

規格 標準版 customtools 版
輸入上下文 1，048，576 tokens 1，048，576 tokens
最大輸出 65，536 tokens 65，536 tokens
輸入價格 （≤200K） $2.00 / 1M tokens $2.00 / 1M tokens
輸入價格 （>200K） $4.00 / 1M tokens $4.00 / 1M tokens
輸出價格 （≤200K） $12.00 / 1M tokens $12.00 / 1M tokens
輸出價格 （>200K） $18.00 / 1M tokens $18.00 / 1M tokens
上下文緩存 $0.20-$0.40 / 1M $0.20-$0.40 / 1M
ARC-AGI-2 77.1% 相同 （未單獨發佈）
SWE-Bench 80.6% 相同 （未單獨發佈）
GPQA Diamond 94.3% 相同 （未單獨發佈）
思考系統 Low / Medium / High Low / Medium / High
多模態輸入 文本/圖片/音頻/視頻 文本/圖片/音頻/視頻

重點: 谷歌沒有爲 customtools 版單獨發佈基準測試數據，因爲底層模型是同一個。差異僅在於工具調用行爲的調優。

區別 4: API 調用方式 — 僅 model 參數不同

gemini-3-1-pro-preview-vs-customtools-comparison-guide-zh-hant 图示

代碼示例: 一鍵切換標準版和 customtools 版

import openai

client = openai.OpenAI（
    api_key="YOUR_API_KEY"，
    base_url="https://api.apiyi.com/v1"  # API易 統一接口
）

# 定義自定義工具
tools = [{
    "type": "function"，
    "function": {
        "name": "view_file"，
        "description": "查看指定文件的內容"，
        "parameters": {
            "type": "object"，
            "properties": {
                "file_path": {"type": "string"， "description": "文件路徑"}
            }，
            "required": ["file_path"]
        }
    }
}]

# 標準版: 可能跳過工具
resp_standard = client.chat.completions.create（
    model="gemini-3.1-pro-preview"，
    messages=[{"role": "user"， "content": "查看 src/main.py"}]，
    tools=tools
）

# customtools 版: 優先使用工具
resp_custom = client.chat.completions.create（
    model="gemini-3.1-pro-preview-customtools"，
    messages=[{"role": "user"， "content": "查看 src/main.py"}]，
    tools=tools
）

# 對比行爲差異
print（"標準版:"， resp_standard.choices[0].message）
print（"customtools:"， resp_custom.choices[0].message）

區別 5: 開發者實際體驗 — 社區反饋

Hacker News 和 GitHub 上的開發者反饋揭示了標準版在 Agent 場景中的痛點:

標準版在 Agent 場景的問題

來自 Hacker News 討論的開發者反饋:

問題描述 原因分析 customtools 能解決嗎
「模型嘗試用奇怪方式編輯文件，不用提供的文本編輯工具」 標準版傾向 bash 能解決 — 優先使用自定義工具
「工具調用能力差，經常繞道」 工具優先級低 能解決 — 提升工具優先級
「容易陷入循環，無法前進」 工具和 bash 之間切換混亂 部分解決 — 工具路徑更清晰
「大量消耗思考 token 後做了莫名其妙的事」 模型推理和工具選擇衝突 部分解決 — 工具選擇更確定
「一直需要告訴它繼續或完成」 Agent 主循環問題 不能解決 — 這是模型通用問題

GitHub Copilot 的實踐

GitHub Copilot 團隊集成 Gemini 3.1 Pro 時指出:

"模型在 edit-then-test 循環中表現出色，具有高工具精度，用更少的工具調用就能達成目標。"

這表明在正確的工具調用框架下，Gemini 3.1 Pro 的 Agent 能力是很強的。customtools 版正是爲了讓這種「高工具精度」更可靠地觸發。

🚀 實踐建議: 如果你在構建編碼助手類產品，建議直接從 customtools 版開始，避免標準版的工具跳過問題。通過 API易 apiyi.com 可以快速部署和測試。

區別 6: 適用的 Agent 框架和編碼工具

工具/框架 建議版本 理由
自研 Agent （有自定義工具） customtools 確保工具被正確調用
Claude Code 類產品 customtools 需要 view_file、edit_file 等工具
Cursor customtools IDE 工具集需要優先級保障
GitHub Copilot 已內置適配 Copilot 自行優化了工具調用
LangChain Agent customtools 框架註冊的 tools 需要被優先調用
MCP 協議 Agent customtools MCP 工具需要優先級
純 RAG 應用 標準版 通常不涉及 bash vs 工具的衝突
Chat 應用 標準版 不涉及工具調用
內容生成 API 標準版 純文本輸出

如何判斷是否需要從標準版切換到 customtools 版

gemini-3-1-pro-preview-vs-customtools-comparison-guide-zh-hant 图示

快速診斷清單

如果你在使用標準版時遇到以下情況，說明應該切換到 customtools 版:

  • 模型執行 cat 而不是調用你的 view_file
  • 模型執行 grep 而不是調用你的 search_code
  • 模型執行 sed 而不是調用你的 edit_file
  • 模型在工具調用日誌中頻繁出現 bash 命令
  • 模型的工具調用率低於預期 （低於 50%）
  • 模型似乎「不知道」有自定義工具可用

出現 2 條以上，建議立即切換到 gemini-3.1-pro-preview-customtools。

進階: 在代碼中動態切換兩個版本

最佳實踐不是「二選一」，而是根據請求類型動態路由:

import openai

client = openai.OpenAI（
    api_key="YOUR_API_KEY"，
    base_url="https://api.apiyi.com/v1"  # API易 統一接口
）

def smart_route（messages， tools=None）:
    """根據是否需要工具，動態選擇模型版本"""
    if tools and len（tools） > 0:
        # 有自定義工具 → 用 customtools 版確保工具被調用
        model = "gemini-3.1-pro-preview-customtools"
    else:
        # 純對話/推理 → 用標準版確保質量穩定
        model = "gemini-3.1-pro-preview"

    return client.chat.completions.create（
        model=model，
        messages=messages，
        tools=tools
    ）

# 場景 1: 純推理 → 自動選標準版
resp1 = smart_route（
    messages=[{"role": "user"， "content": "解釋量子糾纏原理"}]
）

# 場景 2: Agent 工作流 → 自動選 customtools 版
tools = [{"type": "function"， "function": {
    "name": "view_file"，
    "description": "查看文件"，
    "parameters": {"type": "object"， "properties": {
        "path": {"type": "string"}
    }， "required": ["path"]}
}}]

resp2 = smart_route（
    messages=[{"role": "user"， "content": "查看 config.py"}]，
    tools=tools
）

💰 成本提示: 兩個版本價格完全相同，動態路由不會增加任何額外成本。通過 API易 apiyi.com 的統一接口，切換模型就像改一個字符串一樣簡單。

常見問題

Q1: customtools 版會更貴嗎？

不會。兩個版本的價格完全一致: 輸入 $2.00 / 1M tokens，輸出 $12.00 / 1M tokens。通過 API易 apiyi.com 平臺調用，同一個 API Key 即可使用兩個版本。

Q2: 我只用了 function calling 但沒給 bash 執行權限，需要用 customtools 版嗎？

通常不需要。customtools 版主要解決的是「bash 和自定義工具並存時，模型優先選 bash」的問題。如果你的 Agent 沒有 bash 執行能力，標準版的工具調用已經足夠可靠。

Q3: customtools 版的「質量波動」具體是什麼？

谷歌沒有公佈具體數據。從開發者反饋來看，主要體現在純對話、長文生成等不涉及工具的場景中，輸出的一致性和文風可能略有波動。對於工具密集型的 Agent 場景，customtools 版的整體質量反而更好。

Q4: 能同時用兩個版本嗎？

當然可以。推薦在代碼中根據請求類型動態路由: 涉及工具調用的請求發給 customtools 版，純文本請求發給標準版。通過 API易 apiyi.com 的統一接口，只需改 model 參數即可。

總結: 標準版 vs Customtools 6 項對比速查

# 對比維度 標準版 customtools 版 選擇建議
1 工具優先級 可能優先 bash 優先自定義工具 Agent 用 customtools
2 通用質量 所有場景均衡 非工具場景有微小波動 通用任務用標準版
3 規格/價格 完全相同 完全相同 無成本差異
4 API 調用 僅 model 參數不同 僅 model 參數不同 一鍵切換
5 社區反饋 標準版工具調用不可靠 工具調用更可靠 Agent 場景選 customtools
6 適用框架 Chat/RAG/純推理 Cursor/Claude Code/MCP 看你的應用類型

一句話總結: customtools 不是升級版而是專用版 — 同樣的大腦，不同的工具選擇策略。開發 Agent 用 customtools，其他場景用標準版。兩個版本通過 API易 apiyi.com 用同一個 API Key 自由切換。

選擇決策速查

你的問題 答案
我只做對話應用 用標準版
我在開發 Agent 用 customtools 版
兩個版本哪個更強？ 推理能力相同，工具調用 customtools 更可靠
切換需要改代碼嗎？ 只需改 model 參數，其他代碼不變
成本有差異嗎？ 完全相同

參考資料

  1. Google AI 文檔: Gemini 3.1 Pro Preview 模型頁

    • 鏈接: ai.google.dev/gemini-api/docs/models/gemini-3.1-pro-preview
    • 說明: customtools 端點介紹和使用注意事項

  2. Gemini 3 開發者指南: FAQ — 何時切換模型

    • 鏈接: ai.google.dev/gemini-api/docs/gemini-3
    • 說明: 官方建議從標準版切換到 customtools 版的時機

  3. Gemini API Changelog: 2026 年 2 月 19 日發佈記錄

    • 鏈接: ai.google.dev/gemini-api/docs/changelog
    • 說明: customtools 變體的首次發佈公告

  4. Hacker News 討論: 開發者對 Gemini 3.1 Pro 工具調用的反饋

    • 鏈接: news.ycombinator.com/item？id=47074735
    • 說明: 真實開發者體驗和問題報告

  5. GitHub Copilot Changelog: Gemini 3.1 Pro 集成

    • 鏈接: github.blog/changelog/2026-02-19-gemini-3-1-pro-is-now-in-public-preview-in-github-copilot
    • 說明: 編碼助手場景的工具精度評價

📝 作者: APIYI Team | 技術交流請訪問 API易 apiyi.com
📅 更新時間: 2026 年 2 月 20 日
🏷️ 關鍵詞: gemini-3.1-pro-preview-customtools， 標準版對比， Agent 開發， 工具調用， function calling， 模型選擇

發佈留言