Сначала разберитесь в основных терминах ИИ и AI-провайдеров
Если вы столкнулись с понятиями Key, Base URL, названием модели, множителем и кодами ошибок, сначала загляните сюда, чтобы разобраться в терминах перед интеграцией и устранением неполадок.
Основные термины ИИ
| Термин | Простое объяснение | На что обратить внимание новичкам? |
|---|---|---|
| Модель | Возможности ИИ, которые непосредственно отвечают на вопросы, пишут код и генерируют изображения или видео. | Название модели необходимо копировать в точности из панели управления провайдера; не меняйте регистр букв, дефисы или номера версий самостоятельно. |
| Большая модель | Общий термин для моделей, способных работать с задачами на естественном языке, кодом, изображениями и т. д. | Более дорогая модель не обязательно лучше подойдет для вашей задачи; разные модели могут быть оптимальны для текста, программирования, изображений или видео. |
| Мультимодальность | Способность одной и той же модели обрабатывать различные типы входных данных: текст, изображения, аудио или видео. | Поддержка мультимодальности в инструменте не означает, что ваш провайдер и текущая модель также ее поддерживают. |
| Промпт / Инструкция | Запрос, который вы отправляете ИИ, например: «Помоги мне обобщить этот текст». | Чем конкретнее промпт, тем проще получить применимый результат. |
| Системный промпт | Правила с более высоким приоритетом, чем обычные вопросы; часто используются для задания роли, стиля и рамок безопасности. | Системные промпты в инструментах для написания кода влияют на то, как модель читает файлы и вносит изменения в код. |
| Контекстное окно | Объем информации, который модель может помнить и обрабатывать за один раз. | Больший контекст не обязательно означает, что модель умнее, но она лучше подходит для обработки длинных документов, крупных проектов и непрерывных многоэтапных диалогов. |
| Автоматическое сжатие / Автообобщение | Когда диалог или содержимое файла приближаются к лимиту контекста, некоторые инструменты обобщают предыдущую историю в краткую сводку и продолжают отправку модели. | Автосжатие позволяет продолжить диалог, но сводка может упустить важные детали; при поиске ошибок, изменении кода или проверке конфигурации не предполагайте, что модель помнит весь исходный текст. |
| Токен | Базовая единица тарификации модели и расчета длины текста; можно представить как небольшие фрагменты, на которые разбивается текст. | Токены расходуются как на входные данные, так и на ответ; длинные документы и долгие диалоги существенно увеличивают расходы. |
| Температура | Параметр, управляющий степенью случайности и креативности ответа. | Если вам нужны стабильность и воспроизводимость, уменьшите ее; если требуется разнообразие и креативность, значение можно повысить. |
Термины AI-провайдеров
| Термин | Простое объяснение | На что обратить внимание новичкам? |
|---|---|---|
| AI-провайдер / релей | Сервис, перенаправляющий запросы из вашего инструмента на одну или несколько платформ с моделями. | Это не сама модель; ключевое значение имеют поддерживаемые модели, стабильность, цена и история рисков. |
| Провайдер | Платформа, предоставляющая интерфейсы к ИИ, модели, биллинг и панель управления (может быть официальной или релеем). | Адреса API, ключи, названия моделей и способы тарификации у разных провайдеров могут отличаться. |
| Официальные каналы | Сервисы, предоставляемые самими разработчиками моделей, такими как OpenAI, Anthropic, Google и др. | Стабильность и правила более понятны, однако могут существовать ограничения по оплате, регионам, ценам и квотам. |
| Зеркало / Прокси | Промежуточный уровень, перенаправляющий запрос к целевому сервису. | При встрече таких терминов обращайте особое внимание на конфиденциальность, стабильность и сохранение содержимого запросов. |
| New API / Панели вторичной разработки | Многие AI-провайдеры развертывают или дорабатывают серверную часть на основе панелей с открытым исходным кодом. | Названия пунктов меню могут звучать как Token, Channel, Grouping, Model Multiplier и отличаться от официальных платформ. |
| Канал | Маршрут в панели управления, подключающийся к определенному вышестоящему сервису моделей (upstream). | При сбое канала ключ может быть верным, но запрос все равно завершится ошибкой. |
| Группировка моделей | Назначение различных моделей или прав доступа разным группам. | Если ваш ключ не добавлен в соответствующую группу, модель будет недоступна или появится ошибка «model not found». |
| Маппинг моделей | Провайдер сопоставляет отображаемое имя с реальной моделью на стороне источника. | Отображаемое имя на странице может отличаться от настоящего имени модели; при настройке следуйте инструкциям в панели управления. |
Поля конфигурации
| Параметр | Простое объяснение | Как заполнять |
|---|---|---|
| API | Интерфейс приложения для вызова модели. Инструмент не открывает веб-чат, а отправляет вопрос провайдеру через API. | Требуется только в том случае, если инструмент явно поддерживает настройку API. |
| API Key / Key / Secret | Строка, используемая инструментом для подтверждения: «Я владелец этого аккаунта». | Скопируйте полностью из панели провайдера, не публикуйте на скриншотах и следите, чтобы не скопировались лишние пробелы. |
| Token | Название, которое многие AI-провайдеры используют в панели управления для обозначения Key. | Обозначения token, Token, API Key или secret обычно означают одно и то же: учетные данные доступа. |
| Base URL / Адрес API | Адрес интерфейса, предоставляемый провайдером для отправки запросов к модели из инструмента. | Это ссылка на API; иногда она выглядит как адрес главной страницы сайта, а иногда должна заканчиваться на /v1 — ориентируйтесь на пример в панели провайдера. |
| Endpoint | Другое название адреса интерфейса. | Если в документации провайдера указан Endpoint, обычно нужно искать API Address или Base URL. |
| Provider | Пункт настройки провайдера в инструменте. | Означает выбор: «какого провайдера, какой Key и какой адрес API я хочу использовать». |
| Model / Model ID / Название модели | Указывает провайдеру, API какой именно модели следует вызвать. | Копируйте в точности из списка моделей в панели управления; добавляйте вручную только в случае, если автозагрузка списка не сработала. |
| Совместимость с OpenAI | Формат API провайдера повторяет OpenAI API, поэтому во многих инструментах его можно просто настроить как OpenAI Provider. | Совместимость с OpenAI не гарантирует поддержку всех интерфейсов Claude, Gemini, а также генерации изображений и видео. |
Тарификация и лимиты
| Термин | Простое объяснение | На что обратить внимание новичкам? |
|---|---|---|
| Баланс | Сумма или баллы, доступные для использования в аккаунте провайдера. | Недостаточный баланс приводит к ошибкам запросов, что не всегда связано с ошибкой конфигурации. |
| Множитель цены (Multiplier) | Коэффициент тарификации, часто используемый AI-провайдерами, показывающий, во сколько раз изменяется стоимость вызова конкретной модели. | Чем мощнее модель, больше контекст и сложнее задачи с изображениями или видео, тем выше может быть множитель. |
| Цена за ввод (Input price) | Стоимость, рассчитываемая на основе объема данных, отправляемых модели. | Длинные документы, объемный код и большая история переписки увеличивают затраты на ввод. |
| Цена за вывод (Output price) | Стоимость, рассчитываемая на основе объема ответа, сгенерированного моделью. | Если модель генерирует очень длинный ответ, стоимость вывода пропорционально возрастает. |
| Параллелизм (Concurrency) | Количество запросов, которые могут обрабатываться одновременно. | При слишком низком лимите параллелизма одновременный запуск нескольких инструментов или совместное использование приведут к очередям или ошибкам. |
| RPM / TPM | Ограничения на количество запросов в минуту (RPM) и токенов в минуту (TPM). | Сообщение о превышении rate limit обычно означает слишком частые запросы или слишком большой объем данных. |
| Длина контекста | Максимальный объем данных, который может содержать один запрос. | При превышении лимита инструмент может обрезать данные, выдать ошибку либо автоматически сжать или обобщить историю диалога перед продолжением. |
| Кэш (Cache) | Повторное использование уже обработанного содержимого провайдерами или моделями для снижения затрат и ускорения работы. | Кэширование не всегда срабатывает автоматически и не обязательно является полностью бесплатным; все зависит от правил провайдера и модели. |
| Стоимость кэша | Общее обозначение затрат, связанных с кэшированием; некоторые системы разделяют их на создание, попадание в кэш, чтение и т. д. | Увидев стоимость кэша, сначала уточните, относится ли она к записи, чтению или к объединенному показателю в панели. |
| Цена создания / записи в кэш | Стоимость, взимаемая при первой записи фрагмента многократно используемого контента в кэш. | При первом использовании длинных системных промптов, больших документов или фиксированного контекста может взиматься этот сбор. |
| Цена попадания / чтения из кэша | Стоимость при повторном использовании уже закэшированного контента в последующих запросах. | Обычно она ниже стандартной цены за ввод, но все же может списываться; не стоит считать, что попадание в кэш всегда бесплатно. |
| Попадание в кэш (Cache hit) | Часть содержимого в запросе распознана провайдером как совпадающая с предыдущей, и данные взяты напрямую из кэша. | Кэш срабатывает только при выполнении условий провайдера: совпадение префикса, достаточная длина контента и использование в пределах срока действия. |
| Срок действия кэша | Период времени, в течение которого закэшированные данные доступны для повторного использования. | Повторный запрос после истечения срока может тарифицироваться как обычный ввод или снова потребовать оплаты за создание кэша. |
Распространенные ошибки
| Ошибка | Обычное значение | Что проверить в первую очередь |
|---|---|---|
| 401 / Unauthorized | Ошибка аутентификации. | Убедитесь, что ключ введен полностью, не истек и не содержит случайно скопированных пробелов. |
| 403 / Forbidden | У аккаунта или ключа нет прав доступа. | Проверьте права на модель, права группы, региональные ограничения и состояние баланса. |
| 404 / model not found | Модель не существует или текущий ключ не может ее использовать. | Проверьте, скопировано ли имя модели из панели управления и добавлен ли ключ в соответствующую группу моделей. |
| 429 / rate limit | Слишком частые запросы или исчерпан лимит квоты. | Проверьте параллелизм, RPM, TPM, ограничения провайдера и повторите попытку позже. |
| timeout / таймаут | Запрос не вернул ответ вовремя. | Проверьте Base URL, качество сети, статус провайдера и наличие очередей к модели. |
| invalid api key | Неверный формат ключа или отсутствуют права. | Скопируйте ключ заново, убедившись, что вы не перепутали примечание/имя ключа с самим ключом. |
| invalid base url | Неверный адрес интерфейса. | Убедитесь, что указан адрес API, а не адрес панели управления; требуется ли суффикс /v1 — проверьте по документации провайдера. |
| insufficient quota | Недостаточно средств или баланса. | Проверьте баланс аккаунта, множитель модели и поступил ли платеж на счет. |
Если вы не понимаете сообщение об ошибке, не меняйте сразу несколько параметров. Проверяйте по порядку: Key, Base URL, название модели, баланс, права доступа к модели, статус провайдера.