Что такое Gemini 3.1 Pro Customtools? Разберитесь в использовании модели с приоритетом пользовательских инструментов за 5 минут

很多开发者看到 gemini-3.1-pro-preview-customtools 这个模型名时会困惑: customtools 是什么意思? 它和标准的 gemini-3.1-pro-preview 有什么不同? 本文用 5 分钟帮你彻底搞清楚。

核心价值: 读完本文,你将明白什么时候该用标准版、什么时候该用 customtools 版,以及如何在 Agent 开发中正确选择。

什么是 Gemini 3.1 Pro Customtools

一句话解释

gemini-3.1-pro-preview-customtools 是谷歌在 2026 年 2 月 19 日与标准版 Gemini 3.1 Pro 同步发布的专用变体模型。它和标准版的核心区别只有一个: 优先使用你注册的自定义工具,而不是默认跑 bash 命令。

谷歌官方 Changelog 的原话是:

Launched a separate endpoint gemini-3.1-pro-preview-customtools, which is better at prioritizing custom tools, for users building with a mix of bash and tools.

为什么需要这个变体

在 Agent 开发中,开发者通常会同时给模型注册两类能力:

1. Bash/代码执行: 让模型直接运行 shell 命令
2. 自定义工具 (Custom Tools): 开发者定义的结构化函数,如 view_file、search_code、create_pr 等

问题出在哪里? 标准版 Gemini 3.1 Pro 有时会「偷懒」,跳过你精心设计的自定义工具,直接用 bash 命令完成任务。比如你注册了 view_file 工具,但模型可能直接执行 cat filename.py,绕过了你的工具。

这在某些场景下是有问题的:

• 自定义工具可能有权限控制和日志记录
• 自定义工具的返回格式是结构化的,便于后续处理
• 自定义工具可能连接了外部系统 (数据库、API 等)

customtools 变体就是为了解决这个问题: 让模型优先选择你注册的工具。

Основные различия между Gemini 3.1 Pro Standard и версией Customtools

🎯 Ключевой момент: «Уровень интеллекта» у обеих моделей абсолютно одинаков. Разница лишь в том, что когда стоит выбор — использовать bash или ваш зарегистрированный инструмент, версия Customtools с большей вероятностью выберет именно ваш инструмент.

В каких случаях стоит использовать Gemini 3.1 Pro Customtools

Когда Customtools необходима

Когда Customtools НЕ нужна

Официальная рекомендация Google

В FAQ руководства для разработчиков Gemini 3 Google четко заявляет:

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.

Перевод: Если вы заметили, что стандартная версия игнорирует ваши кастомные инструменты в пользу команд bash, попробуйте переключиться на модель gemini-3.1-pro-preview-customtools.

Вызов Gemini 3.1 Pro Customtools через API

Базовый вызов: всё точно так же, как в стандартной версии

import openai

client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"  # Единый интерфейс APIYI
)

# Нужно только сменить название модели, остальной код остается прежним
response = client.chat.completions.create(
    model="gemini-3.1-pro-preview-customtools",
    messages=[
        {"role": "user", "content": "Помоги мне просмотреть содержимое файла main.py в проекте"}
    ]
)
print(response.choices[0].message.content)

Вызов Agent с кастомными инструментами

Настоящая мощь версии customtools раскрывается при использовании function calling:

import openai
import json

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"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "search_code",
            "description": "Поиск ключевых слов в кодовой базе",
            "parameters": {
                "type": "object",
                "properties": {
                    "query": {
                        "type": "string",
                        "description": "Ключевое слово для поиска"
                    },
                    "file_pattern": {
                        "type": "string",
                        "description": "Шаблон файлов, например *.py"
                    }
                },
                "required": ["query"]
            }
        }
    }
]

# Версия customtools будет отдавать приоритет инструментам, определенным выше
response = client.chat.completions.create(
    model="gemini-3.1-pro-preview-customtools",
    messages=[
        {"role": "user", "content": "Найди в проекте все Python-файлы, содержащие TODO"}
    ],
    tools=tools
)

# Модель вызовет инструмент search_code вместо прямого использования grep
tool_call = response.choices[0].message.tool_calls[0]
print(f"Инструмент: {tool_call.function.name}")
print(f"Аргументы: {tool_call.function.arguments}")

import openai
import json

client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"
)

tools = [
    {
        "type": "function",
        "function": {
            "name": "view_file",
            "description": "Просмотреть содержимое указанного файла",
            "parameters": {
                "type": "object",
                "properties": {
                    "file_path": {"type": "string", "description": "Путь к файлу"}
                },
                "required": ["file_path"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "search_code",
            "description": "Поиск ключевых слов в кодовой базе",
            "parameters": {
                "type": "object",
                "properties": {
                    "query": {"type": "string", "description": "Ключевое слово для поиска"},
                    "file_pattern": {"type": "string", "description": "Шаблон файлов"}
                },
                "required": ["query"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "edit_file",
            "description": "Редактирование определенного содержимого в файле",
            "parameters": {
                "type": "object",
                "properties": {
                    "file_path": {"type": "string", "description": "Путь к файлу"},
                    "old_content": {"type": "string", "description": "Старое содержимое для замены"},
                    "new_content": {"type": "string", "description": "Новое содержимое"}
                },
                "required": ["file_path", "old_content", "new_content"]
            }
        }
    }
]

# Имитация выполнения инструмента
def execute_tool(name, args):
    """В реальном проекте замените на настоящую реализацию инструментов"""
    if name == "view_file":
        return f"Содержимое файла: {args['file_path']} (имитация)"
    elif name == "search_code":
        return f"Результаты поиска '{args['query']}': найдено 3 совпадения (имитация)"
    elif name == "edit_file":
        return f"Содержимое в {args['file_path']} успешно заменено (имитация)"
    return "Неизвестный инструмент"

# Основной цикл Agent
messages = [{"role": "user", "content": "Найди все комментарии TODO в проекте и исправь их"}]
max_turns = 5

for turn in range(max_turns):
    response = client.chat.completions.create(
        model="gemini-3.1-pro-preview-customtools",
        messages=messages,
        tools=tools
    )

    msg = response.choices[0].message
    messages.append(msg)

    if msg.tool_calls:
        for tc in msg.tool_calls:
            args = json.loads(tc.function.arguments)
            result = execute_tool(tc.function.name, args)
            messages.append({
                "role": "tool",
                "tool_call_id": tc.id,
                "content": result
            })
            print(f"[Итерация {turn+1}] Вызов: {tc.function.name}({args})")
    else:
        print(f"[Завершено] {msg.content[:200]}")
        break

🚀 Быстрый старт: На платформе APIYI (apiyi.com) стандартная версия и версия customtools используют один и тот же API Key. Просто измените параметр model для переключения — это отлично подходит для A/B тестирования того, какая версия лучше справляется с вашим Agent.

Связь Gemini 3.1 Pro Customtools и фреймворков Agent

Совместимость с популярными фреймворками Agent

Версия customtools особенно ценна для следующих сценариев разработки Agent:

Сравнение поведения Gemini 3.1 Pro Customtools и стандартной версии

Чтобы лучше понять разницу, давайте разберем конкретный пример:

Один и тот же запрос — разная реакция моделей

Запрос пользователя: «Помоги мне просмотреть содержимое файла src/main.py»

Зарегистрированный инструмент: view_file(file_path: string)

Оба способа позволяют получить содержимое файла, но вызов через кастомный инструмент дает следующие преимущества:

1. Контроль доступа: ваш инструмент view_file может проверить, находится ли путь в «белом списке».
2. Форматированный вывод: инструмент может вернуть структурированный JSON вместо «сырого» текста.
3. Логирование и аудит: вызовы инструментов автоматически фиксируются фреймворком.
4. Обработка ошибок: инструмент может выдать понятное сообщение об ошибке вместо системного сбоя bash.

Эволюция моделей вызова инструментов Google Gemini

Customtools — это первый случай, когда Google выпускает специальный вариант модели для вызова инструментов. Вот полная карта моделей Gemini, связанных с инструментами:

Это говорит о том, что Google начинает разделять модели по сценариям использования, а не пытается покрыть всё одной универсальной моделью. В будущем, вероятно, появится еще больше специализированных вариантов.

Часто задаваемые вопросы

Резюме: Шпаргалка по Gemini 3.1 Pro Customtools

Итог одной фразой: gemini-3.1-pro-preview-customtools — это своего рода «режим агента» для Gemini 3.1 Pro. Он заставляет модель послушнее использовать ваши инструменты вместо того, чтобы сразу бежать исполнять bash-скрипты. Цена та же, интеллект тот же, просто стратегия выбора инструментов лучше подходит для разработки агентов.

Рекомендуем подключить обе версии через платформу APIYI (apiyi.com), провести A/B тесты на реальных задачах и выбрать подходящую. Для разработчиков ИИ-агентов версия customtools почти всегда будет лучшим выбором.

Справочные материалы

1. Документация Google AI: Страница модели Gemini 3.1 Pro Preview

   • Ссылка: ai.google.dev/gemini-api/docs/models/gemini-3.1-pro-preview
   • Описание: Содержит сравнение стандартной версии и версии customtools.

2. Gemini API Changelog: Обновление от 19 февраля 2026 года

   • Ссылка: ai.google.dev/gemini-api/docs/changelog
   • Описание: Запись о первом релизе варианта customtools.

3. Руководство для разработчиков Gemini 3: Рекомендации по выбору инструментов в FAQ

   • Ссылка: ai.google.dev/gemini-api/docs/gemini-3
   • Описание: Когда стоит переходить со стандартной версии на версию customtools.

4. Документация Google AI: Руководство по Function Calling

   • Ссылка: ai.google.dev/gemini-api/docs/function-calling
   • Описание: Подробное описание API вызова функций для моделей Gemini.

📝 Автор: Команда APIYI | По вопросам технического взаимодействия заходите на APIYI apiyi.com
📅 Дата обновления: 20 февраля 2026 г.
🏷️ Ключевые слова: gemini-3.1-pro-preview-customtools, кастомные инструменты, разработка агентов, function calling, вызов инструментов, вызов API