Документация по llama.cpp b6286

Привет!

Я недавно столкнулся с изменениями в API llama.cpp в версии b6286 (август 2025), особенно с тем, что прямой доступ к ggml/ggml.h и ggml/gguf.h больше не рекомендуется, а вся работа должна вестись через include/llama.h.

Я подготовил краткую документацию по этим изменениям и тому, как адаптировать собственные примеры (вроде qedit) под новый подход, включая правильную настройку CMakeLists.txt и избегание ошибок линковки (например, LNK1104 из-за отсутствия ggml-cuda.lib).

Документация: Работа с `llama.cpp` b6286 (август 2025)

Изменения в архитектуре и API

Изменение публичного API: Прямой доступ к внутренним библиотекам `ggml` и `gguf` через их заголовочные файлы (`ggml/ggml.h`, `ggml/gguf.h`) больше не является публичным или рекомендуемым. Функции вроде `gguf_init_from_file`, `gguf_get_n_tensors` и т.д. скрыты.

Унификация API: Всё взаимодействие с моделью, её метаданными и тензорами теперь должно происходить только через унифицированный API, предоставляемый в `include/llama.h` (и `include/llama-cpp.h` для C++).

Изменение структуры `include`: Публичные заголовки теперь находятся непосредственно в `include/`. Внутренние заголовки `ggml` перемещены в `ggml/include/`.

Создание собственного примера/приложения (например, `qedit`)

Расположение: Поместите исходный код примера (например, `qedit.cpp`) и его `CMakeLists.txt` в подкаталог `examples/<имя_примера>/` внутри корня проекта `llama.cpp`. Например: `llama.cpp/examples/qedit/`.

CMakeLists.txt:

cmake_minimum_required(VERSION 3.16)

project(<имя_примера> CXX) # Замените <имя_примера> на имя вашего проекта

set(TARGET <имя_примера>)

add_executable(${TARGET} <имя_файла>.cpp) # Замените <имя_файла>.cpp на имя вашего .cpp файла

target_compile_features(${TARGET} PRIVATE cxx_std_17)

# Указываем include-путь к llama.h

target_include_directories(${TARGET} PRIVATE

${CMAKE_SOURCE_DIR}/include # папка с llama.h

# ${CMAKE_SOURCE_DIR}/common # Если используете заголовки из common

# ${CMAKE_SOURCE_DIR}/ggml/include # Только если требуется прямой доступ к внутренним ggml (не рекомендуется)

)

# Линкуем необходимые библиотеки

target_link_libraries(${TARGET} PRIVATE

# common # Если используете утилиты из common

llama # ОСНОВНАЯ библиотека, предоставляющая API из llama.h

# ggml # Обычно не нужно явно указывать, так как llama зависит от ggml.

# Но можно оставить для ясности.

# ggml-cuda # НЕ НУЖНО. Отдельная цель ggml-cuda НЕ СОЗДАЕТСЯ.

# Функциональность CUDA интегрирована в основную библиотеку ggml.

${CMAKE_THREAD_LIBS_INIT} # Если требуется

)

Использование API: В коде вашего примера используйте только функции, объявленные в `include/llama.h`. Примеры функций:

• `llama_backend_init()`, `llama_backend_free()`: Инициализация/деинициализация бэкенда.
• `llama_model_default_params()`: Получение параметров модели по умолчанию.
• `llama_load_model_from_file()`: Загрузка модели.
• `llama_model_meta_count()`, `llama_model_meta_key_by_index()`, `llama_model_meta_val_str_by_index()`: Доступ к метаданным модели.
• `llama_model_n_embd()`, `llama_model_n_ctx_train()`, `llama_model_n_params()`: Получение информации о модели (некоторые могут требовать активного контекста).
• `llama_free_model()`: Освобождение модели.

Сборка проекта `llama.cpp`

Используйте CMake для генерации проекта сборки.

Для включения поддержки CUDA используйте опцию `-DGGML_CUDA=ON` (устаревшая `LLAMA_CUBLAS=ON` больше не поддерживается).

Пример команды для Visual Studio 2022:

cmake .. -G "Visual Studio 17 2022" -A x64 -DGGML_CUDA=ON -DLLAMA_CURL=OFF -DLLAMA_BUILD_COMMON=ON -DLLAMA_BUILD_EXAMPLES=ON

При включении `GGML_CUDA=ON` и `BUILD_SHARED_LIBS=ON` (по умолчанию для MSVC):

• Исходники CUDA (`ggml/src/ggml-cuda/*`) добавляются в сборку основной библиотеки `ggml`.
• Создаются файлы `bin/Debug|Release/ggml.dll` (содержит и CPU, и CUDA код) и `bin/Debug|Release/ggml.lib` (библиотека импорта для этой DLL).
• Основная библиотека `llama.lib` зависит от `ggml.lib`. Линковка с `llama.lib` предоставляет доступ ко всей функциональности, включая CUDA.

Решение проблем линковки (`LNK1104`)

Ошибка `LNK1104: не удается открыть файл "ggml_cuda.lib"`:

Причина: Попытка линковки с несуществующей отдельной библиотекой `ggml-cuda`.

Решение: Убедитесь, что в `target_link_libraries` вашего примера (`CMakeLists.txt`) нет `ggml-cuda`. Линкуйтесь только с `llama` (и `ggml`, если необходимо).

Ошибка `LNK1104: не удается открыть файл "ggml.lib"`:

Причина: Библиотека `ggml.lib` (библиотека импорта для `ggml.dll`) не была создана.

Решение:

1. Убедитесь, что проект `ggml` в сгенерированном решении Visual Studio настроен правильно (`Configuration Type` = `Dynamic Library (.dll)`).
2. Проверьте свойства проекта `ggml` -> `Linker` -> `Advanced` -> `Import Library`. Оно должно быть заполнено (например, `$(OutDir)ggml.lib`).
3. Пересоберите проект `ggml` в Visual Studio.
4. Убедитесь, что путь к каталогу, содержащему `ggml.lib` (обычно `build-vs2022/bin/Debug` или `Release`), указан в настройках линковщика вашего примера (`Linker` -> `General` -> `Additional Library Directories`).

Следуя этим рекомендациям, вы сможете успешно создавать и собирать приложения, использующие обновлённый API `llama.cpp` версии b6286.