Почему все вдруг заговорили про Messages API в llama.cpp?

Представьте: у вас есть любимая модель в llama.cpp, но весь ваш код заточен под Anthropic API. Раньше приходилось переписывать половину проекта или мириться с костылями. Теперь можно просто обновить llama.cpp и получить совместимый эндпоинт.

Начиная с версии 2358, llama.cpp поддерживает протокол Anthropic Messages API. Это не просто "еще один эндпоинт" — это билет в мир совместимости с сотнями инструментов, заточенных под Claude.

Что ломается при переходе на Messages API

Старый добрый /completion эндпоинт работал по принципу "вопрос-ответ". Messages API требует структурированных сообщений с ролями (user, assistant, system). Если ваш код шлет голый текст без ролей — он сломается. Придется перепаковывать запросы.

Важно: Messages API не совместим на 100% с оригинальным Anthropic API. Некоторые продвинутые функции вроде tool use могут работать иначе или не работать вовсе. Это эмуляция, а не клон.

1Собираем llama.cpp с поддержкой Messages API

Если у вас старая сборка — выбросьте ее. Серьезно. Собираем с нуля:

git clone https://github.com/ggerganov/llama.cpp
cd llama.cpp
mkdir build && cd build
cmake .. -DLLAMA_CURL=ON
make -j$(nproc)

Ключевой флаг здесь - DLLAMA_CURL=ON. Без него сервер не сможет правильно обрабатывать HTTP-запросы для Messages API. Если пропустите этот шаг — получите кучу странных ошибок при запуске.

💡

Если у вас проблемы со сборкой, гляньте статью "Сборка llama.cpp не для всех". Там разобраны все подводные камни для разных платформ.

2Запускаем сервер с правильными параметрами

Вот как НЕ надо делать:

./server -m model.gguf --port 8080  # Так Messages API не заработает

А вот правильный способ:

./server -m model.gguf --port 8080 --api-key "sk-ant-" --api-messages

Флаг --api-messages включает поддержку протокола Anthropic. Без него сервер будет отвечать только через старые эндпоинты. Параметр --api-key можно задать любым — сервер все равно его проигнорирует, но некоторые клиенты требуют наличие ключа в заголовках.

3Проверяем, что все работает

Отправляем тестовый запрос через curl:

curl http://localhost:8080/v1/messages \
  -H "Content-Type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: sk-ant-" \
  -d '{
    "model": "claude-3-haiku-20240307",
    "max_tokens": 100,
    "messages": [
      {"role": "user", "content": "Привет, как дела?"}
    ]
  }'

Обратите внимание на заголовок anthropic-version — он обязателен. Без него сервер вернет 400 ошибку. Поле model можно указать любое — llama.cpp его игнорирует и использует загруженную модель.

Как интегрировать с существующими проектами

Допустим, у вас есть скрипт, который раньше ходил в облачный Anthropic API. Меняем всего две строки:

// Было:
const client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });

// Стало:
const client = new Anthropic({
  apiKey: "sk-ant-",  // любая строка
  baseURL: "http://localhost:8080/v1"  // ваш локальный сервер
});

Вот и вся магия. Теперь все вызовы client.messages.create() пойдут на ваш локальный сервер. Если вы работаете с агентами, эта интеграция может сэкономить кучу денег — как в случае с GLM-4.7 и Claude-совместимым API.

Где собака зарыта: тонкости и грабли

Проблема	Решение
Сервер возвращает "Not Found" на /v1/messages	Запустили без флага --api-messages
Ошибка 400 "Missing anthropic-version header"	Добавьте заголовок anthropic-version: 2023-06-01
Медленные ответы	Используйте флаги --ctx-size и --batch-size для оптимизации
Не работает streaming	Streaming в Messages API пока сыроват, используйте обычные запросы

А что с производительностью?

Messages API добавляет небольшую прослойку для преобразования форматов. На практике это 5-15ms дополнительной задержки на запрос. Если каждая миллисекунда на счету — возможно, стоит остаться на старом /completion эндпоинте. Но для большинства проектов разница незаметна.

Для серьезных нагрузок рассмотрите llama.cpp RPC-server — он умеет распределять запросы между несколькими нодами.

Почему это меняет правила игры

Раньше для тестирования кода под Anthropic API нужно было либо платить за облачные запросы, либо городить сложные адаптеры. Теперь можно взять любую GGUF-модель, запустить локально и отлаживать сколько угодно. Особенно круто для:

Тестирования агентских архитектур
Разработки инструментов с tool calling
Обучения моделей с обратной связью
Интеграции в игры вроде S.T.A.L.K.E.R. Anomaly

Если вы управляете кучей агентов, как Джефф Эмануэль с его 20+ ИИ-агентами, эта фича сэкономит вам кучу нервов и денег.

Можно ли использовать это в продакшене?

Технически — да. Практически — с оглядкой. Messages API в llama.cpp еще молодая фича. Для критически важных систем лучше подождать пару релизов или иметь fallback на облачный API.

Но для внутренних инструментов, прототипирования и тестирования — это золото. Особенно если комбинировать с семантическим роутингом для выбора моделей на лету.

💡

Если вы разрабатываете мобильное приложение, посмотрите туториал по llama.cpp на мобилках. Messages API отлично ложится на такую архитектуру.

Что делать, если все равно не работает

Проверьте по чеклисту:

Собрали с -DLLAMA_CURL=ON?
Запустили с --api-messages?
Добавили заголовок anthropic-version в запросе?
Модель загрузилась без ошибок? (смотрите логи сервера)
Порт не занят другим процессом?

Если все это проверили и проблема осталась — идите в Issues llama.cpp на GitHub. Скорее всего, вы не первый.

Что дальше?

Разработчики llama.cpp обещают добавить полную поддержку tool calling и streaming в Messages API. Когда это случится — локальные модели смогут полностью заменять Claude в большинстве сценариев.

Пока же советую поэкспериментировать с разными моделями. Некоторые GGUF-модели отлично работают через Messages API, другие требуют тонкой настройки параметров. И помните: даже если что-то не работает с первой попытки, это не значит, что не заработает никогда. Просто нужно найти правильные ключи — в прямом и переносном смысле.

Anthropic Messages API в llama.cpp: Запускаем локальный Claude без головной боли