gemini-3.1-pro-preview vs customtools: 6 个关键区别帮你选对 Agent 模型

gemini-3.1-pro-preview 和 gemini-3.1-pro-preview-customtools 是谷歌同一天发布的两个模型端点,价格相同、推理能力相同,但行为截然不同。本文从 6 个关键维度 对比两者差异,帮你在 Agent 开发中做出正确选择。

核心价值: 看完本文,你将清楚知道什么场景该用标准版、什么场景该用 customtools 版,避免在 Agent 开发中踩坑。

---

先说结论: 什么时候用哪个版本

如果你赶时间,直接看这个表:

你的场景	选哪个	原因
纯对话/问答	标准版	质量最稳定
文本翻译/分析	标准版	不涉及工具调用
代码生成 (无工具)	标准版	直接输出代码
编码助手 (有 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 参数不同

代码示例: 一键切换标准版和 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 版

快速诊断清单

如果你在使用标准版时遇到以下情况,说明应该切换到 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, 模型选择