Подключение нейросети в Google Sheets через Apps Script и API

Многие небольшие задачи с текстом живут в таблицах: список отзывов, выгрузка заявок, каталог товаров. Подключить нейросеть к Google Таблицам можно без отдельного сервера — через Apps Script, встроенный в каждую таблицу. Вы пишете в ячейке =ASK_AI("Определи тональность"; A2) и получаете ответ модели. Ниже — код функции, безопасная настройка ключа, кэш, квоты Google и пакетная обработка для больших объёмов.

Как это работает

1. В ячейке стоит пользовательская функция =ASK_AI(...).
2. Apps Script отправляет текст в API Zukko через UrlFetchApp.
3. Ответ модели появляется в ячейке.
4. Кэш запоминает ответ, чтобы одинаковый запрос не оплачивался повторно.

Google Таблицы пересчитывают пользовательскую функцию, когда меняются её аргументы. Если аргументы прежние, повторного запроса не будет.

Шаг 1: ключ Zukko

1. Откройте страницу ключей в кабинете↗.
2. Создайте отдельный ключ, например «Google Sheets», задайте ему дневной лимит расходов и разрешите только нужные модели.
3. Скопируйте ключ вида fetch_... — полностью он показывается один раз.

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

Шаг 2: код Apps Script

Откройте таблицу, выберите Расширения → Apps Script, удалите пример кода и вставьте:

const ZUKKO_API_URL = 'https://api.zukko.pro/v1/chat/completions';
const DEFAULT_MODEL = 'glm-5.3-flash';
const CACHE_SECONDS = 21600; // максимум для CacheService — 6 часов
const CACHE_VERSION = 'v1';  // поменяйте, чтобы сбросить кэш

/**
 * Отправляет задание модели и возвращает ответ.
 * @param {string} prompt Задание для модели.
 * @param {string} context Текст или ячейка, к которой относится задание.
 * @param {string} model ID модели (необязательно).
 * @return {string} Ответ модели.
 * @customfunction
 */
function ASK_AI(prompt, context, model) {

Пояснения к коду:

• Адрес — OpenAI-совместимый эндпоинт https://api.zukko.pro/v1/chat/completions, поэтому любая модель Zukko вызывается одинаково.
• Кэш. Ключ кэша — хеш SHA-256 от модели, задания и текста: длинные тексты не упираются в ограничение длины ключа (250 символов). Срок хранения в CacheService — не больше 6 часов, значение — до 100 КБ. Чтобы сбросить кэш, поменяйте CACHE_VERSION.
• Ошибки возвращаются текстом в ячейку, а не исключением: так сразу видно, что случилось — 401 неверный ключ, 402 нет денег на балансе, 429 слишком много запросов.
• Комментарий @customfunction включает подсказку по функции при вводе формулы.

Шаг 3: ключ в свойствах скрипта

Ключ не нужно вписывать в код:

1. В редакторе Apps Script откройте Настройки проекта (значок шестерёнки).
2. В разделе Свойства скрипта добавьте свойство ZUKKO_API_KEY со значением вашего ключа.
3. Сохраните.

Затем выберите в списке функций testConnection и нажмите Выполнить. Google один раз попросит разрешение на внешние запросы — подтвердите. В журнале выполнения должен появиться ответ модели.

Важно про безопасность: свойства скрипта не видны в самой таблице, но их может открыть любой, у кого есть права редактора таблицы, — через тот же редактор Apps Script. Не давайте права редактирования посторонним и используйте отдельный ключ с лимитом, который можно отозвать в кабинете.

Примеры формул

Разделитель аргументов зависит от языка таблицы: в русской локали — точка с запятой, в английской — запятая.

Тональность отзыва (текст в A2):

Краткая сводка:

Извлечение данных:

Другая модель — третьим аргументом:

Доступные модели: glm-5.3-flash, glm-5.3, gpt-5.6-luna, gpt-5.6-sol, claude-sonnet-5, claude-opus-5-5. Актуальный список — GET https://api.zukko.pro/v1/models или страница «Модели» в кабинете↗.

Квоты Google и большие таблицы

Ограничения Apps Script, которые влияют на эту функцию (по документации Google):

Если модель отвечает дольше 30 секунд, формула вернёт ошибку — для коротких заданий держите max_tokens небольшим. А если протянуть формулу на тысячу строк, таблица запустит много вычислений почти одновременно, и часть запросов может получить 429.

Для больших объёмов надёжнее пакетная обработка из меню: скрипт проходит по выделенному столбцу и записывает ответы в соседний столбец как обычные значения. Они не пересчитываются и больше ничего не стоят. Добавьте в проект:

function onOpen() {
  SpreadsheetApp.getUi()
    .createMenu('ИИ')
    .addItem('Тональность для выделенного столбца', 'classifySelection')
    .addToUi();
}

function classifySelection() {
  const range = SpreadsheetApp.getActiveRange(); // выделите один столбец с текстами
  const texts = range.getValues();
  const task = 'Определи тональность отзыва: положительный, нейтральный или отрицательный. Ответь одним словом.';
  const results = texts.map(row => [row[0] ? ASK_AI(task, row[0]) : '']);
  range.getSheet()
    .getRange(range.getRow(), range.getColumn() + 1, results.length, 1)
    .setValues(results);
}

Один запуск ограничен 6 минутами, поэтому обрабатывайте выделение частями — например, по 100–200 строк.

Сколько это стоит

Пример: 1000 вызовов, в каждом около 150 входных токенов (задание и текст отзыва) и 30 выходных. Всего 0,15M входных и 0,03M выходных токенов.

Реальный расход видно в истории в кабинете. Параметры запроса описаны в документации Chat Completions↗, лимиты ключа — в разделе о лимитах ключей↗.

Частые вопросы

Функция пишет «не задано свойство скрипта ZUKKO_API_KEY»

Проверьте название свойства в настройках проекта — оно должно совпадать с кодом буква в букву. После добавления свойства пересчитайте формулу: измените аргумент или вставьте формулу заново.

Как получить свежий ответ вместо кэшированного?

Поменяйте значение CACHE_VERSION в коде (например, на v2) и пересчитайте формулы. Без этого одинаковые запросы в течение 6 часов возвращаются из кэша Apps Script.

Какую модель выбрать?

По умолчанию стоит самая дешёвая — glm-5.3-flash. Подходит ли она для вашей задачи, проверьте на 20–30 строках: запустите ту же формулу с двумя-тремя моделями в соседних столбцах и сравните ответы. Разница в цене видна в таблице выше.

Можно ли пользоваться таблицей вместе с коллегами?

Да. Запросы идут с ключом из свойств скрипта, поэтому любой пересчёт формулы любым пользователем расходует баланс этого ключа. Кэш помогает, но надёжнее хранить готовые ответы как значения (пакетная обработка выше) и задать ключу дневной лимит.