Pi Agent: 安装与认证配置
最后更新：2026-08-31
工欲善其事，必先利其器。这一课带你从零搭建 Pi Agent 开发环境，5 分钟跑起来。
1. 环境要求
| 项目 | 最低要求 | 推荐版本 |
|---|---|---|
| Python | 3.9+ | 3.11+ |
| pip | 最新版 | 最新版 |
| 操作系统 | Windows / macOS / Linux | 任意 |
| 内存 | 512MB 可用 | 2GB+ |
| 磁盘 | 200MB | 1GB+ |
验证 Python 版本：
BASH
python --version
# Python 3.11.8
2. 安装 Pi Agent
(1) pip 安装（推荐）
BASH
pip install pi-agent
(2) 从源码安装
BASH
git clone https://github.com/pi-agent/pi-agent.git
cd pi-agent
pip install -e .
(3) 验证安装
BASH
pi-agent --version
# Pi Agent v0.8.0
(4) 可选依赖
根据需要安装额外功能：
BASH
pip install pi-agent[all] # 安装所有可选依赖
pip install pi-agent[deepseek] # DeepSeek 支持
pip install pi-agent[local] # 本地模型支持（llama.cpp）
pip install pi-agent[tools] # 扩展工具集
3. 认证与模型配置
Pi Agent 支持多个 LLM 提供商，使用前需要配置 API 密钥。
(1) 环境变量方式（推荐）
BASH
# DeepSeek
export PI_DEEPSEEK_API_KEY="sk-xxxxxxxx"
# OpenAI
export PI_OPENAI_API_KEY="sk-xxxxxxxx"
# Anthropic
export PI_ANTHROPIC_API_KEY="sk-ant-xxxxxxxx"
Windows PowerShell：
POWERSHELL
$env:PI_DEEPSEEK_API_KEY = "sk-xxxxxxxx"
(2) 配置文件方式
创建 ~/.pi-agent/config.yaml：
YAML
providers:
deepseek:
api_key: "sk-xxxxxxxx"
base_url: "https://api.deepseek.com"
model: "deepseek-chat"
openai:
api_key: "sk-xxxxxxxx"
model: "gpt-4o"
anthropic:
api_key: "sk-ant-xxxxxxxx"
model: "claude-sonnet-4-20250514"
default_provider: deepseek
(3) 代码内配置
PYTHON
from pi_agent import Agent
agent = Agent(
name="my_agent",
provider="deepseek",
api_key="sk-xxxxxxxx",
model="deepseek-chat"
)
4. 模型提供商一览
| 提供商 | 模型示例 | 特点 | 价格 |
|---|---|---|---|
| DeepSeek | deepseek-chat | 性价比极高，中文优秀 | 低 |
| OpenAI | gpt-4o | 综合能力强 | 中高 |
| Anthropic | claude-sonnet-4-20250514 | 长文本、代码强 | 中 |
| 本地模型 | llama.cpp | 隐私、离线 | 免费 |
| Ollama | llama3, mistral | 本地部署方便 | 免费 |
▶ 示例 1：多提供商切换（难度⭐）
PYTHON
from pi_agent import Agent
deepseek_agent = Agent(provider="deepseek", model="deepseek-chat")
openai_agent = Agent(provider="openai", model="gpt-4o")
result_d = deepseek_agent.chat("用一句话解释量子计算")
result_o = openai_agent.chat("用一句话解释量子计算")
print(f"DeepSeek: {result_d}")
print(f"OpenAI: {result_o}")
5. 首次启动测试
安装和配置完成后，运行快速测试：
BASH
pi-agent chat "你好，Pi Agent！"
预期输出：
TEXT
📖 仅展示
🤖 Pi Agent v0.8.0
📡 Provider: deepseek (deepseek-chat)
💬 你好！我是 Pi Agent，有什么可以帮你的？
Alice 按照以上步骤安装后，3 分钟就完成了环境搭建。Bob 说："Pi Agent 的安装比大多数 Python 工具都简单——装完配个密钥就能用。"
❓ 常见问题
Q pip install 失败怎么办？
A 先升级 pip（
pip install --upgrade pip），如果网络问题就换源：pip install pi-agent -i https://pypi.tuna.tsinghua.edu.cn/simple。Q API 密钥配置了但不生效？
A 检查环境变量名是否正确（
PI_ 前缀），配置文件路径是否正确（~/.pi-agent/config.yaml）。代码内配置优先级最高。Q 没有 API 密钥能用吗？
A 可以。安装
pi-agent[local]，使用 llama.cpp 或 Ollama 运行本地模型，不需要任何 API 密钥。详见第 18 课。📖 小节
- Python 3.9+ 即可安装，
pip install pi-agent一行搞定 - 三种认证方式：环境变量（推荐）、配置文件、代码内配置
- 支持多个 LLM 提供商，DeepSeek 性价比最高，本地模型完全免费
- 首次启动用
pi-agent chat验证环境
📝 作业
- 基础题（难度⭐）：安装 Pi Agent 并用
pi-agent --version验证安装成功。 - 进阶题（难度⭐⭐）：配置至少两个 LLM 提供商，分别用代码创建 Agent 实例并验证连通。
- 挑战题（难度⭐⭐⭐）：写一个脚本，自动检测可用的 API 密钥，列出当前可用的提供商。
