Pi Agent: 问题排查与 AI 提供商
最后更新：2026-08-31
遇到问题别慌，90% 的故障都能在这页找到答案。
1. 常见问题排查
(1) 安装问题
| 问题 | 原因 | 解决方案 |
|---|---|---|
| pip install 失败 | pip 版本过低 | pip install --upgrade pip |
| 网络超时 | 网络问题 | 换源：-i https://pypi.tuna.tsinghua.edu.cn/simple |
| 编译错误 | 缺少构建工具 | 安装 build-essential（Linux）或 Visual Studio Build Tools（Windows） |
| 权限错误 | 全局安装需要权限 | 用 --user 或虚拟环境 |
(2) API 调用问题
| 错误码 | 含义 | 解决方案 |
|---|---|---|
| 401 | 认证失败 | 检查 API 密钥是否正确 |
| 429 | 请求过多 | 降低请求频率，或升级 API 套餐 |
| 500 | 服务器错误 | 稍后重试 |
| 503 | 服务不可用 | 检查提供商状态页 |
(3) 工具调用问题
| 问题 | 原因 | 解决方案 |
|---|---|---|
| 工具不响应 | 权限不足 | 检查信任级别和工具权限 |
| 工具超时 | 执行时间过长 | 增大 max_execution_time |
| 工具返回空 | 输入参数错误 | 检查参数类型和格式 |
| 文件找不到 | 路径错误 | 使用绝对路径 |
2. 调试技巧
(1) 启用调试模式
BASH
pi-agent chat --debug
或：
PYTHON
agent = Agent(name="debug", debug=True)
(2) 查看详细日志
PYTHON
import logging
logging.basicConfig(level=logging.DEBUG)
agent = Agent(name="debug")
agent.chat("测试消息")
# 输出详细的请求/响应日志
(3) 事件追踪
PYTHON
@agent.on("*")
def trace(event):
print(f"[{event.timestamp}] {event.name}: {event.data}")
3. AI 提供商参考
(1) DeepSeek
YAML
providers:
deepseek:
api_key: "sk-xxxxxxxx"
base_url: "https://api.deepseek.com"
models:
- name: deepseek-chat
context: 64000
input_price: 1.0 # ¥/百万 token
output_price: 2.0
- name: deepseek-reasoner
context: 64000
input_price: 4.0
output_price: 16.0
(2) OpenAI
YAML
providers:
openai:
api_key: "sk-xxxxxxxx"
base_url: "https://api.openai.com/v1"
models:
- name: gpt-4o
context: 128000
input_price: 2.5 # $/百万 token
output_price: 10.0
- name: gpt-4o-mini
context: 128000
input_price: 0.15
output_price: 0.6
(3) Anthropic
YAML
providers:
anthropic:
api_key: "sk-ant-xxxxxxxx"
base_url: "https://api.anthropic.com"
models:
- name: claude-sonnet-4-20250514
context: 200000
input_price: 3.0
output_price: 15.0
- name: claude-3-5-haiku-20241022
context: 200000
input_price: 0.8
output_price: 4.0
(4) Google Gemini
YAML
providers:
gemini:
api_key: "AIzaxxxxxxxx"
base_url: "https://generativelanguage.googleapis.com/v1beta"
models:
- name: gemini-2.0-flash
context: 1048576
input_price: 0.1
output_price: 0.4
(5) 本地模型 (llama.cpp)
YAML
providers:
local:
type: llama_cpp
model_path: "./models/qwen2.5-7b-instruct-q4_k_m.gguf"
n_gpu_layers: -1
n_ctx: 4096
(6) Ollama
YAML
providers:
ollama:
type: ollama
base_url: "http://localhost:11434"
model: "qwen2.5:7b"
4. 性能优化
(1) 减少延迟
PYTHON
agent = Agent(
max_tokens=2048, # 限制输出长度
temperature=0.3, # 低温度加速生成
context_window=4096 # 小窗口减少输入
)
(2) 减少费用
PYTHON
agent = Agent(
provider="deepseek", # 选择便宜的提供商
max_tokens=1024, # 限制输出
auto_summarize=True # 自动摘要减少上下文
)
(3) 并发控制
PYTHON
import asyncio
from pi_agent import AsyncAgent
sem = asyncio.Semaphore(5) # 最多 5 个并发
async def limited_chat(prompt):
async with sem:
agent = AsyncAgent(name="worker")
return await agent.chat(prompt)
5. 健康检查
▶ 示例 1：一键诊断脚本（难度⭐）
PYTHON
from pi_agent import Config, Agent
print("=== Pi Agent 诊断 ===")
config = Config.load()
print(f"配置文件: {'OK' if config else '未找到'}")
for name, provider in config.providers.items():
try:
agent = Agent(provider=name)
agent.chat("ping")
print(f"提供商 {name}: OK")
except Exception as e:
print(f"提供商 {name}: FAIL ({e})")
print("=== 诊断完成 ===")
Bob 的建议："遇到问题先跑诊断脚本，90% 的情况都能定位到原因。剩下 10% 开 debug 模式看日志。"
❓ 常见问题
Q Agent 一直不回复怎么办？
A 检查网络连接、API 密钥是否有效、提供商服务是否正常。开启 debug 模式查看详细请求日志。
Q 工具调用报 permission denied？
A 检查项目信任级别是否为 trusted 或 restricted。shell 和 file_write 工具需要较高级别的信任。
Q 如何切换到更便宜的模型？
A 交互模式用
/model gpt-4o-mini，代码中用 Agent(model="deepseek-chat")，或修改配置文件中的 default_model。📖 小节
- 常见问题分三类：安装、API、工具，各有排查路径
- 调试三件套：--debug、logging、事件追踪
- 6 种 AI 提供商完整配置参考
- 性能优化三方向：减少延迟、减少费用、控制并发
- 健康检查脚本快速定位问题
📝 作业
- 基础题（难度⭐）：运行健康检查脚本，确认你的环境配置正确。
- 进阶题（难度⭐⭐）：配置两个不同的 AI 提供商，编写代码在主提供商失败时自动切换到备用提供商。
- 挑战题（难度⭐⭐⭐）：实现一个完整的监控方案：定时检查提供商可用性、记录响应延迟、token 消耗趋势，异常时发送通知。
