Перейти к содержанию

Диагностика интеграции с Яндекс Облаком

Эта страница предназначена для ситуаций, когда интеграция уже настроена полностью или частично, но одна из функций не работает.

Главное правило диагностики:

Не повышайте роли и не пересоздавайте всё подряд, пока не определили слой, на котором возникла ошибка.

Интеграция состоит из нескольких независимых частей:

ИИ Студия
    ↓
NiceSoft Gateway
    ↓
authorized key
    ↓
IAM-token
    ↓
Working Folder / Billing Account / AI Studio Folder
    ↓
конкретный Yandex Cloud API

Ошибка на одном уровне не означает поломку всех остальных.

Быстрый алгоритм

Если нужно начать прямо сейчас:

1. Откройте Интеграция с YC.
2. Проверьте наличие authorized key.
3. Выполните ./nicesoft.sh yc-doctor.
4. Проверьте IAM auth available.
5. Проверьте paired Folder.
6. Определите, какой именно сервис не работает.
7. Проверьте роль именно в нужной области доступа.
8. Повторите один минимальный тест.
9. Зафиксируйте request-id при 4xx/5xx.

1. Сначала определите симптом

Не начинайте с логов, пока не можете сформулировать проблему одной строкой.

Хорошие формулировки:

Authorized key загружен, но Folder не подключается.

ВМ читаются, но Billing возвращает 403.

Инфраструктура работает, Yandex AI — 403.

Billing работает, но показывает старые данные.

Официальная документация не ищется даже без подключения Cloud.

Плохая формулировка:

YC не работает.

2. Разделите интеграцию на независимые контуры

Проверяйте отдельно:

Контур Основной область доступа Типичная зависимость
Инфраструктура рабочий каталог роль IAM только для чтения
Документация внешний официальный сервис привязка может не требоваться
Поиск Яндекса отдельный внешний сервис service permission/configuration
FinOps платёжный аккаунт + область рабочего каталога пользователя billing.accounts.viewer
Yandex AI каталог AI Studio ai.languageModels.user

То, что один контур работает, не доказывает состояние другого.

3. Главный инструмент: yc-doctor

На хосте Студии выполните:

./nicesoft.sh yc-doctor

Команда должна показать безопасную диагностику без раскрытия закрытый ключ и IAM-token.

Типовые поля:

YC Gateway: <version>
Access mode: locked
Источник учётных данных: authorized_key
IAM auth available: YES/NO
Authorized key file: present / readable
Folder configured: YES/NO
Cloud configured: YES/NO

Дополнительно проверяется доступ к внешний сервис-сервисам Яндекс Облака и состояние привязка.

4. Как читать yc-doctor

Источник учётных данных: authorized_key

Нормальное состояние для текущего профиля.

Authorized key file: present / readable

Файл существует и процесс шлюз способен его прочитать.

Это ещё не доказывает, что ключ действующий.

IAM auth available: YES

Шлюз успешно смог получить IAM учётные данные.

Это сильный признак того, что:

  • JSON валиден;
  • закрытый ключ подходит;
  • служебная учётная запись существует;
  • ключ не отозван;
  • адрес IAM доступен.

Folder configured: NO

Учётные данные есть, но рабочая область ещё не выбрана.

Это не ошибка IAM.

5. Состояние: ключ есть, каталог не выбран

Пример логического состояния:

Источник учётных данных: authorized_key
IAM auth available: YES
Authorized key file: present / readable
Folder configured: NO
Cloud configured: NO

Это означает:

аутентификация работает
        ↓
рабочая область доступа ещё не подключена

Исправление

Откройте:

Интеграция с YC → Подключение YC.

Введите идентификатор каталога.

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

Нажмите:

Проверить указанные ID и подключить.

После этого повторите:

./nicesoft.sh yc-doctor

6. Ключ не загружен

Симптом:

Authorized key file: missing

или интерфейс сообщает, что учётные данные не настроен.

Проверьте:

  1. был ли JSON действительно загружен;
  2. не удалялся ли шлюз state;
  3. не выполнялось ли восстановление из неполного backup;
  4. не сменился ли volume/path;
  5. доступен ли файл процессу.

Не вставляйте закрытый ключ вручную в .env, если штатная процедура Студии использует загрузку JSON авторизованного ключа.

7. JSON не принимается

Возможные причины:

  • загружен не авторизованный ключ;
  • файл повреждён;
  • отсутствует закрытый ключ;
  • используется неверный формат;
  • ключ относится не к служебной учётной записи;
  • повреждены переносы PEM;
  • файл был вручную отредактирован.

Создайте новый авторизованный ключ штатным способом и скачайте JSON заново.

Не пытайтесь «починить» закрытый ключ текстовым редактором.

8. IAM auth недоступна

Симптом:

IAM auth available: NO

Проверяйте последовательно.

Шаг 1. Файл ключа

Файл присутствует и readable?

Шаг 2. Служебная учётная запись

Служебная учётная запись существует?

Не был ли он удалён?

Шаг 3. Объект ключа

Не был ли авторизованный ключ удалён в IAM?

Шаг 4. Время сервера

JWT чувствителен ко времени.

Проверьте системное время и NTP.

timedatectl status

Шаг 5. DNS/HTTPS

Host должен иметь исходящий HTTPS-доступ к IAM API Яндекс Облака.

Шаг 6. Proxy/firewall

Проверьте корпоративный proxy, firewall и TLS inspection.

9. Ключ удалён в Яндекс Облаке

Локальный JSON может продолжать существовать, но соответствующий идентификатор ключа уже отозван.

Симптом:

file present
IAM auth unavailable

Создайте новый авторизованный ключ, загрузите его и повторите проверку.

Удаление старого ключа — правильный способ отзыва утекшего учётные данные.

10. идентификатор каталога неверный

Симптомы:

  • привязка не проходит;
  • каталог not found;
  • 404;
  • permission denied при проверке;
  • идентификатор облака не совпадает.

Проверьте идентификатор каталога в консоли Яндекс Облака.

Не используйте:

  • имя каталога вместо ID;
  • идентификатор облака вместо идентификатор каталога;
  • ID из другой организации;
  • пробелы/кавычки из скопированного текста.

11. идентификатор облака и идентификатор каталога не совпадают

Если вы вручную указали оба значения, возможна ошибка:

Folder A belongs to Cloud X
но введён Cloud Y

Лучший способ диагностики:

  1. подтвердите идентификатор каталога;
  2. получите облако из самого каталог;
  3. не подставляйте идентификатор облака по памяти.

В типовом сценарии облако определяется сервером из проверенного каталог.

12. Привязка прошёл, но ресурсов нет

Не делайте сразу вывод, что integration broken.

Возможные причины:

  1. в подключённый рабочий каталог действительно нет таких ресурсов;
  2. ресурс находится в другом каталог;
  3. служебная учётная запись не имеет роли нужного сервиса;
  4. запрос модели слишком общий;
  5. выбран не тот сервис Студии;
  6. фильтр запроса исключил результат;
  7. внешний сервис API вернул пустой список.

Начните с конкретного запроса:

Перечисли все виртуальные машины рабочего Folder и укажи их ID и status.

13. ВМ видны не все

Проверьте, не распределена ли инфраструктура по нескольким каталог.

Например:

prod-app
prod-db
shared-network

При привязка только prod-app нормальным результатом может быть отсутствие ресурсов из prod-db.

Студия не должна автоматически расширять область доступа на соседние каталог.

14. Compute работает, VPC не работает

Это часто IAM, а не шлюз.

Проверьте роль:

vpc.viewer

или более широкую разрешённую роль только для чтения на рабочий каталог.

Если используется granular profile, работоспособность Compute не доказывает наличие VPC permissions.

15. VPC работает, Object Storage недоступен

Определите, какой уровень нужен.

Для конфигурации:

storage.configViewer

Для чтения содержимого:

storage.viewer

Не выдавайте storage.viewer просто для устранения ошибки, если содержимое бакетов пользователю не должно быть доступно.

16. Ресурс виден в консоли администратора, но не виден Студии

Ваша личная учётная запись и служебная учётная запись Студии — разные субъекты IAM.

То, что администратор видит ресурс в браузере, не означает, что его видит служебная учётная запись.

Проверяйте назначения ролей именно для:

SERVICE_ACCOUNT_ID

17. Роль есть, но всё равно 403

Проверьте пять вещей:

роль
resource, на котором она назначена
наследование
фактический resource ID запроса
access policy

Особенно важно: access policy Organization/облако/каталог может блокировать операцию, даже если роль permission существует.

18. Не исправляйте 403 через admin

Если 403 исчез после выдачи admin, это не означает, что admin был нужен.

Вы могли просто скрыть:

  • неверный область доступа;
  • неправильный каталог;
  • недостающую сервисная роль;
  • access policy;
  • ошибку платёжный аккаунт;
  • AI Studio роль на другом каталог.

Верните минимальные права и найдите конкретное missing permission.

19. Документация Яндекс Облака не работает

Сервис официальной документации логически отделён от вашего рабочего каталога.

Поэтому ситуация:

Folder не paired
но поиск документации работает

нормальна.

И наоборот, если инфраструктура работает, а документация нет, это не обязательно IAM служебная учётная запись.

Проверьте:

  • сеть;
  • доступ шлюз к официальному сервису документации;
  • DNS;
  • timeout;
  • доступность самого внешнего сервиса.

20. Yandex Search не работает

Это отдельный внешний контур.

Проверьте:

  • включён ли сервис;
  • есть ли необходимые cloud permissions/configuration;
  • исходящий HTTPS;
  • идентификатор запроса ошибки;
  • ограничения аккаунта/квоты.

Не путайте его с локальным интернет-поиском Студии через SearXNG.

Это две разные поисковые функции.

21. Billing: 403 PERMISSION_DENIED

Самая частая причина — отсутствует:

billing.accounts.viewer

на нужном платёжный аккаунт.

Проверьте, что роль назначена:

  • именно служебная учётная запись Студии;
  • именно на платёжный аккаунт;
  • именно того облака, расходы которого анализируются.

22. Billing роль назначена на каталог

Это типичная ошибка.

Симптом:

инфраструктура работает
Billing 403

Потому что:

viewer → Folder

и:

billing.accounts.viewer → Billing Account

решают разные задачи.

23. Billing показывает 0

Ноль не всегда ошибка.

Проверьте:

  1. выбранный период;
  2. подключённый рабочий каталог;
  3. есть ли billable usage;
  4. правильный платёжный аккаунт;
  5. применённые credits;
  6. задержку формирования usage;
  7. валюту/единицу;
  8. фильтры.

Запросите детализацию по сервисам.

Если все значения сервисов равны нулю, сравните с официальным Billing интерфейс за тот же период и область доступа.

24. cost и expense не совпадают

Это нормально.

Упрощённо:

cost = стоимость до credits/discounts
credits = применённые скидки/компенсации
expense = сумма после них

Не диагностируйте разницу как ошибку до проверки этих полей.

25. Сумма в Студии отличается от закрывающих документов

Usage API может содержать предварительные данные.

Также проверьте:

  • одинаковый ли период;
  • timezone;
  • тот же платёжный аккаунт;
  • тот же каталог filter;
  • cost или expense сравнивается;
  • credits;
  • поздние корректировки.

Для бухгалтерской финализации источником истины являются официальные закрывающие документы Billing, а не прогноз FinOps.

26. Billing показывает старые данные

NiceSoft FinOps намеренно использует cache.

Типовые TTL текущего профиля:

оперативный snapshot ≈ 15 минут
подробный drill-down ≈ 1 час
закрытая история ≈ 24 часа

Поэтому повторный вопрос через несколько секунд может использовать тот же snapshot.

Это оптимизация, а не обязательно сбой.

27. Когда подозревать cache проблему

Подозревайте cache, если:

  • официальные данные заметно изменились;
  • прошло больше ожидаемого TTL;
  • Студия продолжает возвращать старый snapshot;
  • timestamp snapshot не обновляется;
  • FinOps health показывает ошибку refresh.

Тогда проверьте FinOps service health и шлюз logs.

28. Billing drill-down не показывает ресурс

Возможные причины:

  • расход агрегирован на уровне SKU без resource ID;
  • конкретный сервис не отдаёт ожидаемую ресурсную детализацию;
  • выбран короткий период без usage;
  • cache ещё не обновлён;
  • фильтр подключённого рабочего каталога исключает ресурс;
  • resource был удалён, а usage относится к прошлому периоду.

Не заставляйте модель придумывать resource attribution при отсутствии данных.

29. Labels дают странную группировку

Labels полезны для cost allocation, но качество результата зависит от дисциплины labels в самой инфраструктуре.

Проверьте:

  • одинаково ли написаны ключи;
  • нет ли team, Team, team_name как трёх разных схем;
  • не изменялся ли label в течение периода;
  • есть ли label на всех ресурсах.

FinOps не может восстановить отсутствующую метку задним числом.

30. Forecast выглядит слишком высоким или низким

Forecast — производный показатель, а не счёт.

Проверьте:

  • сколько дней периода уже прошло;
  • не было ли одноразового всплеска;
  • не запускалась ли нагрузка только на несколько дней;
  • есть ли сезонность;
  • не применятся ли будущие credits;
  • какой snapshot использован.

Для нерегулярных нагрузок линейный прогноз может быть плохо применим.

31. Advisor советует оптимизацию без достаточных данных

Правильный FinOps Advisor должен быть evidence-first.

Если причина не подтверждена snapshot, попросите:

Покажи факты, на которых основана рекомендация.
Для каждого вывода укажи service, SKU/resource, период и величину.
Если данных недостаточно — прямо отметь это.

Если доказательств нет, рекомендацию нельзя считать установленным фактом.

32. Yandex AI: 403

Это отдельная ветка диагностики.

Проверьте:

ai.languageModels.user

на каталог AI Studio.

Не на платёжный аккаунт.

Не обязательно на рабочий каталог.

Не на объект служебной учётной записи как область доступа ресурса.

33. Как узнать каталог AI Studio

Откройте:

Модели → Yandex AI.

Студия показывает фактически определённый каталог AI Studio для подключённой служебной учётной записи.

Используйте именно этот ID при проверке роли.

34. Роль выдана на неправильный каталог

Очень типичный сценарий:

Working Folder = folder-prod
AI Studio Folder = folder-ai

ai.languageModels.user выдан на folder-prod

Результат:

инфраструктура работает
Yandex AI = 403

Исправление:

ai.languageModels.user → folder-ai

35. Нажмите «Проверить доступ»

После изменения роли не пытайтесь сразу диагностировать сложный чат.

Откройте Модели → Yandex AI и нажмите:

Проверить доступ.

Сначала должна пройти минимальная проверка доступности модельного API.

Только после этого активируйте managed model.

36. Yandex AI доступ есть, но нужная модель отсутствует

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

Возможные причины:

  • модель недоступна в текущем регионе/профиле;
  • модель изменила lifecycle;
  • ваш каталог не имеет доступа;
  • модель не входит в текущий curated catalog Студии;
  • API Яндекса временно не возвращает её.

Не подставляйте произвольный model ID вручную в шлюз.

37. Yandex AI активирован, но ответ всё ещё local

Проверьте:

  1. действительно ли ADMIN активировал модель;
  2. завершилась ли операция успешно;
  3. создаёте ли вы новый чат;
  4. какой model badge отображается у ответа;
  5. не было ли возврата к local после административного переключения.

Старый ответ не меняет свою атрибуцию после переключения модели.

38. Local модель сломалась, но Yandex AI не включился автоматически

Это правильное поведение.

Студия не должна silently fail over из локального приватного режима во внешний managed поставщик.

Если local недоступен:

  • исправьте локальную среду выполнения;
  • активируйте другую уже установленную local модель;
  • или ADMIN явно выберет Yandex AI.

39. x-data-logging-enabled: false и диагностика

Шлюз по текущей политике отключает на стороне сервера данные запроса logging для Yandex AI.

Поэтому при обращении в поддержку может быть меньше содержательных данных для анализа запроса.

Используйте:

  • x-request-id;
  • x-server-trace-id;
  • время;
  • model ID;
  • HTTP status;
  • безопасное описание симптома.

Не включайте логирование чувствительного запрос только ради удобства диагностики без отдельного решения организации.

40. Где найти идентификатор запроса

При ошибке интерфейс или шлюз может показать диагностический идентификатор запроса.

Сохраните его до повторного запуска, если проблема воспроизводится не всегда.

Для Yandex AI особенно полезны:

x-request-id
x-server-trace-id

Эти значения можно приложить к обращению в поддержку Яндекс Облака.

41. 401 Unauthorized

401 обычно указывает на проблему аутентификации, а не нехватку роли.

Проверяйте:

key существует?
key действующий?
JWT сформирован?
IAM token получен?
token не истёк?
запрос содержит нужный Authorization?

Начните с yc-doctor.

Если IAM auth available: NO, сначала исправьте учётные данные chain.

42. 403 Forbidden

403 чаще означает:

identity распознана
но операция не разрешена

Проверяйте:

  • роль;
  • область доступа;
  • унаследованные роли;
  • access policy;
  • NiceSoft user policy;
  • подключённый рабочий каталог;
  • платёжный аккаунт;
  • каталог AI Studio.

43. 404 Not Found

Возможные причины:

  • неправильный resource ID;
  • ресурс удалён;
  • адрес сервиса изменился;
  • resource находится в другом каталог;
  • сервис скрывает недоступный объект как not found.

Сначала подтвердите ID через официальную консоль и проверенный запрос списка.

44. 429 Too Many Requests

Это ограничение частоты или квоты.

Не лечите его повышением IAM роль.

Проверьте:

  • частоту повторов;
  • параллельные задания;
  • плановые помощники;
  • несколько пользователей;
  • API quotas;
  • FinOps cache.

Для Billing NiceSoft специально кэширует и ограничивает повторные обращения, чтобы не дергать внешний сервис на каждый вопрос.

45. Timeout

Timeout может возникать на любом внешнем этапе.

Проверьте:

DNS
маршрут
firewall
proxy
TLS
доступность Yandex service
размер ответа
latency

Не увеличивайте timeout до бесконечности, пока не поняли причину.

46. DNS

На хосте проверьте резолвинг публичных адресов сервисов Яндекса.

Например:

getent hosts iam.api.cloud.yandex.net

Для AI Studio:

getent hosts ai.api.cloud.yandex.net

Если DNS не работает на host, application-level исправления не помогут.

47. Исходящий HTTPS

Интеграции нужны исходящие HTTPS-соединения к разрешённым сервисам Яндекс Облака.

В изолированной сети проверьте:

  • egress firewall;
  • proxy;
  • DNS;
  • TLS CA;
  • маршрутизацию.

Не открывайте весь internet egress без необходимости — лучше использовать контролируемую сетевую policy.

48. TLS interception

Корпоративный proxy может подменять TLS-сертификаты.

Симптомы:

  • certificate verify failed;
  • unknown CA;
  • HTTPS works in browser, fails in container.

Проверьте CA bundle внутри контейнерного контура.

Не отключайте TLS verification как постоянное решение рабочий-проблемы.

49. Студия работает из браузера, шлюз не выходит наружу

Browser connectivity и container egress — разные вещи.

Ваш ноутбук может открыть Яндекс Облако, а сервер Студии — нет.

Проверяйте сеть с хоста/контейнерного контура Студии.

50. Проверка состояния контейнеров

На сервере:

docker compose ps

Убедитесь, что основные сервисы имеют ожидаемый status.

Особенно важен шлюз Яндекс Облако.

Для его журналов:

docker compose logs --tail=200 yandex-gateway

Перед передачей логов третьей стороне выполните redaction.

51. Какие строки искать в шлюз logs

Полезны:

  • HTTP status;
  • safe error code;
  • внешний сервис service;
  • область доступа ресурса;
  • идентификатор запроса;
  • duration;
  • auth mode;
  • привязка status.

Не копируйте в тикет целиком строки, если они содержат Authorization или пользовательские данные.

52. интерфейс показывает старое состояние

Возможны:

  • browser cache;
  • старый polling result;
  • серверная часть cache;
  • незавершённое переключение.

Сначала обновите страницу.

Затем сравните интерфейс с:

./nicesoft.sh yc-doctor

Серверная диагностика важнее визуального badge.

53. После ротации ключа всё перестало работать

Проверьте последовательность:

новый ключ создан
        ↓
JSON действительно загружен
        ↓
IAM auth YES
        ↓
pairing сохранён/восстановлен
        ↓
roles принадлежат тому же service account

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

54. Новый ключ создан для другой служебной учётной записи

Симптом:

IAM auth works
но все service calls = 403

Проверьте service_account_id нового JSON.

Если account другой, нужно назначить ему необходимые роли.

Не копируйте старые роли автоматически без ревизии.

55. Служебная учётная запись удалён

Авторизованный ключ для удалённого account больше не должен быть рабочими учётными данными.

Создайте новую служебную учётную запись, назначьте минимальные роли и новый ключ.

Используйте это как повод проверить, почему account был удалён и нет ли других систем, которые от него зависели.

56. Роль назначена недавно

IAM изменения могут распространяться не абсолютно мгновенно.

После назначения:

  1. подождите короткий интервал;
  2. повторите минимальную проверку;
  3. не создавайте десять дополнительных роли за минуту.

Иначе будет трудно понять, какое изменение реально помогло.

57. Диагностируйте один слой за раз

Плохая процедура:

сменить key
выдать admin
сменить Folder
перезапустить всё
очистить cache

После неё система, возможно, заработает, но причина останется неизвестной.

Правильная:

одна гипотеза
        ↓
одно изменение
        ↓
один тест
        ↓
зафиксированный результат

58. Минимальные контрольные запросы

Используйте простые reproducible запросы.

Infrastructure

Перечисли ID и status всех ВМ рабочего Folder.

VPC

Перечисли сети и подсети рабочего Folder.

IAM

Покажи только для чтения список назначений ролей рабочего каталога.

Billing

Покажи expense рабочего Folder за последние 7 полных дней.

Docs

Найди в официальной документации Яндекс Облака страницу про роль compute.viewer.

Yandex AI

Используйте кнопку Проверить доступ, а затем короткий новый чат.

59. Не используйте сложный пользовательский запрос как проверка состояния

Запрос:

Проанализируй всю нашу инфраструктуру, найди проблемы, расходы и предложи оптимизацию

зависит сразу от множества сервисов.

Для диагностики он плох.

Сначала тестируйте атомарные возможности.

60. Проблема возникает только у одного пользователя

Если ADMIN работает, а USER нет:

подозревайте policy/RBAC Студии, а не служебная учётная запись IAM.

Проверьте:

  • роль пользователя Студии;
  • группы;
  • разрешённые сервисы;
  • пользовательский область доступа;
  • Billing ограничения;
  • настройки подтверждений.

61. Проблема возникает у всех пользователей

Если не работает даже ADMIN:

проверяйте общую инфраструктуру:

  • шлюз health;
  • авторизованный ключ;
  • IAM;
  • привязка;
  • внешний сервис availability;
  • сеть.

62. ADMIN видит больше Billing, чем USER

Это может быть ожидаемой политикой.

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

Не считайте различие багом, пока не сверились с корпоративной policy.

63. Запрос требует подтверждения, хотя режим YC только для чтения разрешён

Возможные причины:

  • выбран неизвестный инструмент;
  • операция не классифицирована как системная операция чтения;
  • после обновления появился новый метод;
  • администратор изменил policy;
  • модель выбрала не тот сервис.

Не отключайте подтверждение глобально для всех неизвестных действий.

Сначала проверьте, почему вызов не попал в разрешённую категорию операций только для чтения.

64. Студия отказывается изменять ресурс

Это не ошибка.

Например:

Останови VM
Удалить диск
Создать subnet
Изменить route
Опубликовать function

должны быть недоступны в профиле только для чтения.

Если ваша бизнес-задача требует изменений, это уже отдельный продуктовый/security сценарий, а не проблема текущей интеграции.

65. Документация говорит одно, API возвращает другое

Возможны:

  • rollout новой версии;
  • региональные различия;
  • deprecation;
  • permission differences;
  • устаревший документ;
  • устаревшая документация Студии.

Зафиксируйте:

URL документации
дату документа
API method
HTTP status
request ID
фактический response

И не заставляйте модель выбирать «правильную реальность» без доказательств.

66. Модель неправильно объяснила реальный API response

Разделяйте:

данные инструмента

и:

интерпретацию модели

Если результат операции содержит конкретный status/ID/amount, а текст ответа ему противоречит, доверяйте первичным данным и повторите запрос с просьбой:

Не делай предположений. Перечисли только факты из полученного ответа сервиса.

67. Ответ утверждает, что ресурс изменён

В текущем контуре только для чтения такое утверждение подозрительно.

Проверьте:

  • был ли вообще вызов операции;
  • какой результат операции вернулся;
  • не hallucination ли это;
  • состояние ресурса в официальной консоли.

Не считайте текст модели подтверждением выполненной операции.

68. Порядок полной диагностики

Если проблема сложная, пройдите весь маршрут.

A. Studio UI открывается?
B. Gateway healthy?
C. Authorized key present?
D. IAM auth YES?
E. Folder paired?
F. Cloud согласован?
G. Минимальный infrastructure read работает?
H. Нужная service role существует?
I. Access policy не блокирует?
J. Billing role настроена отдельно?
K. AI Studio role настроена отдельно?
L. Network/DNS/TLS работают?
M. Есть request-id ошибки?

Не переходите к следующему уровню, пока предыдущий не подтверждён.

69. Безопасный пакет для обращения в поддержку

Подготовьте:

Версия ИИ Студии:
Дата/время и timezone:
Роль пользователя: USER/ADMIN
Симптом:
Сервис: Infrastructure/Billing/Docs/Yandex AI/другое
HTTP status:
Safe error code:
Working Folder ID:
Cloud ID:
Billing Account ID: <если релевантно>
AI Studio Folder ID: <если релевантно>
Service Account ID:
yc-doctor output:
x-request-id:
x-server-trace-id:
Последнее изменение конфигурации:

Не прикладывайте JSON авторизованного ключа.

70. Что обязательно удалить из диагностического пакета

Перед отправкой проверьте отсутствие:

private_key
IAM token
Authorization header
Gateway secret
пароли
секреты Lockbox
закрытые сертификаты
полные пользовательские документы
персональные данные без необходимости

71. Когда проблема требует обращения в Яндекс Облако

Это вероятно, если:

  • IAM и область доступа проверены;
  • запрос воспроизводится вне Студии с той же служебной учётной записью;
  • внешний сервис возвращает стабильный 5xx;
  • модель отсутствует при корректных правах;
  • API ведёт себя не по актуальной документации;
  • есть x-request-id/x-server-trace-id для воспроизведения.

Приложите идентификаторы запросов и минимальный безопасный сценарий.

72. Когда проблема вероятнее в Студии

Это вероятно, если:

  • официальный API работает тем же учётные данные;
  • yc-doctor IAM показывает OK;
  • проблема возникает только через конкретный сервис Студии;
  • USER/ADMIN ведут себя неожиданно относительно policy;
  • область доступа подставляется неверно;
  • интерфейс показывает несогласованное состояние;
  • шлюз возвращает внутреннюю ошибку до запроса к внешнему сервису.

73. Когда проблема вероятнее в конфигурации заказчика

Это вероятно, если:

  • служебная учётная запись не имеет нужной роли;
  • роль назначена не на тот resource;
  • облако/каталог перепутаны;
  • access policy блокирует действие;
  • firewall запрещает egress;
  • корпоративный proxy ломает TLS;
  • служебная учётная запись или ключ удалены;
  • платёжный аккаунт не связан с нужным облаком.

74. После исправления обязательно сделайте regression check

Не останавливайтесь на тесте:

Теперь работает.

Проверьте, что исправление не расширило права.

После изменения IAM:

[ ] нужный запрос чтения работает
[ ] соседняя запрещённая область доступа не открылась
[ ] изменяющая операция всё ещё запрещена
[ ] Billing не стал account-wide для USER
[ ] Object Storage content не открылся случайно
[ ] Yandex AI boundary не изменилась

75. Контрольный сценарий полной интеграции

После первоначальной настройки или крупного обновления выполните:

1. Учётные данные

./nicesoft.sh yc-doctor

Ожидается IAM OK.

2. Привязка

рабочий каталог и облако определены.

3. Compute

Запросите список ВМ.

4. VPC

Запросите сети и подсети.

5. IAM

Запросите безопасный список назначения ролей.

6. Negative test

Попросите остановить VM — ожидается отказ.

7. Documentation

Найдите официальную страницу по роли.

8. Billing

Если включён — получите overview.

9. Yandex AI

Если включён — выполните Проверить доступ и короткий тестовый запрос.

10. Attribution

Проверьте фактическую модель ответа.

76. Матрица симптомов

Симптом Вероятный слой Первое действие
Ключ отсутствует учётные данные проверить загрузку JSON
IAM NO authentication ключ/служебная учётная запись/сеть/время
IAM YES, каталог NO привязка подключить каталог
Infrastructure 403 IAM/область доступа проверить роль на рабочий каталог
Только VPC 403 сервисная роль проверить vpc.viewer
Billing 403 Billing IAM billing.accounts.viewer на платёжный аккаунт
Billing 0 period/область доступа/data сверить период и каталог
Billing stale cache проверить snapshot timestamp/TTL
AI 403 AI IAM ai.languageModels.user на каталог AI Studio
AI model missing availability/catalog выполнить probe
Docs unavailable external service/network проверить egress/DNS
USER fail, ADMIN OK Studio RBAC проверить user policy
Все fail шлюз/учётные данные/network yc-doctor, health
429 quota/rate снизить частоту, проверить квоты
TLS error proxy/CA проверить trust store

77. Что не делать

Не используйте следующие «универсальные исправления»:

выдать admin
выдать editor
отключить TLS verification
разрешить весь интернет
положить IAM token в браузер
скопировать private key в чат
отключить server-side policy
разрешить все неизвестные операции

Если проблема исчезла после такого изменения, вы, вероятно, обменяли диагностическую проблему на security-проблему.

78. После решения задокументируйте причину

Внутренняя запись должна содержать:

Симптом
Корневая причина
Как диагностировали
Какое минимальное изменение внесли
Какие права изменились
Какие negative tests выполнены
Нужно ли обновить документацию

Так следующая аналогичная проблема решится намного быстрее.

Официальная документация

Для проверки поведения Яндекс Облака используйте актуальные официальные источники:

Если проблема остаётся

Соберите безопасный диагностический пакет из раздела выше и передайте администратору ИИ Студии. Не отправляйте ключи, токены и приватные данные даже если вас просят «просто для проверки».