Hub documentation

Local Agents với llama.cpp

Hub

API docs

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

Local Agents với llama.cpp

Bạn có thể chạy một coding agent hoàn toàn trên phần cứng của riêng mình. Một số agent mã nguồn mở có thể kết nối với máy chủ llama.cpp cục bộ để mang đến trải nghiệm tương tự như Claude Code hoặc Codex — nhưng mọi thứ đều chạy trên máy của bạn.

Bắt đầu

1. Cài đặt phần cứng cục bộ của bạn

Cấu hình phần cứng cục bộ của bạn để hệ thống hiển thị các mô hình tương thích với thiết lập của bạn.

Truy cập huggingface.co/settings/hardware và cấu hình hồ sơ phần cứng cục bộ của bạn. Sau đó, chọn llama.cpp trong cài đặt Ứng dụng cục bộ, vì đây sẽ là engine bạn sử dụng.

2. Tìm một Mô hình Tương thích

Tìm kiếm các mô hình tương thích với Llama.cpp.

3. Chạy llama.cpp Server

Trang mô hình, nhấp vào nút “Use this model” và chọn llama.cpp. Hệ thống sẽ hiển thị các lệnh chính xác cho cấu hình của bạn. Bước đầu tiên là khởi động một máy chủ llama.cpp, ví dụ

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

Điều này sẽ tải xuống mô hình và khởi động một máy chủ API tương thích OpenAI trên máy của bạn. Xem hướng dẫn llama.cpp để biết các bước cài đặt.

4. Kết nối Agent của bạn

Chọn một trong các tác nhân bên dưới và làm theo các hướng dẫn cài đặt.

Pi

Pi là tác nhân đứng sau OpenClaw và hiện đã được tích hợp trực tiếp vào Hugging Face, cho phép bạn truy cập hàng nghìn mô hình tương thích.

Cài đặt Pi:

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

Sau đó, thêm mô hình cục bộ của bạn vào tệp cấu hình của Pi tại ~/.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"
        }
      ]
    }
  }
}

Bắt đầu Pi trong thư mục dự án của bạn:

pi

Pi kết nối với máy chủ llama.cpp cục bộ của bạn và cung cấp cho bạn một phiên agent tương tác.

Demo

Bật hỗ trợ thị giác

Đối với các mô hình có khả năng thị giác, hãy thêm "input": ["text", "image"] vào mục mô hình trong ~/.pi/agent/models.json:

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

Duyệt các mô hình thị giác-ngôn ngữ tương thích với Pi.

OpenClaw

OpenClaw chạy cục bộ với llama.cpp. Bạn có thể đặt model của mình thông qua lệnh onboard:

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

Bạn cũng có thể chạy openclaw onboard theo cách tương tác, chọn custom-compatibility với openai, và truyền cùng một cấu hình.

Tìm kiếm bộ nhớ cục bộ cho OpenClaw

Bạn có thể chạy các mô hình nhúng cục bộ bằng Llama.cpp cho việc tìm kiếm bộ nhớ của agent. Để làm điều này, hãy đảm bảo bạn đã cài đặt node-llama-cpp.

npm i node-llama-cpp

Dưới đây là một đoạn mã mẫu để chạy EmbeddingGemma-300M đã lượng tử hóa cục bộ cho tìm kiếm bộ nhớ. OpenClaw tự động tải xuống và phục vụ mô hình bằng lệnh bên dưới.

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"

Khởi động lại gateway và xác thực.

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 chạy cục bộ với llama.cpp. Định nghĩa cấu hình mặc định như sau:

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

### Tìm kiếm bộ nhớ cục bộ cho Hermes Agent

Hermes Agent sử dụng các mô hình tìm kiếm ngữ nghĩa thông qua các endpoint. Khi bạn đã triển khai mô hình embedding mong muốn trên endpoint 8080 bằng llama.cpp hoặc bộ máy suy luận bạn chọn, hãy thêm nội dung sau vào ~/.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

Kiểm tra xem điều này có hoạt động không, none - built-in only cho thấy không có plug-in bộ nhớ nào khác được sử dụng. Đầu ra bên dưới cho thấy việc phục vụ cục bộ đang hoạt động.

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

OpenCode

OpenCode chạy cục bộ với llama.cpp. Định nghĩa một ~/.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
          }
        }
      }
    }
  }
}

Cách hoạt động

Cấu hình này có hai thành phần chạy cục bộ:

llama.cpp server — Cung cấp mô hình dưới dạng API tương thích OpenAI trên localhost.
Agent của bạn — Tiến trình agent gửi các prompt đến máy chủ cục bộ, suy luận về các tác vụ và thực thi các hành động.

┌─────────┐     API calls     ┌──────────────────┐
│  Agent  │ ───────────────▶  │  llama.cpp server │
│         │ ◀───────────────  │  (local model)    │
└─────────┘    responses      └──────────────────┘
     │
     ▼
  Your files,
  terminal, etc.

Phương án thay thế: llama-agent

llama-agent theo đuổi một cách tiếp cận khác — nó tích hợp vòng lặp agent trực tiếp vào llama.cpp dưới dạng một binary duy nhất với zero external dependencies. Không cần Node.js, không cần Python, chỉ cần compile và chạy:

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

Vì các cuộc gọi công cụ diễn ra trong tiến trình thay vì qua HTTP, nên không có chi phí mạng giữa mô hình và tác tử. Nó cũng hỗ trợ các tác tử con, các máy chủ MCP và chế độ máy chủ API HTTP.

Các bước tiếp theo

Sử dụng Mô hình AI cục bộ — Tìm hiểu thêm về việc chạy mô hình trên máy của bạn
Hướng dẫn llama.cpp — Cài đặt và sử dụng llama.cpp chi tiết
Các tác tử trên Hub — Kết nối các tác tử với hệ sinh thái Hugging Face

Update on GitHub

←Xây dựng agent với HF SDK Thư viện Agent→