Pi Agent: Multi-Platform Deployment & llama.cpp
Last updated: 2026-08-31
Cloud APIs are convenient but costly; local models are free but need setup — this lesson covers both.
1. Multi-Platform Deployment Overview
| Platform | Method | Best For |
|---|---|---|
| Local dev | Direct run | Development & debugging |
| Docker | Containerization | CI/CD, team sharing |
| Cloud server | systemd/supervisor | Production |
| Serverless | Cloud functions | Low-frequency calls |
| Local models | llama.cpp/Ollama | Privacy, offline |
2. Local Development Deployment
(1) Virtual Environment
BASH
python -m venv .venv
source .venv/bin/activate # macOS/Linux
# .venv\Scripts\activate # Windows
pip install pi-agent
(2) Project Integration
PYTHON
from pi_agent import Agent
agent = Agent(name="app_agent", config_file=".pi-agent.yaml")
def process_request(user_input: str) -> str:
return agent.chat(user_input)
3. Docker Deployment
(1) Dockerfile
DOCKERFILE
FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
ENV PI_DEEPSEEK_API_KEY=""
ENV PI_DEFAULT_PROVIDER=deepseek
CMD ["python", "agent_service.py"]
(2) docker-compose.yaml
YAML
version: "3.8"
services:
pi-agent:
build: .
ports:
- "8000:8000"
environment:
- PI_DEEPSEEK_API_KEY=${PI_DEEPSEEK_API_KEY}
volumes:
- ./sessions:/app/sessions
restart: unless-stopped
4. Cloud Server Deployment
INI
# /etc/systemd/system/pi-agent.service
[Unit]
Description=Pi Agent Service
After=network.target
[Service]
Type=simple
User=piagent
WorkingDirectory=/opt/pi-agent
Environment=PI_DEEPSEEK_API_KEY=sk-xxxxxxxx
ExecStart=/opt/pi-agent/.venv/bin/python agent_service.py
Restart=always
[Install]
WantedBy=multi-user.target
5. llama.cpp Local Models
(1) Install
BASH
# macOS
brew install llama.cpp
# Linux
git clone https://github.com/ggerganov/llama.cpp
cd llama.cpp && make
(2) Download Model
BASH
# Download GGUF format models from Hugging Face
wget https://huggingface.co/Qwen/Qwen2.5-7B-Instruct-GGUF/resolve/main/qwen2.5-7b-instruct-q4_k_m.gguf
(3) Pi Agent Config
YAML
providers:
local:
type: llama_cpp
model_path: "./models/qwen2.5-7b-instruct-q4_k_m.gguf"
n_gpu_layers: -1
n_ctx: 4096
temperature: 0.7
default_provider: local
6. Ollama Integration
(1) Install
BASH
curl -fsSL https://ollama.com/install.sh | sh
(2) Pull Models
BASH
ollama pull qwen2.5:7b
ollama pull llama3:8b
(3) Pi Agent Config
YAML
providers:
ollama:
type: ollama
base_url: "http://localhost:11434"
model: "qwen2.5:7b"
Example: Local Model Comparison (Difficulty: ⭐⭐)
PYTHON
from pi_agent import Agent
models = {
"qwen2.5-7b": Agent(provider="ollama", model="qwen2.5:7b"),
"llama3-8b": Agent(provider="ollama", model="llama3:8b"),
}
question = "Implement quicksort in Python"
for name, agent in models.items():
print(f"=== {name} ===")
result = agent.chat(question)
print(result[:200])
FAQ
Q Hardware requirements for local models?
A 7B models need ~8GB RAM/VRAM, 13B need ~16GB, 70B need ~40GB+. Apple M-series chips perform well.
Q llama.cpp or Ollama?
A Ollama is simpler (one command to run). llama.cpp is more flexible (fine-grained parameter tuning). Beginners should use Ollama.
Q Local vs API model quality gap?
A 7B local models are ~70-80% of API model capability. Smaller gap for code generation, larger for creative writing.
Summary
- Five deployment methods: local, Docker, cloud, serverless, local models
- Docker for team sharing and CI/CD
- llama.cpp supports various GGUF models with GPU acceleration
- Ollama is simpler; recommended for beginners
- Local models for privacy; API models for quality
Exercises
- Basic (Difficulty: ⭐): Deploy Pi Agent with Docker, verify it can chat normally.
- Intermediate (Difficulty: ⭐⭐): Install Ollama, pull a model, configure Pi Agent for local inference.
- Advanced (Difficulty: ⭐⭐⭐): Build a hybrid deployment — simple questions via local model, complex ones auto-switch to API.
