Hugging Face's logo

Hub documentation

Локальные агенты с llama.cpp

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Локальные агенты с llama.cpp

Вы можете запускать агента для написания кода полностью на собственном оборудовании. Несколько открытых агентов могут подключаться к локальному серверу llama.cpp, чтобы обеспечить опыт, аналогичный Claude Code или Codex, — при этом всё работает на вашем компьютере.

Начало работы

1. Настройте локальное оборудование

Настройте своё локальное оборудование, чтобы система могла показывать, какие модели совместимы с вашей конфигурацией.

Перейдите на huggingface.co/settings/hardware и настройте профиль вашего локального оборудования. Затем выберите llama.cpp в разделе Local Apps settings, так как именно этот движок вы будете использовать.

2. Найдите совместимую модель

Найдите модели, совместимые с Llama.cpp.

3. Запустите сервер llama.cpp

На странице модели нажмите кнопку «Использовать эту модель» и выберите llama.cpp. Там будут показаны точные команды для вашей конфигурации. Первый шаг — запустить сервер llama.cpp, например

llama-server -hf ggml-org/gemma-4-26b-a4b-it-GGUF:Q4_K_M

Эта команда загружает модель и запускает на вашем компьютере сервер API, совместимый с OpenAI. Инструкции по установке см. в руководстве llama.cpp.

4. Подключите вашего агента

Выберите одного из агентов ниже и следуйте инструкциям по настройке.

Pi

Pi — это агент, стоящий за OpenClaw. Теперь он напрямую интегрирован в Hugging Face, что даёт вам доступ к тысячам совместимых моделей.

Установка Pi:

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

Затем добавьте вашу локальную модель в файл конфигурации Pi по пути ~/.pi/agent/models.json:

{
  "providers": {
    "llama-cpp": {
      "baseUrl": "http://localhost:8080/v1",
      "api": "openai-completions",
      "apiKey": "none",
      "models": [
        {
          "id": "ggml-org-gemma-4-26b-4b-gguf"
        }
      ]
    }
  }
}

Запустите Pi в каталоге вашего проекта:

pi

Pi подключается к вашему локальному серверу llama.cpp и предоставляет интерактивную сессию агента.

Demo

Включение поддержки зрения

Для моделей с поддержкой изображений добавьте "input": ["text", "image"] в запись модели в ~/.pi/agent/models.json:

"models": [
  {
    "id": "unsloth/Qwen3.6-35B-A3B-GGUF:Q4_K_XL",
    "input": ["text", "image"]
  }
]

Просмотрите модели «зрение-язык», совместимые с Pi.

OpenClaw

OpenClaw работает локально с llama.cpp. Вы можете задать свою модель с помощью встроенной команды:

openclaw onboard --non-interactive \
  --auth-choice custom-api-key \
  --custom-base-url "http://127.0.0.1:8080/v1" \
  --custom-model-id "ggml-org-gemma-4-26b-a4b-gguf" \
  --custom-api-key "llama.cpp" \
  --secret-input-mode plaintext \
  --custom-compatibility openai \
  --accept-risk

Вы также можете запустить openclaw onboard в интерактивном режиме, выбрать custom-compatibility с openai и передать ту же конфигурацию.

Локальный поиск в памяти для OpenClaw

Вы можете использовать локальные модели эмбеддингов с Llama.cpp для поиска в памяти вашего агента. Для этого убедитесь, что у вас установлен node-llama-cpp.

npm i node-llama-cpp

Ниже приведён пример фрагмента кода для запуска квантованной модели EmbeddingGemma-300M локально для поиска по памяти. OpenClaw автоматически скачивает и запускает модель с помощью приведённой ниже команды.

openclaw config set agents.defaults.memorySearch.provider local
openclaw config set agents.defaults.memorySearch.local.modelPath "hf:ggml-org/embeddinggemma-300m-qat-q8_0-GGUF/embeddinggemma-300m-qat-Q8_0.gguf"

Перезапустите шлюз и выполните проверку.

openclaw gateway restart
openclaw memory status
# Memory Search (main)
# Provider: local (requested: local)
# Model: hf:ggml-org/embeddinggemma-300m-qat-q8_0-GGUF/embeddinggemma-300m-qat-Q8_0.gguf

Hermes Agent

Hermes Agent работает локально с llama.cpp. Определите конфигурацию по умолчанию следующим образом:

model:
  provider: custom
  default: ggml-org/gemma-4-26B-A4B-it-GGUF:Q4_K_M
  base_url: http://127.0.0.1:8080/v1
  api_key: llama.cpp

custom_providers:
  - name: Local (127.0.0.1:8080)
    base_url: http://127.0.0.1:8080/v1
    api_key: llama.cpp
    model: ggml-org/gemma-4-26B-A4B-it-GGUF:Q4_K_M

### Локальный поиск в памяти для агента Hermes

Hermes Agent использует модели семантического поиска через эндпоинты. Когда вы развернете выбранную модель эмбеддингов на эндпоинте 8080 с помощью llama.cpp или другого движка инференса, добавьте следующее в ~/.hermes/config.yaml.

auxiliary:
  session_search:
    base_url: "http://127.0.0.1:8080/v1"
    api_key: "no-key-required"
    model: "local-llama" # your model alias
    timeout: 90
    max_concurrency: 1

Проверьте, что это работает: none - built-in only означает, что другие плагины памяти не используются. Вывод ниже показывает, что локальное обслуживание активно.

$ hermes memory status
# Memory status
#────────────────────────────────────────
#  Built-in:  always active
#  Provider:  (none — built-in only)

OpenCode

OpenCode работает локально с llama.cpp. Определите ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "llama.cpp": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "llama-server (local)",
      "options": {
        "baseURL": "http://127.0.0.1:8080/v1"
      },
      "models": {
        "gemma-4-26b-4b-it": {
          "name": "Gemma 4 (local)",
          "limit": {
            "context": 128000,
            "output": 8192
          }
        }
      }
    }
  }
}

Как это работает

Настройка включает два компонента, работающих локально:

  1. llama.cpp server — предоставляет модель в виде OpenAI-совместимого API на localhost.
  2. Ваш агент — процесс агента, который отправляет промпты локальному серверу, рассуждает о задачах и выполняет действия.
┌─────────┐     API calls     ┌──────────────────┐
│  Agent  │ ───────────────▶  │  llama.cpp server │
│         │ ◀───────────────  │  (local model)    │
└─────────┘    responses      └──────────────────┘
     │
     ▼
  Your files,
  terminal, etc.

Альтернатива: llama-agent

llama-agent использует иной подход — он встраивает цикл агента непосредственно в llama.cpp в виде единого бинарного файла без внешних зависимостей. Без Node.js, без Python, достаточно скомпилировать и запустить:

git clone https://github.com/gary149/llama-agent.git
cd llama-agent

# Build
cmake -B build
cmake --build build --target llama-agent

# Run (downloads the model automatically)
./build/bin/llama-agent -hf ggml-org/gemma-4-26b-a4b-it-GGUF:Q4_K_M

Поскольку вызовы инструментов выполняются в рамках процесса, а не по HTTP, между моделью и агентом нет сетевых накладных расходов. Также поддерживаются субагенты, MCP-серверы и режим HTTP API-сервера.

Дальнейшие шаги

Update on GitHub

←Создание агентов с помощью HF SDK Библиотеки агентов→