Claude в Google Cloud Vertex AI

Зачем Claude через Vertex AI

Модели те же самые — меняется дверь, в которую вы стучитесь. Вместо ключа sk-ant-… у вас токен Google-аутентификации, вместо отдельного счёта от Anthropic — строка в счёте Google Cloud, вместо ручного управления ключами — роли IAM и сервис-аккаунты. Для компании, у которой уже есть договор с Google и пройденная проверка вендора, это часто единственный способ пустить Claude в продакшен без нового раунда закупок.

Второй мотив — соседство с остальной инфраструктурой. Данные в BigQuery, файлы в Cloud Storage, сервис в Cloud Run: вызов модели из того же проекта не выходит в открытый интернет, пишется в общий Cloud Logging и подчиняется тем же VPC Service Controls и CMEK, что и всё остальное.

За удобство платите деталями. Идентификаторы моделей отличаются от прямого API, новые возможности Anthropic доезжают до Vertex не одновременно и не все, набор регионов у каждой модели свой, а квоты живут по правилам Google. Код с прямого API переносится почти без изменений — но это «почти» надо проверить руками, а не поверить на слово.

Проект, регион и права: подготовка, которая экономит вечер

Начните с включения API: gcloud services enable aiplatform.googleapis.com --project=ВАШ_ПРОЕКТ. Дальше — Model Garden и карточка нужной модели Claude. Партнёрские модели не работают сразу: их надо явно включить и принять условия, а оформляется это как заказ через Cloud Marketplace. У разработчика с одной ролью aiplatform.user кнопка либо не появится, либо вернёт 403, поэтому включение делает владелец проекта, а рабочим сервис-аккаунтам остаётся минимум прав.

Регион — не косметика. Модель обслуживается в конкретных локациях, и вызов туда, где её нет, вернёт 404 с невнятным текстом про publisher model. Список локаций смотрите на карточке модели, а не по памяти: он у разных моделей разный и меняется. Кроме региональных эндпоинтов есть глобальный (region="global") и мультирегиональные ("us", "eu"): у глобального обычно лучше доступность и мягче квоты, но вы теряете контроль над тем, где физически считается запрос. Нужна резидентность данных — берите региональный и не смешивайте два варианта в одном сервисе.

Аутентификация идёт через Application Default Credentials. Локально: gcloud auth application-default login и gcloud config set project ВАШ_ПРОЕКТ. На сервере файл ключа не нужен вообще — на GCE, Cloud Run, GKE и Cloud Functions прикрепите сервис-аккаунт, и SDK возьмёт токен из метаданных. Скачанный JSON-ключ, заехавший в репозиторий, — самая частая и самая дорогая ошибка этого шага.

• roles/aiplatform.user — минимум для вызова модели из кода
• Права владельца или закупщика — для включения модели в Model Garden
• Отдельный сервис-аккаунт на каждый контур: dev, staging, prod
• Никаких скачанных ключей там, где работает привязанный сервис-аккаунт

Первый вызов: SDK и голый REST

Ставим SDK: pip install "anthropic[vertex]" для Python или npm i @anthropic-ai/vertex-sdk для Node. От обычного клиента отличается одна строка: from anthropic import AnthropicVertex; client = AnthropicVertex(project_id="my-project", region="us-east5"). Дальше всё привычно: client.messages.create(model=..., max_tokens=1024, system="Ты помощник службы поддержки. Отвечай по-русски, коротко.", messages=[{"role": "user", "content": "Как сбросить пароль?"}]). Текст обычно лежит в msg.content[0].text, но надёжнее пройти по блокам и взять первый текстовый.

Главная ловушка — идентификатор модели. У датированных версий на Vertex дата отделяется собакой, а не дефисом: claude-opus-4-5@20251101, а не claude-opus-4-5-20251101. Часть моделей зовётся тем же именем, что и в прямом API, вообще без даты. Отсюда правило: ID копируем с карточки в Model Garden, а не из чужого примера в блоге — иначе вы получите 404 и полдня будете чинить регион вместо одной строки с именем.

Полезно один раз увидеть, что происходит под капотом. Запрос уходит на https://REGION-aiplatform.googleapis.com/v1/projects/PROJECT/locations/REGION/publishers/anthropic/models/МОДЕЛЬ:rawPredict, для потокового ответа — на :streamRawPredict. В теле нет поля model (оно уже в URL), зато обязательно есть "anthropic_version": "vertex-2023-10-16". Заголовок авторизации — Bearer с результатом gcloud auth print-access-token. SDK делает это за вас, но при отладке curl быстрее показывает правду.

Расшифровка типичных ответов сервера: 403 — не хватает роли или модель не включена в проекте; 404 — неверный ID или модель не обслуживается в этом регионе; 400 — сломанное тело запроса, чаще всего роли в messages идут не по очереди; 429 — упёрлись в квоту; 529 или 503 — сервис перегружен, надо повторить позже.

Многошаговый диалог: модель ничего не помнит

Messages API не хранит состояние. Каждый вызов — это полный текст переписки заново: массив messages с чередующимися ролями user и assistant. Системная инструкция передаётся не сообщением, а отдельным параметром system. Если ждать, что модель «вспомнит» прошлый ход сама, диалог рассыплется на втором шаге.

Ответ модели кладите обратно в историю целиком, блоками, а не выдирайте текст: messages.append({"role": "assistant", "content": msg.content}). Как только появятся инструменты, это станет критично — в content лежат не только текстовые блоки. И всегда смотрите на stop_reason: end_turn означает, что модель договорила, max_tokens — что вы её обрезали на полуслове, tool_use — что она просит вызвать функцию.

Контекстное окно у нынешних моделей Claude — сотни тысяч токенов, у части моделей больше; точную цифру для конкретной версии держите не в голове, а на карточке модели. Важнее механика: весь контекст пересылается на каждом шаге, поэтому длинный диалог дорожает нелинейно — сотое сообщение тащит за собой девяносто девять предыдущих. Рабочие приёмы: держать окно последних N ходов, периодически заменять хвост краткой сводкой и включать кэширование префикса через cache_control для неизменной части — системного промпта, инструкций, справочника.

Инструменты (tool use): модель просит, код исполняет

Схема одинаковая на Vertex и на прямом API. Вы описываете набор функций: имя, описание и input_schema в формате JSON Schema. Модель, решив, что нужен вызов, возвращает stop_reason = tool_use и блок с полями id, name и input. Никакого кода она не запускает — исполняете вы, в своём процессе, со своими правами.

Результат возвращается следующим сообщением с ролью user, внутри которого блок типа tool_result с тем же tool_use_id и содержимым ответа. Если функция упала, не сочиняйте текст ошибки от себя — верните tool_result с is_error: true и коротким описанием, модель на это реагирует корректно. Цикл повторяется, пока stop_reason не станет end_turn; счётчик итераций (пяти-десяти обычно хватает) ставьте обязательно, иначе редкий сценарий превратится в бесконечный обмен.

Описание инструмента — это тоже промпт, и оно важнее аккуратного имени. Пишите в description, когда функцию использовать и когда не стоит, какие форматы допустимы, что означает пустой результат. Ограничения выражайте схемой: enum вместо фразы «допустимы только эти значения», required вместо «этот параметр обязателен». Такая правка почти всегда даёт больше, чем перебор формулировок в системном промпте.

Аргументы, пришедшие от модели, считайте недоверенным вводом — ровно как данные из веб-формы. Валидируйте типы и диапазоны, давайте инструменту минимальные права (пользователь БД только на чтение, ограниченный список путей), а на действия, которые нельзя откатить — списание денег, удаление, рассылку — ставьте подтверждение человеком.

RAG на кубиках Google

Сразу уберём частое ожидание: заземления на поиск Google у Claude в Vertex нет — это возможность моделей Gemini. Набор серверных инструментов Anthropic на партнёрских площадках вообще уже, чем в прямом API, так что сверяйтесь с документацией площадки. Поиск по вашим данным вы собираете сами: Google даёт готовые части, Claude отвечает за формулировку ответа.

Хранилище выбирается под масштаб. Vertex AI Vector Search — если корпус большой и нужна отдельная векторная база. AlloyDB или Cloud SQL с pgvector — если документы и так лежат в PostgreSQL и хочется искать рядом с бизнес-данными фильтрами SQL. Векторный поиск в BigQuery — когда всё уже в хранилище и терпимы секунды задержки. Vertex AI Search — когда не хочется собирать конвейер вручную. Эмбеддинги берутся у Google: моделей эмбеддингов у Anthropic нет, а для русского текста нужна мультиязычная версия.

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

Что проверять на этом этапе: помещаются ли фрагменты в бюджет контекста, честно ли модель говорит «в документах этого нет», совпадают ли процитированные идентификаторы с тем, что реально выдал поиск. Логируйте, какие фрагменты ушли в запрос: без этого разбор жалобы «модель выдумала» превращается в гадание.

Квоты, лимиты и деньги

Квоты в Vertex считаются на связку проект + регион + модель и выражаются в запросах и токенах в минуту. Смотреть их надо в разделе «IAM и администрирование» → «Квоты» с фильтром по aiplatform; там же подаётся запрос на повышение, и рассматривают его люди, то есть не мгновенно. Разбирайте 429 (квота) и 529/503 (перегрузка) одинаково по механике: повтор с экспоненциальной задержкой и случайным разбросом, а не цикл без пауз.

Когда нагрузка предсказуема и простой недопустим, есть Provisioned Throughput: вы платите за зарезервированную пропускную способность и перестаёте конкурировать за общую ёмкость. Для несрочной обработки, наоборот, дешевле пакетный режим — задания уходят в очередь, результат приезжает с задержкой, тариф ниже.

Платите вы за токены, а не за время: считаются входные и выходные, ставка указывается за миллион. Выход стоит заметно дороже входа, запись в кэш — чуть дороже обычного ввода, чтение из кэша — в разы дешевле. Конкретные цифры не запоминайте: у партнёрских моделей своя страница цен Vertex AI, и она меняется. Считать по табличке годовой давности — верный способ ошибиться в оценке в разы.

Считайте не по прикидке, а по факту: в каждом ответе есть usage с input_tokens и output_tokens. Пишите их в метрики вместе с идентификатором сценария — так видно, какая функция продукта съедает бюджет. Сверху поставьте бюджетные оповещения в Billing, а квоту используйте как предохранитель: заниженный лимит на дев-проекте дешевле, чем цикл, случайно ушедший в бесконечность.

Продакшен-практики

Фиксируйте конкретную версию модели в конфиге, а не берите «самую свежую». Переезд на новую версию делайте отдельным шагом: прогоните набор реальных примеров (несколько десятков — уже показательно) через старую и новую модель, сравните ответы глазами или моделью-судьёй и только потом переключайте трафик. Промпты и тестовый набор храните в репозитории рядом с кодом: они такая же часть системы, как SQL-миграции.

Отвечайте потоком там, где ответ читает человек: :streamRawPredict заметно улучшает ощущение скорости, даже если общее время не изменилось. Таймауты ставьте выше, чем привыкли для обычных HTTP-вызовов, — длинный ответ на большом контексте легко идёт минуту. Сетевые сбои и 429 закрывайте ретраями, но с ограничением попыток и понятной деградацией: заранее решите, что показывает интерфейс, когда модель недоступна.

Для устойчивости держите запасной регион с включённой той же моделью и переключайтесь на него при серии ошибок. Разнесите контуры по разным проектам GCP, чтобы нагрузочные тесты не выедали продовую квоту. В логи не пишите персональные данные и содержимое пользовательских документов — храните хеши и идентификаторы запросов, для расследования инцидентов этого хватает.

И то, о чём вспоминают поздно: текст от пользователя — это данные, а не команды. Заворачивайте его в явные границы, не позволяйте ему менять системную инструкцию, ограничивайте длину входа, а решения о деньгах, доступах и удалении оставляйте за кодом с проверками, а не за формулировкой в ответе модели.

Практика

Проверьте себя

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

Похожие уроки