Pi Agent: 多平台部署与 llama.cpp
最后更新：2026-08-31
云端 API 好用但不便宜，本地模型免费但要配置——这一课两手都教。
1. 多平台部署概览
| 平台 | 部署方式 | 适合场景 |
|---|---|---|
| 本地开发 | 直接运行 | 开发调试 |
| Docker | 容器化 | CI/CD、团队共享 |
| 云服务器 | systemd/supervisor | 生产环境 |
| Serverless | 云函数 | 低频调用 |
| 本地模型 | llama.cpp/Ollama | 隐私、离线 |
2. 本地开发部署
(1) 虚拟环境
BASH
python -m venv .venv
source .venv/bin/activate # macOS/Linux
# .venv\Scripts\activate # Windows
pip install pi-agent
(2) 项目集成
PYTHON
# app.py
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 部署
(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}
- PI_DEFAULT_PROVIDER=deepseek
volumes:
- ./sessions:/app/sessions
- ./config:/app/config
restart: unless-stopped
(3) 启动
BASH
docker-compose up -d
4. 云服务器部署
(1) systemd 服务
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
RestartSec=10
[Install]
WantedBy=multi-user.target
BASH
sudo systemctl enable pi-agent
sudo systemctl start pi-agent
5. llama.cpp 本地模型
(1) 安装
BASH
# macOS
brew install llama.cpp
# Linux
git clone https://github.com/ggerganov/llama.cpp
cd llama.cpp && make
# Windows
# 下载预编译二进制：https://github.com/ggerganov/llama.cpp/releases
(2) 下载模型
BASH
# 下载 GGUF 格式模型
# 推荐从 Hugging Face 下载
# 例：Qwen2.5-7B-Instruct
wget https://huggingface.co/Qwen/Qwen2.5-7B-Instruct-GGUF/resolve/main/qwen2.5-7b-instruct-q4_k_m.gguf
(3) Pi Agent 配置
YAML
# ~/.pi-agent/config.yaml
providers:
local:
type: llama_cpp
model_path: "./models/qwen2.5-7b-instruct-q4_k_m.gguf"
n_gpu_layers: -1 # -1 表示全部用 GPU
n_ctx: 4096 # 上下文长度
temperature: 0.7
max_tokens: 2048
default_provider: local
(4) Python 使用
PYTHON
from pi_agent import Agent
agent = Agent(
provider="local",
model="qwen2.5-7b-instruct"
)
result = agent.chat("解释什么是递归")
print(result)
6. Ollama 集成
(1) 安装 Ollama
BASH
curl -fsSL https://ollama.com/install.sh | sh
(2) 拉取模型
BASH
ollama pull qwen2.5:7b
ollama pull llama3:8b
ollama pull mistral:7b
(3) Pi Agent 配置
YAML
providers:
ollama:
type: ollama
base_url: "http://localhost:11434"
model: "qwen2.5:7b"
▶ 示例 1：本地模型对比（难度⭐⭐）
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"),
"mistral-7b": Agent(provider="ollama", model="mistral:7b"),
}
question = "用 Python 实现快速排序"
for name, agent in models.items():
print(f"=== {name} ===")
result = agent.chat(question)
print(result[:200])
print()
Alice 的选择："日常开发用 DeepSeek API，敏感数据处理用本地 Qwen，两不耽误。"
❓ 常见问题
Q 本地模型需要什么硬件？
A 7B 模型约需 8GB 内存/显存，13B 约 16GB，70B 约 40GB+。Mac M 系列芯片性能很好。
Q llama.cpp 和 Ollama 选哪个？
A Ollama 更简单（一条命令跑模型），llama.cpp 更灵活（细粒度参数调优）。新手推荐 Ollama。
Q 本地模型和 API 模型效果差多少？
A 7B 本地模型约为 API 模型的 70-80% 能力。代码生成等任务差距更小，创意写作差距更大。
📖 小节
- 五种部署方式：本地、Docker、云服务器、Serverless、本地模型
- Docker 部署适合团队共享和 CI/CD
- llama.cpp 支持多种 GGUF 模型，可 GPU 加速
- Ollama 安装更简单，推荐新手使用
- 本地模型适合隐私场景，API 模型适合效果优先场景
📝 作业
- 基础题（难度⭐）：用 Docker 部署一个 Pi Agent 服务，验证可以正常对话。
- 进阶题（难度⭐⭐）：安装 Ollama，拉取一个模型，配置 Pi Agent 使用本地模型。
- 挑战题（难度⭐⭐⭐）：搭建一个混合部署方案——简单问题走本地模型，复杂问题自动切换到 API 模型。
