gemini-3.1-pro-preview и gemini-3.1-pro-preview-customtools — это два эндпоинта одной и той же модели, выпущенные Google в один день. У них одинаковая цена и одинаковая мощность рассуждений, но ведут они себя совершенно по-разному. В этой статье мы сравним их по 6 ключевым аспектам, чтобы вы могли сделать правильный выбор при разработке своих агентов.
В чем польза: после прочтения вы будете четко понимать, в каких сценариях использовать стандартную версию, а в каких — версию customtools, чтобы не набивать шишки при разработке агентов.
Сразу к сути: когда и какую версию использовать
Если вы спешите, просто взгляните на эту таблицу:
| Ваш сценарий | Что выбрать | Почему |
|---|---|---|
| Обычный чат / Вопросы и ответы | Стандартная | Самое стабильное качество ответов |
| Перевод / Анализ текста | Стандартная | Не требует вызова инструментов |
| Генерация кода (без инструментов) | Стандартная | Выводит код напрямую |
Кодинг-ассистент (с инструментами типа view_file) |
Версия customtools | Гарантирует правильный вызов инструментов |
| DevOps-агент (bash + кастомные инструменты) | Версия customtools | Модель не будет пытаться сделать всё через bash в обход инструментов |
| Рабочие процессы MCP | Версия customtools | Приоритет инструментов гарантирован |
| Не уверены? | Начните со стандартной, если она игнорирует инструменты — переходите на customtools | Официальная рекомендация Google |
🎯 Цитата из документации Google: "Если вы используете gemini-3.1-pro-preview и модель игнорирует ваши кастомные инструменты в пользу bash-команд, попробуйте вместо неё модель gemini-3.1-pro-preview-customtools."
Отличие 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: Общее качество работы — стандартная версия стабильнее
Google в официальной документации дает важное предупреждение:
"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 | Описание |
|---|---|---|---|
| Текстовый чат | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | Возможны небольшие колебания |
| Написание длинных текстов | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | Инструменты не используются, стандартная версия лучше |
| Математические рассуждения | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | Базовые способности к рассуждению одинаковы |
| Генерация кода (без инструментов) | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | Стандартная версия чуть лучше |
| Агент + кастомные инструменты | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ | customtools заметно лучше |
| Смешивание bash и кастомных инструментов | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ | Ключевое преимущество customtools |
Важное понимание: версия customtools — это не «более мощная» модель, а версия, оптимизированная специально для вызова инструментов. В сценариях, где инструменты не нужны, стандартная версия справляется лучше.
💡 Совет по выбору: Если в вашем приложении более 50% запросов не требуют вызова инструментов, рекомендуем оставить стандартную версию в качестве основной и переключаться на customtools только в рабочих процессах агентов. APIYI (apiyi.com) позволяет динамически менять параметр
modelв коде в зависимости от сценария.
Отличие 3: Параметры и спецификации модели — полностью идентичны
На уровне «железа» и характеристик обе версии абсолютно одинаковы:
| Спецификация | Стандартная версия | Версия customtools |
|---|---|---|
| Входной контекст | 1 048 576 токенов | 1 048 576 токенов |
| Максимальный вывод | 65 536 токенов | 65 536 токенов |
| Цена за вход (≤200K) | $2.00 / 1M токенов | $2.00 / 1M токенов |
| Цена за вход (>200K) | $4.00 / 1M токенов | $4.00 / 1M токенов |
| Цена за вывод (≤200K) | $12.00 / 1M токенов | $12.00 / 1M токенов |
| Цена за вывод (>200K) | $18.00 / 1M токенов | $18.00 / 1M токенов |
| Кэширование контекста | $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 |
| Мультимодальный ввод | Текст/Фото/Аудио/Видео | Текст/Фото/Аудио/Видео |
Важный момент: Google не публиковала отдельные результаты бенчмарков для версии customtools, так как базовая модель одна и та же. Разница заключается исключительно в тонкой настройке (fine-tuning) того, как модель работает с инструментами.
Отличие 4: Способ вызова через API — меняется только параметр model
Пример кода: переключение между стандартной версией и customtools в одну строку
import openai
client = openai.OpenAI(
api_key="YOUR_API_KEY",
base_url="https://api.apiyi.com/v1" # Единый интерфейс APIYI
)
# Определяем кастомные инструменты
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 подсвечивают основные «боли» стандартной версии в сценариях с ИИ-агентами:
Проблемы стандартной версии в сценариях с агентами
Фидбек разработчиков из обсуждений на Hacker News:
| Описание проблемы | Анализ причин | Решит ли это customtools? |
|---|---|---|
| «Модель пытается редактировать файлы странными способами, игнорируя предоставленные инструменты редактирования текста» | Стандартная версия отдает приоритет bash | Да — приоритет отдается кастомным инструментам |
| «Плохо вызывает инструменты, часто идет в обход» | Низкий приоритет инструментов | Да — повышает приоритет инструментов |
| «Легко зацикливается и не может двигаться дальше» | Путаница при переключении между инструментами и bash | Частично — путь использования инструментов становится понятнее |
| «Тратит кучу токенов на размышления (thinking tokens), а потом делает какую-то ерунду» | Конфликт между рассуждениями модели и выбором инструментов | Частично — выбор инструментов становится более детерминированным |
| «Постоянно приходится говорить ей "продолжай" или "завершай"» | Проблема основного цикла агента | Нет — это общая проблема модели |
Практика GitHub Copilot
Команда GitHub Copilot при интеграции Gemini 3.1 Pro отметила:
«Модель отлично показывает себя в цикле edit-then-test, обладает высокой точностью работы с инструментами и достигает цели за меньшее количество вызовов».
Это доказывает, что при правильном фреймворке вызова инструментов возможности Gemini 3.1 Pro как агента очень велики. Версия customtools создана как раз для того, чтобы эта «высокая точность» срабатывала стабильнее.
🚀 Практический совет: Если вы создаете ИИ-помощника для написания кода, рекомендуем сразу начинать с версии customtools, чтобы избежать проблем с игнорированием инструментов в стандартной версии. Быстро развернуть и протестировать решение можно через APIYI (apiyi.com).
Отличие 6: Подходящие фреймворки агентов и инструменты разработки
| Инструмент / Фреймворк | Рекомендуемая версия | Причина |
|---|---|---|
| Собственный агент (с кастомными инструментами) | customtools | Гарантирует корректный вызов инструментов |
| Аналоги Claude Code | customtools | Нужны инструменты типа view_file, edit_file и т.д. |
| Cursor | customtools | Набору инструментов IDE нужен гарантированный приоритет |
| GitHub Copilot | Уже адаптировано | Copilot сам оптимизировал вызовы инструментов |
| Агенты LangChain | customtools | Инструменты, зарегистрированные во фреймворке, должны вызываться в приоритетном порядке |
| Агенты на протоколе MCP | customtools | Инструментам MCP нужен приоритет |
| Чистые RAG-приложения | Стандартная версия | Обычно нет конфликта между bash и инструментами |
| Чат-приложения | Стандартная версия | Не предполагают вызов инструментов |
| 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" # Единый интерфейс APIYI
)
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: Ворклоу агента → автоматически выбирается версия 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
)
💰 Совет по стоимости: Цена обеих версий абсолютно одинакова, динамическая маршрутизация не несет дополнительных затрат. Через единый интерфейс APIYI (apiyi.com) переключение модели так же просто, как изменение одной строки.
Часто задаваемые вопросы
Q1: Будет ли версия customtools дороже?
Нет. Цена на обе версии абсолютно одинаковая: входные токены — $2.00 / 1M, выходные — $12.00 / 1M. При вызове через платформу APIYI (apiyi.com) обе версии доступны по одному и тому же API-ключу.
Q2: Я использую только function calling, но не давал прав на выполнение bash. Нужна ли мне версия customtools?
Обычно нет. Версия customtools в первую очередь решает проблему, когда при одновременном наличии bash и кастомных инструментов модель отдает приоритет bash. Если у вашего агента нет возможности выполнять bash-команды, стандартного вызова инструментов (tool calling) будет вполне достаточно.
Q3: Что именно подразумевается под «колебаниями качества» в версии customtools?
Google не публиковал конкретных данных. Судя по отзывам разработчиков, это проявляется в сценариях, не связанных с инструментами (просто диалог или генерация длинных текстов): согласованность ответов и стиль могут немного варьироваться. Для сценариев с активным использованием инструментов (Agent-сценарии) общее качество версии customtools, наоборот, выше.
Q4: Можно ли использовать обе версии одновременно?
Конечно. Рекомендуем настроить динамическую маршрутизацию в коде: запросы, предполагающие вызов инструментов, отправлять на версию customtools, а чисто текстовые запросы — на стандартную версию. Через единый интерфейс APIYI (apiyi.com) для этого достаточно просто изменить параметр model.
Итог: Сравнение стандартной версии и customtools по 6 пунктам
| # | Параметр сравнения | Стандартная версия | Версия customtools | Рекомендация |
|---|---|---|---|---|
| 1 | Приоритет инструментов | Может предпочесть bash | Приоритет кастомным инструментам | Для агентов — customtools |
| 2 | Общее качество | Сбалансировано для всех сценариев | Небольшие колебания в задачах без инструментов | Для общих задач — стандартная |
| 3 | Характеристики/Цена | Полностью идентичны | Полностью идентичны | Нет разницы в затратах |
| 4 | API-вызов | Отличается только параметр model | Отличается только параметр model | Переключение в один клик |
| 5 | Отзывы сообщества | Вызов инструментов бывает нестабилен | Вызов инструментов более надежен | Для Agent-сценариев выбирайте customtools |
| 6 | Подходящие фреймворки | Chat / RAG / Чистые рассуждения | Cursor / Claude Code / MCP | Зависит от типа вашего приложения |
Краткий вывод: customtools — это не «апгрейд», а специализированная версия. Тот же «мозг», но другая стратегия выбора инструментов. Для разработки агентов используйте customtools, для остальных задач — стандартную версию. На APIYI (apiyi.com) можно свободно переключаться между ними, используя один и тот же API-ключ.
Шпаргалка для принятия решения
| Ваш вопрос | Ответ |
|---|---|
| Я делаю просто чат-приложение | Используйте стандартную версию |
| Я разрабатываю ИИ-агента | Используйте версию customtools |
| Какая из двух версий мощнее? | Способности к рассуждению одинаковые, но customtools надежнее в вызове инструментов |
| Нужно ли менять код для переключения? | Нужно только изменить параметр model, остальной код остается прежним |
| Есть ли разница в стоимости? | Полностью идентичны |
Список источников
-
Документация Google AI: Страница модели Gemini 3.1 Pro Preview
- Ссылка:
ai.google.dev/gemini-api/docs/models/gemini-3.1-pro-preview - Описание: Обзор эндпоинта customtools и нюансы его использования.
- Ссылка:
-
Руководство разработчика Gemini 3: FAQ — когда переходить на другую модель
- Ссылка:
ai.google.dev/gemini-api/docs/gemini-3 - Описание: Официальные рекомендации о том, в каких случаях стоит переключиться со стандартной версии на версию customtools.
- Ссылка:
-
Gemini API Changelog: Запись о релизе от 19 февраля 2026 года
- Ссылка:
ai.google.dev/gemini-api/docs/changelog - Описание: Анонс первого выпуска варианта customtools.
- Ссылка:
-
Обсуждение на Hacker News: Отзывы разработчиков о вызове инструментов в Gemini 3.1 Pro
- Ссылка:
news.ycombinator.com/item?id=47074735 - Описание: Реальный опыт использования и отчеты о проблемах от сообщества.
- Ссылка:
-
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 - Описание: Оценка точности работы инструментов в сценариях AI-ассистента для написания кода.
- Ссылка:
📝 Автор: Команда APIYI | Для обмена техническим опытом заходите на APIYI apiyi.com
📅 Дата обновления: 20 февраля 2026 г.
🏷️ Ключевые слова: gemini-3.1-pro-preview-customtools, сравнение со стандартной версией, разработка агентов, вызов инструментов, function calling, выбор модели
