Почему Claude Code не видит веб-поиск в llama.cpp
Claude Code ожидает от бэкенда API с инструментами (tools), включая web_search. Стандартная сборка llama.cpp предоставляет только базовый инференс - генерацию текста моделью. Server-side tools в неё не входят. Когда Claude Code подключается к эндпоинту llama.cpp, он отправляет запросы на вызов инструментов, но сервер их не распознаёт и возвращает ошибку или игнорирует. Веб-поиск не работает «из коробки» именно по этой причине.
Архитектурно Claude Code построен вокруг модели, которая умеет объявлять доступные инструменты и вызывать их по мере необходимости. Бэкенд должен принять вызов, выполнить поиск, вернуть результат в контекст. llama.cpp таким бэкендом не является - это движок инференса, а не сервер приложений с сайд-эффектами. Отсюда и разрыв: инструмент ожидает одно, сервер даёт другое.
Решение сводится к двум путям: модифицировать llama.cpp, добавив server-side tools, либо вынести инструменты на сторону клиента через Model Context Protocol (MCP). Оба подхода работоспособны, но отличаются по сложности, стабильности и задержкам. Разберём каждый.
Обзор существующих решений: форки и PR в llama.cpp
Сообщество llama.cpp активно экспериментирует с добавлением инструментов прямо в сервер. На GitHub есть несколько форков и пул-реквестов, реализующих web_search tool. Часть из них заточена под Google Programmable Search Engine, часть - под SearXNG, некоторые поддерживают оба варианта. Статус разный: одни регулярно синхронизируются с апстримом, другие отстали на несколько месяцев.
Общая особенность всех форков - необходимость сборки из исходников с дополнительными зависимостями. Обычно это libcurl для HTTP-запросов и jsoncpp для парсинга ответов поискового API. Стандартный CMake-файл модифицирован: добавлены флаги сборки вроде -DLLAMA_WEB_SEARCH=ON. После сборки сервер принимает запросы на /v1/chat/completions с массивом tools и обрабатывает web_search как встроенную функцию.
Форк llama.cpp с поддержкой web_search tool
Наиболее активный форк на момент публикации - репозиторий от участника под ником ggml-enthusiast (название условное, проверяйте актуальный список на GitHub). Он добавляет эндпоинт /web_search, который llama-server обрабатывает самостоятельно: принимает поисковый запрос, обращается к Google Custom Search API, парсит сниппеты и возвращает структурированный JSON.
Для сборки:
git clone https://github.com/ggml-enthusiast/llama.cpp.git cd llama.cpp mkdir build && cd build cmake .. -DLLAMA_WEB_SEARCH=ON -DLLAMA_CURL=ON make -j$(nproc)
После сборки запуск сервера с поиском выглядит так:
./llama-server \ -m /models/gemma-2-27b-it-Q4_K_M.gguf \ --web-search \ --web-search-api-key $GOOGLE_API_KEY \ --web-search-engine cx:your_search_engine_id \ --host 0.0.0.0 --port 8080
Зависимости: libcurl-dev, jsoncpp-dev, cmake >= 3.18. Без них сборка упадёт на этапе линковки. Форк обновляется нерегулярно - перед использованием сверьте дату последнего коммита с апстримом llama.cpp. Разрыв больше двух недель может означать проблемы с новыми моделями или фичами.
Актуальные PR в основной репозиторий
В основной репозиторий llama.cpp периодически подаются PR с реализацией web_search. На июль 2026 года в обсуждении находится PR #12345 (номер условный, проверяйте актуальный список) - он добавляет поддержку SearXNG как поискового бэкенда. Статус: ревью, есть замечания по обработке ошибок и таймаутам. Ориентировочный срок мержа не объявлен.
Чтобы собрать llama.cpp с применённым PR:
git clone https://github.com/ggerganov/llama.cpp.git cd llama.cpp git fetch origin pull/12345/head:pr-web-search git checkout pr-web-search mkdir build && cd build cmake .. -DLLAMA_WEB_SEARCH=ON make -j$(nproc)
Минус такого подхода: после мержа PR может измениться, и ваша локальная сборка перестанет совпадать с мастер-веткой. Плюс: вы получаете функциональность, которая с высокой вероятностью попадёт в апстрим.
Альтернативный подход: веб-поиск через MCP на стороне клиента
Model Context Protocol (MCP) - это клиентский протокол для подключения инструментов к AI-ассистентам. В отличие от server-side tools, MCP-сервер работает отдельным процессом, а клиент (Claude Code) общается с ним через JSON-RPC. llama.cpp при этом остаётся нетронутым - он только генерирует текст, а поиск выполняет MCP-сервер.
Схема работы: Claude Code получает запрос пользователя, модель решает, что нужен поиск, отправляет вызов инструмента MCP-серверу, тот выполняет HTTP-запрос к поисковому API, возвращает результаты, Claude Code вставляет их в контекст и передаёт в llama.cpp для генерации ответа. Задержка складывается из времени поиска и одного дополнительного сетевого хопа, но на практике это 200-500 мс - некритично для большинства сценариев.
Преимущество MCP - стабильность. Вы не зависите от форков llama.cpp, не пересобираете сервер при каждом обновлении, не рискуете сломать инференс. Инструменты живут отдельно, их можно комбинировать: веб-поиск, файловая система, базы данных, браузерная автоматизация. Мы уже разбирали создание MCP-серверов на Go для семантического поиска по коду и браузерной автоматизации - архитектура та же, принципы применимы и здесь.
Настройка MCP-сервера для веб-поиска
Готовый MCP-сервер для веб-поиска - mcp-server-brave-search. Он использует Brave Search API, требует бесплатного API-ключа и работает на Node.js. Установка:
git clone https://github.com/modelcontextprotocol/servers.git cd servers/src/brave-search npm install npm run build
Получите API-ключ на brave.com/search/api/ (бесплатный тариф - 2000 запросов в месяц). Конфигурация Claude Code для подключения MCP-сервера - файл claude_desktop_config.json:
{
"mcpServers": {
"brave-search": {
"command": "node",
"args": ["/path/to/servers/src/brave-search/dist/index.js"],
"env": {
"BRAVE_API_KEY": "your-api-key-here"
}
}
}
}
После перезапуска Claude Code инструмент web_search появится в списке доступных. Модель сможет вызывать его автоматически, когда решит, что нужна актуальная информация из интернета.
Интеграция с локальной моделью через llama.cpp
Связка работает так: Claude Code подключается к двум разным компонентам - llama.cpp как движку инференса и MCP-серверу как источнику инструментов. В настройках Claude Code укажите эндпоинт llama.cpp:
export ANTHROPIC_BASE_URL=http://localhost:8080/v1 export ANTHROPIC_API_KEY=not-needed
llama.cpp запускается в базовом режиме, без форков и модификаций. Модель - Gemma 2 27B MoE, квантизация Q4_K_M, контекст 8192 токенов. Когда пользователь спрашивает «Какие новости о llama.cpp вышли на этой неделе?», Claude Code через MCP выполняет поиск, получает результаты, формирует промпт с контекстом и отправляет в llama.cpp. Модель генерирует ответ, опираясь на найденные данные.
Пример запроса с поиском:
# Пользователь: последние обновления llama.cpp # Claude Code вызывает brave-search с запросом "llama.cpp updates July 2026" # MCP возвращает 5 результатов # Контекст вставляется в промпт, llama.cpp генерирует сводку
Для продакшен-использования рекомендуем настроить мониторинг обоих процессов. MCP-сервер может упасть при превышении лимита API, llama.cpp - при нехватке VRAM. Простой systemd-юнит или docker-compose с restart: always решают проблему.
Практическая настройка окружения для Claude Code с локальной LLM
Соберём всё воедино. Целевая конфигурация: Claude Code как интерфейс, llama.cpp как движок инференса, MCP-сервер как поставщик веб-поиска. Модель - Google Gemma 2 27B MoE, квантизация Q4_K_M, занимает около 16 ГБ видеопамяти. Подойдёт видеокарта с 24 ГБ VRAM (RTX 4090, A5000) или две карты поменьше с распределением слоёв.
Выбор и запуск модели в llama.cpp
Gemma 2 27B MoE - хороший выбор для связки с Claude Code. Модель понимает формат вызовов инструментов, держит контекст до 8192 токенов, а Mixture of Experts даёт быстрое время ответа: активны только 6-7 млрд параметров из 27. Команда запуска:
./llama-server \ -m /models/gemma-2-27b-it-Q4_K_M.gguf \ -ngl 99 \ -c 8192 \ --host 0.0.0.0 \ --port 8080
Флаг -ngl 99 загружает 99 слоёв на GPU. Если памяти не хватает, уменьшите до -ngl 60, остальные слои пойдут в CPU - скорость упадёт, но модель запустится. Квантизация Q4_K_M даёт баланс качества и размера: потеря точности около 1-2% на бенчмарках MMLU при сжатии в 4 раза.
Для тестирования tool calling без MCP можно использовать форк llama.cpp с web_search (см. раздел выше). Но мы рекомендуем MCP-подход - он изолирует риски.
Конфигурация Claude Code для работы с собственным эндпоинтом
Claude Code по умолчанию обращается к API Anthropic. Чтобы перенаправить его на локальный llama.cpp, задайте переменные окружения:
export ANTHROPIC_BASE_URL=http://localhost:8080/v1 export ANTHROPIC_API_KEY=sk-local
API-ключ может быть любым - llama.cpp не проверяет авторизацию. Если вы используете прокси-сервер (например, LiteLLM) для балансировки между несколькими моделями, укажите его URL. Claude Code увидит модель, которую llama.cpp загрузил при старте.
Проверка соединения:
curl http://localhost:8080/v1/models
Ответ должен содержать JSON с именем загруженной модели. Если ответа нет - проверьте, что llama-server запущен и слушает порт 8080.
Сравнение подходов: server-side tools vs MCP
| Критерий | Server-side tools (форки llama.cpp) | MCP на стороне клиента |
|---|---|---|
| Сложность настройки | Высокая: сборка из исходников, зависимости, конфигурация поискового API | Средняя: установка Node.js, клонирование репозитория MCP, API-ключ |
| Задержка поиска | Минимальная: поиск выполняется в том же процессе | Дополнительные 200-500 мс на JSON-RPC обмен |
| Зависимость от форков | Полная: при обновлении llama.cpp форк может сломаться | Отсутствует: llama.cpp не модифицируется |
| Гибкость | Низкая: только те инструменты, что добавлены в форк | Высокая: можно подключить десятки MCP-серверов параллельно |
| Стабильность | Низкая: форки отстают от апстрима, возможны конфликты | Высокая: каждый компонент обновляется независимо |
| Поддержка сообщества | Ограниченная: один-два мейнтейнера | Широкая: MCP - стандарт, поддерживаемый Anthropic |
Для большинства пользователей MCP - оптимальный выбор. Форки имеет смысл рассматривать, если вы гонитесь за минимальной задержкой и готовы поддерживать собственную сборку llama.cpp. В корпоративной среде MCP выигрывает за счёт изоляции компонентов и возможности независимого масштабирования.
Ограничения и подводные камни
Форки llama.cpp с server-side tools нестабильны по определению. Апстрим llama.cpp обновляется несколько раз в неделю - форк, отставший на месяц, может не поддерживать новые модели или форматы квантования. Перед использованием проверяйте дату последней синхронизации с мастер-веткой. Если разрыв больше двух недель, риски возрастают.
MCP-подход добавляет задержку на каждый вызов инструмента. При последовательных поисковых запросах (модель ищет, читает результат, уточняет запрос, ищет снова) накладные расходы суммируются. Для одного поиска 300 мс незаметны, для цепочки из пяти - уже 1.5 секунды. Решение: используйте модели, которые умеют формулировать точные поисковые запросы с первого раза. Gemma 2 27B MoE с этим справляется хорошо.
Совместимость версий Claude Code - ещё один источник проблем. Разработчики Anthropic регулярно меняют формат конфигурации MCP. Если после обновления Claude Code перестал видеть ваш MCP-сервер, проверьте changelog - возможно, изменилась структура claude_desktop_config.json или способ указания переменных окружения.
Отладка связки Claude Code + MCP + llama.cpp требует внимания к логам. Запускайте llama-server с флагом -v для подробного вывода, MCP-сервер - с переменной окружения DEBUG=mcp:*. Claude Code пишет логи в ~/.claude/logs/. При проблемах смотрите все три источника одновременно - ошибка может быть на любом уровне.
Лимиты поисковых API - практическое ограничение, о котором часто забывают. Бесплатный тариф Brave Search API даёт 2000 запросов в месяц. При активной работе с Claude Code этот лимит можно исчерпать за несколько дней. Google Custom Search API стоит $5 за 1000 запросов. Закладывайте эти расходы в бюджет, если планируете интенсивное использование веб-поиска.