llamaMan

# logo llamaMan [English](../../README.md) · [简体中文](../zh-CN/README.md) · [日本語](../ja/README.md) · [Deutsch](../de/README.md) · [Français](../fr/README.md) · [Español](../es/README.md) · [Português](../pt-BR/README.md) · [Русский](../ru/README.md) · **Български** > **Забележка:** това е превод и може да изостава от [английската версия](../../README.md), която е водеща. **Какво е.** Браузърен UI + API фронтенд за пускане на няколко инстанции на сървъра на [llama.cpp](https://github.com/ggml-org/llama.cpp), на една машина или на малък клъстер от такива. Включва Ollama-съвместимо прокси, така че се включва директно вместо Ollama в [Open WebUI](https://github.com/open-webui/open-webui). **Какво е различното.** Самият llamaMan **няма код от llama.cpp и няма зависимост от GPU** - той стартира контейнери `ghcr.io/ggml-org/llama.cpp:server-*` като съседни през Docker сокета. Обновявайте llama.cpp, без да пипате llamaMan: `docker pull` на по-нов образ `server-*`. Същата машинария за стартиране и проксиране не зависи от двигателя: инстанции на [Strata](STRATA.md) работят до llama.cpp инстанциите и се стартират, наблюдават, проксират и приспиват по същия начин. > Семантиката на флаговете на llama-server се определя от страната на llama.cpp: **[CLI справочник на сървъра](https://github.com/ggml-org/llama.cpp/blob/master/tools/server/README.md)**. ## Възможности - **Универсален GPU образ** - един и същ поток за NVIDIA, AMD (ROCm), Intel Arc, CPU; производителят се разпознава автоматично (Vulkan е по избор чрез `GPU_TYPE=vulkan`) - **Библиотека с модели + изтегляне** - изтегляне от HuggingFace с лимити на скоростта, продължаване, автоматичен повторен опит, засичане на повторно публикуване с атомарно повторно изтегляне - **Стартиране с едно щракване + пресети** - всяка настройка на llama.cpp (spec-decoding, MoE offload, KV квантуване, mmproj, вход с PDF…) е пълноценно поле в UI, с обновяване на пресетите на живо за полетата, които не изискват рестарт - **Ollama + OpenAI прокси на `:42069`** - Open WebUI се включва директно; моделите стартират автоматично при поискване и се изместват по LRU, щом се достигне `LLAMAMAN_MAX_MODELS` - **Вход с изображения и PDF** - vision модели с `--mmproj`; PDF файловете се растеризират страница по страница - **Наблюдение на инстанциите** - VRAM по GPU, CPU/RAM на контейнера, TTFT / пропускателна способност / латентност по инстанция - **Удостоверяване** - потребителски акаунти, API ключове (bearer токени), превключвател за удостоверяване по ендпойнти - **Клъстер от няколко възела** *(по избор)* - разнородни възли като един логически клъстер; обединено табло; балансиране на натоварването чрез обща опашка - 🆕 **Двигател Strata** *(по избор, NVIDIA или AMD)* - стартирайте инстанции на [Strata](https://github.com/Niko1221/Strata) до llama.cpp инстанциите - 🆕 **База знания + MCP сървър** *(по избор, бекенд MariaDB)* - съхранявайте документи като теми, търсете в тях по смисъл със собствен ембединг модел и предоставете всичко на всеки MCP клиент — изцяло локално ## Изисквания - Docker с достъп до `/var/run/docker.sock` - **Едно** от: - [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html) за NVIDIA GPU - [Съвместима с ROCm среда](https://rocm.docs.amd.com/projects/install-on-linux/en/latest/) за AMD GPU - Intel Arc с достъп до `/dev/dri` - Само CPU ## Бърз старт Първо редактирайте `docker-compose.yml`: - Задайте `HOST_MODELS_DIR` / `HOST_LOGS_DIR` на **реалните пътища на хоста**, които стоят зад монтираните томове (llamaMan ги подава на Docker демона, когато стартира съседни контейнери). - `LLAMAMAN_NODE_NAME` (`srv1` в примерния compose; **няма вградена стойност по подразбиране** - приложението отказва да стартира без нея) е **задължителна за всяка инсталация** - това е ключът за разделяне на съхраненото състояние на това внедряване. Изберете веднъж и не я сменяйте (по-късна смяна осиротява съхраненото състояние). Изтеглете llama.cpp образа за вашето GPU и стартирайте: | GPU | `LLAMA_IMAGE` | |---|---| | NVIDIA | `ghcr.io/ggml-org/llama.cpp:server-cuda` | | AMD (ROCm) | `ghcr.io/ggml-org/llama.cpp:server-rocm` | | Intel Arc | `ghcr.io/ggml-org/llama.cpp:server-sycl` | | Vulkan (резервен вариант за AMD/Intel) | `ghcr.io/ggml-org/llama.cpp:server-vulkan` (задайте `GPU_TYPE=vulkan`) | | Само CPU | `ghcr.io/ggml-org/llama.cpp:server` | ```bash docker pull # from the table above # For non-CUDA: also set LLAMA_IMAGE=... in docker-compose.yml docker compose up --build ``` За нативно наблюдение на VRAM при NVIDIA разкоментирайте и `deploy.resources.reservations` в `docker-compose.yml`. - **UI за управление**: (създайте администратор на `/setup`) - **Ollama-съвместим API**: - **Портове на инстанциите на llama-server**: 8000-8020 > **Бележка за сигурността:** монтираният `/var/run/docker.sock` дава на контейнера пълен контрол над Docker на хоста. Важат обичайните последици от достъпа до Docker сокета. Работите директно на хоста (разработка, WSL)? Вижте [Работа директно на хоста](CONFIGURATION.md#running-bare-metal). ## Вашият първи модел 1. **Сдобийте се с модел.** Или поставете `.gguf` в директорията с модели, или отворете UI, изберете HuggingFace хранилище в **Downloads** и оставете llamaMan да го изтегли. 2. **Стартирайте го.** Изберете модела в страничната лента и щракнете **Launch**. llamaMan стартира контейнер с llama-server и инстанцията се появява със значка за статус. Стойностите по подразбиране (ctx 4096, автоматични GPU слоеве) работят за повечето модели; **Save Preset** запомня настройките ви. Всяко поле за стартиране е описано в [Настройки при стартиране](LAUNCH-SETTINGS.md). 3. **Създайте API ключ.** В **API Keys** създайте ключ (`llm-xxxxxxxxxx`). По подразбиране ендпойнтите за модели изискват bearer токен. 4. **Насочете клиента си към него.** Всеки OpenAI или Ollama клиент работи с `:42069`. За Open WebUI: ```yaml open-webui: environment: - OLLAMA_BASE_URL=http://llamaman:42069 - OPENAI_API_BASE_URLS=http://llamaman:42069/v1 - OPENAI_API_KEYS=llm-your-api-key-here ``` Open WebUI изброява моделите ви чрез `/api/tags` (по основата на името на GGUF файла, освен ако не зададете **Display Name**); изборът на модел го стартира автоматично, изчаква да стане здрав и след това проксира. Задайте **Display Name** за всеки модел, за да се показва удобно име вместо суровото име на файла с квантуването. > **Уговорка за лимита:** примерният compose идва с `LLAMAMAN_MAX_MODELS=1`. При зададен лимит Ollama връзката измества LRU модела, когато е пълно, но OpenAI връзката (`OPENAI_API_BASE_URLS`) по подразбиране връща **503** - изберете един от двата пътя или вдигнете лимита. Правила: [Изместване на модели](MODELS.md#model-eviction). Ако нещо се обърка, [Отстраняване на проблеми](#отстраняване-на-проблеми) по-долу покрива честите неуспехи при първо стартиране. ## Удостоверяване Два вида идентификационни данни: - **Сесийни бисквитки** за UI (създават се през `/setup` при първо стартиране) - **API ключове** за външни клиенти (`Authorization: Bearer llm-xxxxxxxxxx`), управлявани в **API Keys** в UI Превключвателят **"Require authentication for all endpoints"** (включен по подразбиране) определя дали ендпойнтите, обслужващи модели, изискват bearer токен. Подробности: [Удостоверяване](CONFIGURATION.md#authentication-detail). ## Архитектура llamaMan е малко Python приложение, което никога не докосва директно кода на llama.cpp. То стартира всеки `llama-server` като съседен контейнер през Docker сокета, наблюдава всички тях и предоставя входна врата, съвместима с OpenAI/Ollama. ```mermaid %%{init: {'theme': 'base', 'themeVariables': {'fontFamily': 'ui-sans-serif, system-ui, sans-serif', 'fontSize': '14px', 'primaryColor': '#eef2ff', 'primaryBorderColor': '#6366f1', 'primaryTextColor': '#1e1b4b', 'lineColor': '#64748b', 'clusterBkg': '#f8fafc', 'clusterBorder': '#cbd5e1', 'edgeLabelBackground': '#f8fafc'}, 'flowchart': {'curve': 'basis', 'nodeSpacing': 40, 'rankSpacing': 60}}}%% flowchart LR client[Client
Open WebUI / any OpenAI or Ollama client] subgraph nodeA[Node A] lmA[llamaman
:5000 UI · :42069 compat] subgraph workersA[llama-server siblings on host GPUs] wA1[qwen2.5-14b] wA2[gpt-oss-20b] end end subgraph nodeB[Node B] lmB[llamaman] subgraph workersB[llama-server siblings] wB1[qwen2.5-14b] wB2[deepseek-v3] end end db[(Shared storage
presets · instance state · heartbeats)] client -->|prompt| lmA lmA -->|forward when a peer is less loaded| lmB lmA --> wA1 lmA --> wA2 lmB --> wB1 lmB --> wB2 lmA <-.-> db lmB <-.-> db classDef core fill:#4f46e5,stroke:#312e81,color:#fff classDef worker fill:#0d9488,stroke:#134e4a,color:#fff classDef ext fill:#64748b,stroke:#334155,color:#fff class lmA,lmB core class wA1,wA2,wB1,wB2 worker class client,db ext ``` Картината с един възел (по подразбиране) е само горната половина - един контейнер llamaman, N съседни `llama-server` на локалния Docker демон, без пиъри в клъстер, JSON файлове вместо общата БД. Клъстерирането е по избор и само добавя функционалност. Как работи в дълбочина - поток на заявките, разпределение според опашките, поведение при откази, проектни компромиси: [Архитектура](ARCHITECTURE.md). ## Документация | Ръководство | Съдържание | |---|---| | [Настройки при стартиране](LAUNCH-SETTINGS.md) | Всяко поле от формата за стартиране и неговия флаг на llama-server: ctx, KV кеш, GPU слоеве, MoE offload, спекулативно декодиране, пренастройки на семплирането, паралелизъм и опашки, обновяване на пресетите на живо, [вход с изображения и PDF](LAUNCH-SETTINGS.md#image--pdf-input), [Anti-Loop](LAUNCH-SETTINGS.md#anti-loop), прокси за всяка инстанция, idle timeout | | [Модели](MODELS.md) | Показвани имена, обновяване на модели, [Decision модели](MODELS.md#decision-models) (`/v1/systemone`), [изместване на модели](MODELS.md#model-eviction), настройки за изтегляне, управление на Docker образи, архив на модели, резервно копие и възстановяване, почистване | | [Конфигурация и съхранение](CONFIGURATION.md) | Инсталации директно на хоста, подробно за удостоверяването, статистика за GPU, записване на заявки, бекенди JSON срещу MariaDB, [оцеляване при срив на БД](CONFIGURATION.md#surviving-a-database-outage-local-mirror) и пълният справочник на [променливите на средата](CONFIGURATION.md#environment-variables) | | [Клъстериране](CLUSTERING.md) | Настройка с няколко възела: обща БД, heartbeat-и, балансиране на натоварването чрез обща опашка, събуждане при натоварване, грешки при маршрутизиране | | [База знания и MCP](KNOWLEDGE-BASE.md) | Теми, ембединги, MCP ендпойнт, режими на достъп | | [Strata](STRATA.md) | Вторият inference двигател: настройка, каталог, ограничения, бележки по дизайна | | [REST API](API.md) | Основни ендпойнти: инстанции, изтегляния, пресети, настройки, журнал на заявките, особености на тялото на стартирането | | [Отстраняване на проблеми](TROUBLESHOOTING.md) | Пълната таблица симптом → решение | ## Променливи на средата Тези, които ще пипнете още първия ден (пълен справочник: [Променливи на средата](CONFIGURATION.md#environment-variables)): | Променлива | По подразбиране | Описание | |---|---|---| | `LLAMAMAN_NODE_NAME` | *(задължителна)* | Уникална стабилна идентичност - изберете веднъж и не я сменяйте | | `HOST_MODELS_DIR` / `HOST_LOGS_DIR` | *(= пътищата в контейнера)* | Реалните пътища на хоста зад монтираните томове | | `LLAMA_IMAGE` | *(авто)* | Образ на llama.cpp; избира се автоматично според производителя на GPU, задайте го, за да го фиксирате. Примерният compose фиксира `server-cuda` - сменете го за GPU, различни от NVIDIA | | `LLAMAMAN_MAX_MODELS` | `0` | Максимален брой едновременни чат модели през проксито (LRU изместване; 0 = без лимит). Примерният compose задава `1` | | `DATABASE_URL` | *(не е зададена)* | Низ за връзка с MariaDB/MySQL. Не е зададена = JSON файлове | ## Отстраняване на проблеми | Симптом | Решение | |---|---| | Инстанцията е заседнала на **starting** | Проверете логовете с бутона Logs. Чести причини: OOM, грешка в пътя на модела, повреден GGUF, неизтеглен образ | | _"Docker image not found"_ | Изтеглете съответния образ: `docker pull ghcr.io/ggml-org/llama.cpp:server-cuda` (или `server-rocm` / `server-sycl` / `server`) | | _"Docker API error"_ при стартиране | Уверете се, че `/var/run/docker.sock` е монтиран (по подразбиране в `docker-compose.yml`) | | Няма GPU / CUDA грешка | Уверете се, че NVIDIA Container Toolkit е инсталиран и `docker run --gpus all` работи на хоста | | Няма статистика за GPU | NVIDIA: разкоментирайте блока `deploy.resources.reservations`. AMD/Intel: уверете се, че `/sys/class/drm:ro` е монтиран | | Моделът не се показва в OpenWebUI | Уверете се, че `OLLAMA_BASE_URL=http://llamaman:42069`. Проверете дали `/api/tags` връща модели | | OpenWebUI получава 401 | `require_auth` е включено (по подразбиране). Създайте API ключ и задайте `OPENAI_API_KEYS` в OpenWebUI | | OpenAI клиент получава 503, когато моделите са пълни | Достигнат е лимитът `LLAMAMAN_MAX_MODELS`, а OpenAI API по подразбиране не може да измества. Вдигнете лимита или включете превключвателите за изместване: [Изместване на модели](MODELS.md#model-eviction) | | Конфликт на портове | Формата сама предлага свободен порт; коригирайте при нужда | Пълна таблица: [Отстраняване на проблеми](TROUBLESHOOTING.md). ## Благодарности Тази работа не би била възможна без [ggml-org/llama.cpp](https://github.com/ggml-org/llama.cpp). ## Лиценз llamaMan е лицензиран под [Elastic License 2.0](../../LICENSE). Можете да използвате, копирате, разпространявате и променяте софтуера при следните условия: - Забранено е предоставянето на софтуера на трети страни като хостнат / управляван сервиз, при който сервизът дава на потребителите достъп до съществена част от неговите функции или функционалност. - Забранено е премахването или скриването на лицензионни, авторски или други известия на лицензодателя. ### Лицензи на трети страни - **[Font Awesome Free 7.1.0](https://fontawesome.com/)** от Fonticons, Inc. - икони (CC BY 4.0), шрифтове (SIL OFL 1.1) и код (MIT). Пълният текст на лиценза е в [`static/fontawesome-free-7.1.0-web/LICENSE.txt`](../../static/fontawesome-free-7.1.0-web/LICENSE.txt).