Hub documentation

Local Agents với llama.cpp

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Local Agents với llama.cpp

Bạn có thể chạy một coding agent cục bộ, 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ột 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.

Cách hoạt động

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

  1. llama.cpp server — Cung cấp mô hình dưới dạng API tương thích OpenAI trên localhost.
  2. Agent của bạn — 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.

Cài đặt máy chủ llama.cpp

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

Duyệt các mô hình GGUF tương thích với Llama. Sau khi chọn, hãy tải mô hình xuống phần cứng của bạn.

Nếu bạn cần nguồn cảm hứng, ứng dụng Llama sẽ gợi ý một số mô hình được điều chỉnh phù hợp với thiết bị phần cứng của bạn (xem Bước 3).

3. Cài đặt Llama App

Bạn có thể dễ dàng cài đặt llama.cpp trên máy của mình:

  • Mac và Windows: cài đặt ứng dụng Llama, một ứng dụng desktop tối giản nằm trên khay hệ thống Sau khi cài đặt ứng dụng, hãy làm theo các bước để bắt đầu sử dụng mô hình yêu thích của bạn, được đề xuất cho hệ thống của bạn. llama app
  • Linux (or if you only want the command line): lệnh cài đặt một dòng:
    curl -LsSf https://llama.app/install.sh | sh

Xác minh cài đặt:

llama --version

4. Khởi động router

Nếu bạn đã cài đặt ứng dụng desktop, llama serve đã đang chạy. Bạn có thể kiểm tra bằng cách truy cập danh sách model trên localhost:9931.

Nếu không, hãy khởi động llama serve. Việc truyền một mô hình sẽ khởi động chế độ đơn mô hình thay vì chế độ router. Xem hướng dẫn máy chủ llama.cpp để biết cách cấu hình router.

Bạn có hai lựa chọn:

  • Tải tự động: mặc định, các mô hình được tải theo yêu cầu.
  • Tải thủ công: thêm --no-models-autoload, sau đó dùng /llama để tải các model trước khi chọn chúng.

Để tải tự động, chỉ cần chạy:

llama serve

Trong hầu hết các trường hợp, bạn không cần thêm bất kỳ cờ nào vì các giá trị mặc định thường đã hợp lý. Đối với việc sử dụng nâng cao, dưới đây là một số cờ có thể bạn quan tâm:

  • -ngl all chuyển tất cả các lớp sang GPU. Bỏ qua tham số này để sử dụng tính năng tự động chuyển lớp sang GPU.
  • -c 32768 đặt kích thước ngữ cảnh theo số token. Sử dụng -c 0 cho toàn bộ cửa sổ ngữ cảnh của mô hình, điều này có thể yêu cầu bộ nhớ lớn hơn đáng kể. Ngữ cảnh được chia sẻ giữa các slot máy chủ song song.
  • --models-dir ~/models phát hiện các tệp GGUF cục bộ từ một thư mục cục bộ tùy chỉnh.

Mặc dù lệnh ở trên thường là tất cả những gì bạn cần, nhưng dưới đây là một số cờ phổ biến để sử dụng với llama serve:

CờNó hoạt động như thế nào
-ngl alloffloads tất cả các lớp sang GPU
-c 32768đặt kích thước ngữ cảnh theo số token
--models-dir ~/modelsphát hiện các tệp GGUF cục bộ từ một thư mục cục bộ tùy chỉnh

5. 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

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

pi

Cấu hình llama.cpp:

/login llama.cpp

Chạy /llama để tải một mô hình, sau đó chạy /model để chọn mô hình đã tải cho phiên hiện tại.

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 plugins install @openclaw/llama-cpp-provider
openclaw onboard

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. Trong ~/.hermes/config.yaml, hãy thêm các nội dung sau.

custom_providers:
  - name: llama cpp (127.0.0.1:8080)
    base_url: http://127.0.0.1:8080/v1

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
          }
        }
      }
    }
  }
}

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

Update on GitHub