# Как подключить модели OpenAI через Google Cloud: пошаговая настройка доступа и ключей > AI Release · @ai_release1 · https://ai-release.org/guides/kak-podklyuchit-modeli-openai-cherez-google-cloud-posha.html ## TL;DR - Время выполнения: 30–45 минут (без учёта времени на одобрение доступа к конкретной модели в Model Garden — для части моделей требуется отдельная заявка). - Уровень сложности: Intermediate - Понадобится: проект Google Cloud с привязанным биллингом; gcloud CLI (версию сверьте командой `gcloud version` и с документацией); права Owner либо набор ролей `roles/serviceusage.serviceUsageAdmin`, `roles/iam.serviceAccountAdmin`, `roles/resourcemanager.projectIamAdmin`, `roles/aiplatform.user`; `curl`; Python 3 с pip и пакетами `google-auth`, `openai`; включённый API `aiplatform.googleapis.com`. ## Требования и подготовка ![Иллюстрация к разделу «Требования и подготовка»](https://ai-release.org/guides/img/kak-podklyuchit-modeli-openai-cherez-google-cloud-posha-ru-1.jpg) Что понадобится по компонентам: | Компонент | Что это (одной фразой) | Зачем в этой схеме | |---|---|---| | Vertex AI | платформа Google Cloud для запуска моделей | принимает ваш HTTP-запрос и передаёт его модели | | Model Garden | каталог моделей внутри Vertex AI | здесь включается доступ к моделям OpenAI | | Сервисный аккаунт | «технический пользователь» без пароля | от его имени код получает OAuth2-токен | | IAM | управление правами в Google Cloud | роль `roles/aiplatform.user` разрешает вызывать модель | | OAuth2 access token | временный токен доступа (живёт около часа) | подставляется в заголовок `Authorization: Bearer …` вместо API-ключа | Чек-лист подготовки: - [ ] ОС: Linux, macOS или Windows 10/11 (PowerShell 7 либо WSL2) — gcloud CLI работает во всех трёх. - [ ] Аккаунт Google Cloud и проект, у которого в разделе Billing привязан платёжный аккаунт. Без биллинга партнёрские модели не включаются. - [ ] gcloud CLI установлен: `gcloud version` печатает список компонентов, а не «command not found». - [ ] Python 3 и pip: `python3 --version` и `pip3 --version` отвечают без ошибок. - [ ] Пакеты Python: `pip3 install --upgrade google-auth openai`. - [ ] `curl` доступен: `curl --version`. Поток запроса выглядит так — держите эту схему перед глазами: 1. Ваш скрипт читает файл сервисного аккаунта (JSON) или credentials активного пользователя. 2. Библиотека `google-auth` обменивает их на OAuth2 access token. 3. Токен уходит в заголовке `Authorization: Bearer ` на OpenAI-совместимый endpoint Vertex AI в выбранном регионе. 4. Vertex AI передаёт запрос модели OpenAI, включённой в Model Garden. 5. Ответ возвращается в формате OpenAI Chat Completions — с полями `choices`, `usage` и т. д. Если позже понадобится ходить из одного кода сразу в несколько провайдеров, пригодится отдельный гайд: [Как объединить несколько ИИ-провайдеров в один API](https://ai-release.org/guides/kak-obedinit-neskolko-ii-provayderov-v-odin-api-nastroy.html?utm_source=tg&utm_medium=channel&utm_campaign=guide_inline&utm_content=guide_to_guide). **Пример:** проект называется `my-ai-lab-2026`, регион — `us-central1`. Ниже эти значения подставляются вместо плейсхолдеров `` и ``. **Как проверить:** `gcloud projects describe my-ai-lab-2026 --format="value(lifecycleState)"` → должно напечататься `ACTIVE`. ## Шаг 1. Авторизация в gcloud, выбор проекта и включение API **Что сделать:** войдите в аккаунт, зафиксируйте проект по умолчанию и включите API Vertex AI. ```bash gcloud auth login gcloud config set project my-ai-lab-2026 gcloud services enable aiplatform.googleapis.com ``` Для локальных скриптов, которые используют credentials пользователя (ADC — Application Default Credentials, «учётные данные по умолчанию»), дополнительно: ```bash gcloud auth application-default login ``` **Зачем:** `aiplatform.googleapis.com` — тот самый API, который обслуживает запросы к моделям. Пока он выключен, любой вызов вернёт ошибку о недоступности сервиса, даже при корректных правах. `gcloud auth application-default login` создаёт локальный файл с credentials, который библиотека `google-auth` находит автоматически. **Как проверить:** ```bash gcloud config list --format="value(core.project)" gcloud services list --enabled --filter="config.name:aiplatform.googleapis.com" ``` Ожидаемый результат: первая команда печатает `my-ai-lab-2026`, вторая — строку, в которой присутствует `aiplatform.googleapis.com`. Пустой вывод второй команды означает, что API ещё не включился: подождите минуту и повторите. **Пример:** `gcloud config list` показывает `core.project = my-ai-lab-2026`, а `gcloud services list --enabled` содержит `aiplatform.googleapis.com Vertex AI API`. ## Шаг 2. Сервисный аккаунт, права IAM и включение модели в Model Garden ![Иллюстрация к разделу «Шаг 2. Сервисный аккаунт, права IAM и включение модели в Model Garden»](https://ai-release.org/guides/img/kak-podklyuchit-modeli-openai-cherez-google-cloud-posha-ru-2.jpg) **Что сделать:** создайте сервисный аккаунт, выдайте ему роль `roles/aiplatform.user`, скачайте JSON-ключ и включите нужную модель OpenAI в Model Garden. ```bash gcloud iam service-accounts create vertex-ai-client \ --display-name="Vertex AI client" gcloud projects add-iam-policy-binding my-ai-lab-2026 \ --member="serviceAccount:vertex-ai-client@my-ai-lab-2026.iam.gserviceaccount.com" \ --role="roles/aiplatform.user" mkdir -p ~/keys gcloud iam service-accounts keys create ~/keys/vertex-ai-client.json \ --iam-account=vertex-ai-client@my-ai-lab-2026.iam.gserviceaccount.com chmod 600 ~/keys/vertex-ai-client.json export GOOGLE_APPLICATION_CREDENTIALS="$HOME/keys/vertex-ai-client.json" ``` В PowerShell те же два последних шага выглядят так: ```powershell gcloud iam service-accounts keys create $HOME\keys\vertex-ai-client.json ` --iam-account=vertex-ai-client@my-ai-lab-2026.iam.gserviceaccount.com $env:GOOGLE_APPLICATION_CREDENTIALS = "$HOME\keys\vertex-ai-client.json" ``` **Зачем:** сервисный аккаунт — это «бот» внутри проекта: у него нет пароля, вход выполняется по JSON-ключу. Роль `roles/aiplatform.user` даёт право отправлять запросы к моделям, но не менять настройки проекта. Переменная `GOOGLE_APPLICATION_CREDENTIALS` сообщает библиотекам Google, где лежит ключ, — код не содержит секретов. Затем включите модель: Console → **Vertex AI** → **Model Garden** → найдите карточку нужной модели OpenAI → кнопка подключения/включения модели в вашем проекте. Точные названия кнопок, список доступных моделей и регионов, а также идентификаторы моделей (``) сверьте с документацией Vertex AI — они меняются. **Пример:** после включения вызываем endpoint обычным `curl`. Токен берём у пользователя, чтобы отделить проблемы прав от проблем ключа: ```bash TOKEN="$(gcloud auth print-access-token)" curl -sS \ -X POST \ -H "Authorization: Bearer ${TOKEN}" \ -H "Content-Type: application/json" \ "https://us-central1-aiplatform.googleapis.com/v1/projects/my-ai-lab-2026/locations/us-central1/endpoints/openapi/chat/completions" \ -d '{ "model": "", "messages": [{"role": "user", "content": "Ответь одним словом: столица Франции?"}] }' ``` Почему это работает: заголовок `Authorization` подтверждает личность, путь `/projects//locations//endpoints/openapi/chat/completions` указывает проект, регион и OpenAI-совместимый шлюз, а поле `model` выбирает включённую модель. Формат пути и поддержку регионов сверьте с документацией — часть моделей доступна не во всех регионах. **Как проверить:** ```bash gcloud projects get-iam-policy my-ai-lab-2026 \ --flatten="bindings[].members" \ --filter="bindings.members:vertex-ai-client@my-ai-lab-2026.iam.gserviceaccount.com" \ --format="table(bindings.role)" ``` Ожидаемый результат: таблица с одной строкой `roles/aiplatform.user`. Если таблица пустая — привязка роли не выполнилась, повторите `add-iam-policy-binding`. ## Шаг 3. Проверка работы из кода и фиксация конфигурации ![Иллюстрация к разделу «Шаг 3. Проверка работы из кода и фиксация конфигурации»](https://ai-release.org/guides/img/kak-podklyuchit-modeli-openai-cherez-google-cloud-posha-ru-3.jpg) **Что сделать:** вызовите модель из Python через официальный SDK `openai`, подставив токен вместо API-ключа. ```python import google.auth from google.auth.transport.requests import Request from openai import OpenAI PROJECT_ID = "my-ai-lab-2026" REGION = "us-central1" MODEL_ID = "" # идентификатор из карточки модели в Model Garden creds, _ = google.auth.default(scopes=["https://www.googleapis.com/auth/cloud-platform"]) creds.refresh(Request()) client = OpenAI( base_url=f"https://{REGION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{REGION}/endpoints/openapi", api_key=creds.token, ) resp = client.chat.completions.create( model=MODEL_ID, messages=[{"role": "user", "content": "Ответь одним словом: столица Франции?"}], ) print(resp.choices[0].message.content) print(resp.usage) ``` **Зачем:** это тот же запрос, что и `curl`, но через привычный SDK. `google.auth.default()` читает переменную `GOOGLE_APPLICATION_CREDENTIALS` (или ADC пользователя), `creds.refresh()` получает свежий токен, а `base_url` переключает SDK с api.openai.com на шлюз Google Cloud. Поэтому отдельный ключ OpenAI не нужен. **Пример вывода на экране:** ``` Париж CompletionUsage(completion_tokens=2, prompt_tokens=20, total_tokens=22) ``` Конкретные значения `usage` зависят от модели и токенизатора — важна сама структура ответа. Сохраните рабочую конфигурацию, чтобы не повторять шаги: ```bash cat > ~/.vertex-openai.env <<'EOF' export GOOGLE_APPLICATION_CREDENTIALS="$HOME/keys/vertex-ai-client.json" export VERTEX_PROJECT="my-ai-lab-2026" export VERTEX_REGION="us-central1" export VERTEX_MODEL="" EOF source ~/.vertex-openai.env ``` **Как проверить (чек-лист успеха):** - [ ] `echo $GOOGLE_APPLICATION_CREDENTIALS` печатает путь к JSON-ключу. - [ ] `curl` из шага 2 возвращает JSON с непустым массивом `choices`. - [ ] Скрипт из шага 3 печатает текст ответа, а не трассировку исключения. - [ ] `ls -l ~/keys/vertex-ai-client.json` показывает права `-rw-------` (файл читает только владелец). Если нужен доступ к модели, запущенной локально, а не в облаке, логика «OpenAI-совместимый endpoint + ключ» повторяется один в один: [Как подключить локальную модель к Claude Code](https://ai-release.org/guides/kak-podklyuchit-lokalnuyu-model-k-claude-code-llama-ser.html?utm_source=tg&utm_medium=channel&utm_campaign=guide_inline&utm_content=guide_to_guide). ## Возможные проблемы и решения **Проблема. Модель отвечает отказом в доступе, хотя API включён** - Ошибка вида: `403 PERMISSION_DENIED: Permission 'aiplatform.endpoints.predict' denied on resource '//aiplatform.googleapis.com/projects/my-ai-lab-2026/locations/us-central1/publishers/openai/models/'`. - Причина: у сервисного аккаунта нет роли `roles/aiplatform.user`, либо роль выдана на другом проекте, либо модель не включена в Model Garden этого проекта. - Решение: проверьте привязку роли командой из шага 2 и при необходимости выдайте её повторно; затем откройте Model Garden и убедитесь, что модель подключена именно к `my-ai-lab-2026`. ```bash gcloud projects add-iam-policy-binding my-ai-lab-2026 \ --member="serviceAccount:vertex-ai-client@my-ai-lab-2026.iam.gserviceaccount.com" \ --role="roles/aiplatform.user" ``` **Проблема. Python не находит ключ** - Ошибка: `google.auth.exceptions.DefaultCredentialsError: Your default credentials were not found. To fix this, run 'gcloud auth application-default login'`. - Причина: переменная `GOOGLE_APPLICATION_CREDENTIALS` не задана в текущей сессии терминала (частая ситуация после перезапуска или в другом окне), либо путь указывает на несуществующий файл. - Решение: подключите сохранённый env-файл и проверьте путь. ```bash source ~/.vertex-openai.env test -f "$GOOGLE_APPLICATION_CREDENTIALS" && echo OK ``` **Проблема. Ресурс не найден** - Ошибка вида: `404 NOT_FOUND: Publisher Model ... was not found in location europe-west4`. - Причина: выбран регион, где эта модель OpenAI недоступна, либо в поле `model` стоит неверный идентификатор. - Решение: переключитесь на регион из документации (в примерах выше — `us-central1`), исправив `base_url`/URL и `VERTEX_REGION`, и скопируйте идентификатор модели из карточки Model Garden без опечаток. ## Резюме и следующие шаги Доступ к моделям OpenAI через Google Cloud строится на трёх вещах: включённом `aiplatform.googleapis.com`, сервисном аккаунте с ролью `roles/aiplatform.user` и запросе на OpenAI-совместимый endpoint Vertex AI с OAuth2-токеном вместо API-ключа. Дальше имеет смысл вынести ключ в секрет-хранилище, добавить `try/except` на ошибки 401/403/404 и сверить актуальный список моделей, регионов и лимитов с документацией. ## FAQ **Нужен ли отдельный API-ключ OpenAI?** Нет: доступ идёт через идентичность Google Cloud, а в поле `api_key` SDK `openai` подставляется OAuth2 access token, полученный через `google-auth`. **Можно ли пользоваться привычным SDK `openai`?** Да, достаточно заменить `base_url` на OpenAI-совместимый endpoint Vertex AI в вашем проекте и регионе; остальной код с `chat.completions.create` остаётся прежним. **Где хранить JSON-ключ сервисного аккаунта?** Не в git и не в коде: положите файл вне репозитория, ограничьте права (`chmod 600`) и передавайте путь через переменную окружения или секрет-хранилище. **Чем это отличается от прямого доступа к API OpenAI?** Биллинг идёт через ваш проект Google Cloud, права управляются через IAM, а доступность модели зависит от региона и включения в Model Garden; актуальные модели, регионы и лимиты сверьте с документацией.