Key Pool 管理
Key Pool（密钥池）是 poeti.ai 的核心概念。每个 AI 提供商可以配置多个 API Key，形成一个 Key Pool。路由引擎从 Pool 中自动选择最优 Key 发送请求，实现负载均衡、故障切换和成本优化。
⚖️
负载均衡
多 Key 分摊流量，避免单 Key 达到速率限制
🔄
自动故障切换
某个 Key 失效时，立即切换到其他可用 Key
💰
成本优化
关联供应商后，智能选择单价最低的可用 Key
架构说明：一个"提供商（Provider）"对应一组 Key Pool。比如，你可能有一个"OpenAI Key Pool"，其中包含 5 个不同的 OpenAI API Key，还有一个"Anthropic Key Pool"，包含 3 个 Claude API Key。
添加 API Key
方式一：控制台界面
1
进入 Key Pool 管理页
控制台 → Key Pool 管理
2
选择提供商
选择或新建一个提供商（如 OpenAI）
3
点击「添加 Key」
填写 API Key、备注名称、权重、优先级等参数
4
（可选）关联供应商
选择该 Key 来自哪个供应商，并填写单价，用于成本追踪
5
保存
Key 加入 Pool，立即参与路由决策
方式二：API 添加
# 添加单个 Provider Key
curl -X POST https://api.poeti.ai/api/v1/provider-keys \
-H "Authorization: Bearer $ADMIN_KEY" \
-H "Content-Type: application/json" \
-d '{
"provider": "openai",
"api_key": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"name": "OpenAI Key #3 - 高配额",
"weight": 200,
"priority": 80,
"notes": "2026年3月购入，月配额$200"
}'
Key 字段说明
批量导入 Keys
当需要一次性添加多个 Key 时，可以通过 CSV 格式批量导入：
# CSV 格式（第一行为表头）
provider,api_key,name,weight,priority
openai,sk-aaa...,Key_A,100,50
openai,sk-bbb...,Key_B,200,80
openai,sk-ccc...,Key_C,100,30
anthropic,sk-ant-aaa...,Claude_Key1,100,50
# 通过 API 批量导入
curl -X POST https://api.poeti.ai/api/v1/provider-keys/bulk \
-H "Authorization: Bearer $ADMIN_KEY" \
-H "Content-Type: text/csv" \
--data-binary @keys.csv
⚠️ 安全提示：API Key 是高度敏感的凭证。请确保：(1) 不要在代码库中明文存储；(2) 通过安全渠道（加密传输）导入；(3) 定期检查 Key 的有效性和使用情况。
Key 健康状态
每个 Key 都有实时健康指标，在控制台 Key Pool 管理页可直接查看：
# 查询所有 Key 的健康状态
curl https://api.poeti.ai/api/v1/provider-keys?provider=openai \
-H "Authorization: Bearer $ADMIN_KEY"
// 响应示例
{
"data": [
{
"id": 1,
"name": "OpenAI Key A",
"key_prefix": "sk-aaa...",
"is_active": true,
"health_score": 0.92,
"success_rate": 99.1,
"latency_avg": 632,
"total_requests": 8420,
"consecutive_failures": 0
}
]
}
禁用与恢复 Key
# 手动禁用 Key（如 Key 泄露或即将到期）
curl -X PATCH https://api.poeti.ai/api/v1/provider-keys/1 \
-H "Authorization: Bearer $ADMIN_KEY" \
-H "Content-Type: application/json" \
-d '{"is_active": false}'
# 重新启用 Key
curl -X PATCH https://api.poeti.ai/api/v1/provider-keys/1 \
-H "Authorization: Bearer $ADMIN_KEY" \
-H "Content-Type: application/json" \
-d '{"is_active": true}'
Key Pool 管理最佳实践
🔢 每个 Provider 至少配置 3 个 Key
单个 Key 无法做负载均衡和故障切换。生产环境建议每个 Provider 配置 3~5 个 Key，确保高可用。
🏷️ 为每个 Key 添加清晰备注
记录购买日期、来源渠道、月配额限制。出现问题时快速定位。
📊 关联供应商启用成本追踪
为每个 Key 关联供应商并填写单价，才能在请求日志中看到精确的成本分析。
⚠️ 设置配额防超支
为每个 Key 设置日/月 Token 或金额配额上限，防止意外的大量请求导致费用超支。
🔄 定期轮换 Key
建议每 3~6 个月轮换一次 API Key，减少泄露风险。轮换时先添加新 Key，确认正常后再停用旧 Key。