Самая частая причина неудачного подключения Llama API — не недостаток возможностей модели, а три несогласованных параметра: Base URL, способ аутентификации и имя модели. После закрытия публичной предварительной версии Llama API от Meta в июле 2026 года входы в Llama распределились между облаками, платформами инференса, собственными развёртываниями и OpenAI-совместимыми шлюзами. Форма запросов у них близкая, но детали различаются.

Ниже шаги идут по порядку: определить вход, собрать URL, найти имя модели, отправить первый запрос, обработать потоковый режим и вызов инструментов, разобрать ошибки, мигрировать со старого интерфейса. Примеры используют OpenAI-совместимый интерфейс; список моделей и цены — на странице цены на модели.

Примечание: Meta и Llama — товарные знаки Meta Platforms, Inc.; Groq, OpenRouter, AWS, Google Cloud и другие названия — товарные знаки соответствующих правообладателей. Статья носит технический характер и не подразумевает аффилированности, агентских или партнёрских отношений с указанными платформами.

1. Перед подключением подтвердите три вещи

Независимо от поставщика, сначала зафиксируйте в конфигурации три пункта:

  • Base URL: протокол, домен и префикс пути, обычно заканчивается на /v1.
  • Аутентификация: Bearer Token, подпись IAM или сервисный аккаунт — их нельзя смешивать.
  • Имя модели: внутренний ID модели платформы, а не рекламное название продукта.

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

2. Base URL: SDK сам добавляет путь

В OpenAI SDK base_url указывается только до префикса версии, а /chat/completions SDK добавляет сам. Поэтому:

  • Правильно: https://api.groq.com/openai/v1
  • Неправильно: https://api.groq.com/openai/v1/chat/completions (получится двойной путь)
  • Неправильно: https://api.groq.com/openai (нет /v1, большинство платформ вернёт 404)

Префиксы путей различаются: у Groq — /openai/v1, у OpenRouter — /api/v1, у собственного vLLM по умолчанию /v1. У облаков адреса сложнее: OpenAI-совместимый адрес Vertex AI включает проект, регион и путь endpoint, копировать только домен нельзя. Надёжнее всего скопировать полный Base URL из раздела «пример запроса» в консоли и проверить минимальным запросом.

3. Имя модели: у каждой платформы своё

Одна и та же модель Llama на разных платформах может называться совершенно по-разному:

Вход Пример Base URL Пример имени модели Примечание
Groq https://api.groq.com/openai/v1 llama-3.3-70b-versatile Ориентируйтесь на текущий список моделей
OpenRouter https://openrouter.ai/api/v1 meta-llama/llama-3.3-70b-instruct Агрегирующая маршрутизация, важен префикс
Собственный vLLM http://localhost:8000/v1 Задаётся через --served-model-name Без параметра используется путь весов
AWS Bedrock https://bedrock-runtime.us-east-1.amazonaws.com us.meta.llama4-scout-17b-instruct-v1:0 Invoke/Converse, не OpenAI-совместимый
Совместимый шлюз https://ai.zhongshangqihang.com/v1 По списку моделей в консоли Один ключ, несколько моделей

В имени модели важны регистр, номер версии, квантование и вариант рассуждения. Llama-3.3-70B-Instruct, llama-3.3-70b-versatile и meta-llama/llama-3.3-70b-instruct могут означать не одно и то же развёртывание. Не берите ID из блога и не выводите его в продакшен — сначала подтвердите в консоли или через GET /models.

Учитывайте жизненный цикл. Google Cloud объявила о выводе llama-3.3-70b-instruct-maas 21 октября 2026 года; AWS Llama 4 Scout находится в стадии Legacy, объявленная дата прекращения поддержки — 30 марта 2027 года. Храните ID модели в конфигурации, а не разбрасывайте по бизнес-коду, тогда при миграции не придётся искать по всему репозиторию.

4. Первый вызов: сначала curl

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

export LLAMA_API_KEY="ваш-ключ"

curl -s https://api.groq.com/openai/v1/chat/completions \
  -H "Authorization: Bearer $LLAMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama-3.3-70b-versatile",
    "messages": [{"role": "user", "content": "Одной фразой объясни, что такое OpenAI-совместимый интерфейс"}],
    "max_tokens": 128
  }'

В ответном JSON смотрите четыре поля: есть ли содержимое в choices[0].message.content, равен ли finish_reason значению stop или length, посчитаны ли входные и выходные токены в usage, совпадает ли model с запрошенным. Если платформа вернула другое model, возможно, сработала маршрутизация или подмена псевдонима — это повлияет на счёт и оценку качества.

5. Python SDK: различия — в конфигурацию

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["LLAMA_API_KEY"],
    base_url=os.environ["LLAMA_BASE_URL"],
)

resp = client.chat.completions.create(
    model=os.environ["LLAMA_MODEL"],
    messages=[{"role": "user", "content": "Одной фразой объясни, что такое OpenAI-совместимый интерфейс"}],
    max_tokens=128,
    timeout=60,
)
print(resp.choices[0].message.content)

Три инженерные привычки уменьшают число проблем: явно задавать тайм-аут; ограничивать число повторов и повторять только повторяемые ошибки; держать base_url, model и max_tokens в конфигурации. Не используйте бесконечные повторы и не повторяйте ошибки параметров вроде 400.

Учитывайте различия имён параметров. Одни платформы принимают только max_tokens, другие перешли на max_completion_tokens; где-то есть ограничения на диапазон temperature, число stop или роли сообщений. Ориентируйтесь на документацию целевой платформы и не предполагайте, что параметры OpenAI передаются без изменений.

6. Потоковый вывод: обрабатывайте по частям

После stream=True сервер обычно отвечает через Server-Sent Events: каждая строка начинается с data:, последняя — data: [DONE]. Клиент должен читать choices[0].delta.content по частям и обрабатывать пустые блоки, heartbeat и обрывы соединения. Три частые проблемы:

  • delta.content считают всегда присутствующим и падают на None.
  • Прокси или шлюз буферизует ответ: внешне «потока нет», хотя данные приходят целиком.
  • После отключения клиента сервер продолжает генерацию, расходуя квоту; нужны отмена и тайм-аут на уровне бизнес-логики.

Если используется шлюз, сначала выясните, передаёт ли он SSE без изменений и не переписывает ли события ошибок. Совместимость потокового интерфейса ломается чаще, чем непоточного, поэтому перед запуском проведите отдельный тест.

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

Параметр tools в стиле OpenAI поддерживается не всеми хостингами Llama полностью. Перед вызовом проверьте три вещи: модель поддерживает инструменты, платформа передаёт tools и tool_choice, в ответе может появиться finish_reason=tool_calls.

Аргументы инструмента модель обычно возвращает строкой JSON, а не объектом. Бэкенд должен сначала разобрать JSON и проверить схему, затем выполнять реальную функцию; нельзя подставлять вывод модели напрямую в SQL, Shell или внутренние интерфейсы. У выполнения инструмента должны быть тайм-аут, идемпотентность и границы прав; результат ошибки нужно вернуть модели, чтобы она решила, повторять или менять аргументы. Параллельные вызовы, строгая схема и потоковый вызов инструментов сильнее всего различаются между платформами — проверяйте каждый пункт.

8. Частые ошибки: сначала код, потом тело ответа

  • 401: ключ отсутствует, имеет неверный формат, относится к другой платформе или отозван.
  • 404: в Base URL лишний или недостающий /v1, либо имени модели не существует.
  • 400: параметр не поддерживается, например смешаны max_tokens и max_completion_tokens или недопустима роль сообщения.
  • 403: ключ действителен, но нет прав на модель, проект или регион.
  • 429: сработало ограничение скорости или параллелизма. Читайте Retry-After, используйте экспоненциальную выдержку со случайным разбросом, не повторяйте с фиксированным интервалом.
  • 5xx: сбой или тайм-аут вышестоящего сервиса. Повторяйте только идемпотентные запросы и записывайте ID запроса.
  • 200 с пустым содержимым: возможны finish_reason=length, фильтрация контента или ошибка разбора потока.

Порядок диагностики — снаружи внутрь: сначала curl в обход бизнес-кода, затем официальный SDK, и только потом подозревайте промпт. Записывайте в журнал ID запроса, код состояния, имя модели и Base URL, иначе межплатформенные проблемы трудно воспроизвести.

9. Миграция со старого Llama API: по порядку

  1. Найдите в коде и конфигурации api.llama.com, /compat/v1 и старые имена моделей, составьте список всех точек вызова.
  2. Создайте ключ на новой платформе, подтвердите Base URL и имя модели, прогоните минимальный запрос через curl.
  3. Составьте таблицу соответствия моделей: новый ID, лимит контекста, лимит выхода, поддержка потока и инструментов.
  4. Замените Base URL и способ аутентификации, сохранив тайм-ауты, повторы и поля журналов; не меняйте попутно бизнес-логику.
  5. Отдельно протестируйте потоковый вывод и вызов инструментов — здесь чаще всего возникает «непоточный работает, потоковый нет».
  6. Проведите малую оценку на реальных запросах, затем переведите 5–10% трафика и следите за ошибками и p95.
  7. Сохраните старый канал или резервного хостинг-провайдера и выполните учение по откату, прежде чем переключать всё.

Признак завершённой миграции — не «модель возвращает текст», а приемлемые качество, задержка, лимиты и счёт, а также возможность найти конкретный запрос при проблеме.

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

Base URL Llama API фиксирован?

Нет. Старый вход Meta Llama API закрыт, теперь Base URL определяется выбранной платформой. У Groq, OpenRouter, собственного vLLM и совместимого шлюза разные префиксы путей; ориентируйтесь на пример из консоли.

Почему одна модель Llama называется на разных платформах по-разному?

Платформы добавляют свои префиксы, версии, квантование и метки развёртывания. Имя модели — внутренний ID платформы, а не общее название семейства. При смене платформы имя обычно приходится менять.

Можно ли вызывать Llama напрямую через OpenAI SDK?

Да, если целевая платформа предоставляет OpenAI-совместимый /chat/completions. Укажите её адрес в base_url, её ключ в api_key и её ID модели в model — минимальный вызов готов. Вызов инструментов, поток и структуру ошибок всё равно нужно проверить по отдельности.

Нужно ли менять SDK для потокового вывода?

Большинство OpenAI SDK поддерживают stream=True, менять SDK не нужно. Но проверьте, что платформа возвращает стандартный SSE, что маркер завершения — [DONE] и что шлюз не буферизует ответ.

Что проверить первым при сбое вызова инструментов?

Сначала убедитесь, что модель и платформа заявляют поддержку инструментов, затем проверьте валидность JSON Schema в tools и принимает ли платформа tool_choice, и только потом смотрите finish_reason и разбираемость JSON аргументов. Сужайте слой за слоем, не начинайте с промпта.

Что дальше

Выберите вход, прогоните curl с Base URL и именем модели из консоли, затем подключайте Python SDK; поток и вызов инструментов принимайте отдельно. Если нужен единый вход, журналы и переключение моделей, начните с регистрации в ZSQH AI Gateway; список моделей и тарификация — на странице цены на модели.

Связанные материалы: