Hub documentation
llama.cpp ile Yerel Ajanlar
llama.cpp ile Yerel Ajanlar
Bir kodlama ajanını tamamen kendi donanımınızda, yerel olarak çalıştırabilirsiniz. Birkaç açık kaynaklı ajan, size Claude Code veya Codex'e benzer bir deneyim sunmak için yerel bir llama.cpp sunucusuna bağlanabilir — ancak her şey makinenizde çalışır.
Nasıl Çalışır
Kurulum, yerel olarak çalışan iki bileşenden oluşur:
- llama.cpp sunucusu — Modeli
localhostüzerinde OpenAI ile uyumlu bir API olarak sunar. - Ajanınız — İstemleri yerel sunucuya gönderir, görevler hakkında akıl yürütür ve eylemleri yürütür.
┌─────────┐ API calls ┌───────────────────┐
│ Agent │ ───────────────▶ │ llama.cpp server │
│ │ ◀─────────────── │ (local model) │
└─────────┘ responses └───────────────────┘
│
▼
Your files,
terminal, etc.llama.cpp sunucusunu yapılandır
1. Yerel Donanımınızı Ayarlayın
Yerel donanımınızı yapılandırın; böylece kurulumunuzla uyumlu modelleri görebilirsiniz.
huggingface.co/settings/hardware adresine gidin ve yerel donanım profilinizi yapılandırın. Ardından, kullanacağınız motor bu olacağı için Yerel Uygulamalar ayarlarınızda llama.cpp seçeneğini seçin.
2. Uygun Bir Model Bulun
Llama ile uyumlu GGUF modellerini görüntüleyin. Seçim yapıldıktan sonra modeli donanımınıza indirin.
İlham arıyorsanız, Llama uygulaması donanımınıza uyarlanmış birkaç model önerecektir (Adım 3'e bakın).
3. Llama Uygulamasını yükleyin
llama.cpp'yi makinenize kolayca kurabilirsiniz:
- Mac ve Windows: sistem tepsinizde yer alan minimalist bir masaüstü uygulaması olan Llama uygulamasını yükleyin
Uygulama yüklendikten sonra, sisteminiz için önerilen favori modelinizi kullanmaya başlamak için adımları izleyin.

- Linux (or if you only want the command line): tek satırlık kurulum komutu:
curl -LsSf https://llama.app/install.sh | sh
Kurulumu doğrulayın:
llama --version
4. Röter’ı başlatın
Masaüstü uygulamasını yüklediyseniz, llama serve zaten çalışıyor. localhost:9931 adresindeki model listesini görüntüleyerek bunu kontrol edebilirsiniz.
Değilse, llama serve komutunu başlatın. Bir model geçirildiğinde, yönlendirici modu yerine tek model modu başlatılır. Yönlendirici yapılandırması için llama.cpp sunucu kılavuzu'na bakın.
İki seçeneğiniz var:
- Otomatik yükleme: varsayılan olarak modeller talep üzerine yüklenir.
- Manuel yükleme:
--no-models-autoloadekleyin, ardından modelleri seçmeden önce yüklemek için/llamakullanın.
Otomatik yükleme için yalnızca şunu başlatın:
llama serve
Çoğu durumda, varsayılan değerlerin makul olması nedeniyle ek bayraklara ihtiyacınız yoktur. Gelişmiş kullanım için, ilginizi çekebilecek olası bayraklardan bir örnek aşağıda verilmiştir:
-ngl alltüm katmanları GPU'ya taşır. Otomatik GPU taşıma kullanmak için bu parametreyi atlayın.-c 32768, bağlam boyutunu token cinsinden belirler. Modelin tam bağlam penceresi için-c 0kullanın; bu, önemli ölçüde daha fazla bellek gerektirebilir. Bağlam, paralel sunucu yuvaları arasında paylaşılmaktadır.--models-dir ~/models, özel bir yerel dizinden yerel GGUF dosyalarını bulur.
Yukarıdaki komutun ihtiyacınız olan her şey olması gerekirken, llama serve ile kullanabileceğiniz bazı yaygın bayraklar şunlardır:
| Bayrak | Ne işe yarar |
|---|---|
-ngl all | tüm katmanları GPU'ya taşır |
-c 32768 | token cinsinden bağlam boyutunu ayarlar |
--models-dir ~/models | özel bir yerel dizinden yerel GGUF dosyalarını keşfeder |
5. Ajanınızı Bağlayın
Aşağıdaki ajanlardan birini seçin ve kurulum talimatlarını izleyin.
Pi
Pi, OpenClaw'ın arkasındaki ajan ve artık Hugging Face'e doğrudan entegre edilmiş durumda; bu sayede binlerce uyumlu modele erişim imkânı sunuyor.
Pi'yi yükleyin:
npm install -g --ignore-scripts @earendil-works/pi-coding-agent
Proje dizininizde Pi'yi başlatın:
pi
llama.cpp yapılandırması:
/login llama.cpp
/llama komutunu çalıştırarak bir model yükleyin, ardından /model komutuyla yüklenen modeli mevcut oturum için seçin.
OpenClaw
OpenClaw, llama.cpp ile yerel olarak çalışır. Modelinizi yerleşik komutla ayarlayabilirsiniz:
openclaw plugins install @openclaw/llama-cpp-provider openclaw onboard
OpenClaw için Yerel Bellek Araması
Ajanınızın bellek araması için yerel gömme modellerini Llama.cpp ile çalıştırabilirsiniz. Bunu yapmak için node-llama-cpp'ın kurulu olduğundan emin olun.
npm i node-llama-cpp
Yerel bellek araması için quantized EmbeddingGemma-300M çalıştırmak için örnek bir kod parçası aşağıdadır. OpenClaw, aşağıdaki komutla modeli otomatik olarak indirir ve sunar.
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"Gateway'yi yeniden başlatın ve doğrulayın.
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.ggufHermes Ajan
Hermes Agent, llama.cpp ile yerel olarak çalışır. ~/.hermes/config.yaml dosyasına aşağıdakileri ekleyin.
custom_providers:
- name: llama cpp (127.0.0.1:8080)
base_url: http://127.0.0.1:8080/v1Hermes Ajanı için Yerel Bellek Araması
Hermes Agent, anlamsal arama modellerini uç noktalar üzerinden kullanır. Tercih ettiğiniz gömme modelini 8080 numaralı uç noktada llama.cpp veya tercih ettiğiniz çıkarım motoruyla çalıştırdıktan sonra, aşağıdakileri ~/.hermes/config.yaml dosyasına ekleyin.
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: 1Bunun çalıştığını kontrol edin, none - built-in only başka bir bellek eklentisinin kullanılmadığını gösterir. Aşağıdaki çıktı, yerel sunumun aktif olduğunu gösterir.
$ hermes memory status
# Memory status
#────────────────────────────────────────
# Built-in: always active
# Provider: (none — built-in only)OpenCode
OpenCode, llama.cpp ile yerel olarak çalışır. ~/.config/opencode/opencode.json tanımlayın:
{
"$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
}
}
}
}
}
}Alternatif: llama-agent
llama-agent farklı bir yaklaşım benimser — ajan döngüsünü llama.cpp içine, harici bağımlılığı sıfır olan tek bir ikili dosya olarak doğrudan yerleştirir. Node.js yok, Python yok, derleyip çalıştırmanız yeterli:
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_MAraç çağrıları HTTP üzerinden değil, süreç içi gerçekleştiği için model ile ajan arasında ağ gecikmesi yoktur. Ayrıca alt ajanları, MCP sunucularını ve bir HTTP API sunucu modunu destekler.
Sonraki Adımlar
- Yapay Zeka Modellerini Yerel Olarak Kullanın — Modelleri kendi makinenizde çalıştırma hakkında daha fazla bilgi edinin
- llama.cpp Kılavuzu — Detaylı llama.cpp kurulumu ve kullanımı
- Hub'daki Ajanlar — Ajanları Hugging Face ekosistemine bağlayın