供应商管理

v2.6.0 新增

供应商（Supplier）是 API Key 的来源机构或渠道。通过在 poeti.ai 中为每个 Key 关联供应商，可以实现精确的成本核算、配额限制和智能的成本感知路由。

🆕 v2.6.0 新功能亮点

支持 5 种供应商类型（官方/转售商/自托管/Bedrock/Azure）
每个 Key 可关联供应商，实现精细成本分摊
日/月配额控制，自动保护预算
成本感知路由：优先使用单价最低的可用 Key
系统预置 8 个常用供应商，开箱即用

供应商类型详解

official

官方渠道

直接使用 AI 厂商（OpenAI、Anthropic、Google 等）官方网站购买的 API Key。

✅ 成本最透明

✅ 服务最稳定

⚠️ 价格较高

⚠️ 有速率限制

reseller

转售商

通过 API 转售商（如中间服务商）获取的 API Key，通常价格低于官方。

✅ 价格更低

✅ 配额更大

⚠️ 稳定性不一

⚠️ 需评估可信度

self_hosted

自托管

在自己服务器上部署的开源模型（如 Ollama、vLLM、LocalAI），接口兼容 OpenAI 格式。

✅ 数据完全私密

✅ 无 Token 费用

⚠️ 需要维护成本

⚠️ 性能依赖硬件

bedrock

AWS Bedrock

通过 AWS Bedrock 服务调用模型，使用 IAM Access Key 认证。

# Bedrock 需要额外配置
AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLE
AWS_REGION=us-east-1
                        

azure

Azure OpenAI

通过 Microsoft Azure OpenAI 服务调用模型，提供企业级 SLA 和私有网络。

# Azure 需要配置 Endpoint 和 Deployment
AZURE_ENDPOINT=https://your-resource.openai.azure.com
AZURE_API_KEY=your-azure-api-key
AZURE_DEPLOYMENT=gpt-4o-deployment
                        

添加供应商

通过控制台界面快速添加新供应商：

1

进入供应商管理页面

控制台 → 左侧菜单 → 供应商管理

2

点击「添加供应商」

页面右上角的蓝色按钮

3

填写供应商信息

名称、类型、描述、联系邮箱（可选）

4

设置定价参数（可选）

输入 Token 单价和输出 Token 单价（美元/1M tokens），用于成本核算

5

设置配额限制（可选）

供应商级别的日/月费用上限，作为整体兜底保护

6

保存

供应商创建完成，可以在 Key Pool 中为 Key 关联此供应商

系统预置供应商

系统已内置 8 个常用供应商，可直接关联使用：

供应商名称	类型	说明	代表模型
OpenAI Official	official	OpenAI 官方 API	gpt-4o, gpt-4-turbo
Anthropic Official	official	Anthropic 官方 API	claude-3-5-sonnet
Google AI Official	official	Google AI Studio API	gemini-1.5-pro
AWS Bedrock	bedrock	AWS Bedrock 服务	anthropic.claude-v3
Azure OpenAI	azure	Microsoft Azure OpenAI	gpt-4o (部署名)
Mistral AI Official	official	Mistral AI 官方 API	mistral-large
Cohere Official	official	Cohere 官方 API	command-r-plus
Local Ollama	self_hosted	本地 Ollama 服务	llama3, qwen2

将供应商关联到 Key

在 Key Pool 中为每个 Provider Key 关联对应供应商，以启用成本追踪：

# 为 Key 设置供应商
curl -X POST https://api.poeti.ai/api/v1/provider-keys/{key_id}/supplier \
  -H "Authorization: Bearer $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "supplier_id": 1,
    "cost_per_1k_input_tokens": 0.005,
    "cost_per_1k_output_tokens": 0.015
  }'
                

💡 提示：单价设置优先级为：Key 级别 > 供应商级别 > 全局默认。Key 级别单价会覆盖供应商默认单价。

配额管理

配额可以在两个层级设置，共同保护预算安全：

配额层级	范围	说明
供应商级配额	该供应商的所有 Key 合计	控制从某供应商采购的总花费上限
Key 级配额	单个 API Key	控制单个 Key 的使用量，防止某个 Key 被过度使用

# 设置 Key 的日/月配额
curl -X POST https://api.poeti.ai/api/v1/provider-keys/{key_id}/quota \
  -H "Authorization: Bearer $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "daily_budget_usd": 5.0,
    "monthly_budget_usd": 100.0,
    "daily_token_limit": 500000,
    "monthly_token_limit": 10000000
  }'
                

# 查询 Key 的配额使用情况
curl https://api.poeti.ai/api/v1/provider-keys/{key_id}/quota/status \
  -H "Authorization: Bearer $ADMIN_KEY"

// 响应示例
{
  "key_id": 42,
  "daily_budget_usd": 5.0,
  "daily_used_usd": 2.34,
  "daily_remaining_usd": 2.66,
  "monthly_budget_usd": 100.0,
  "monthly_used_usd": 47.82,
  "is_quota_exceeded": false,
  "next_reset_at": "2026-04-10T00:00:00Z"
}
                

⚠️ 配额超出行为：当某个 Key 超过配额后，路由系统会自动将其标记为不可用，并选择其他可用的 Key。若所有 Key 都超出配额，请求会返回 503 no_available_keys 错误。配额在下一个重置周期开始时自动恢复。

成本感知路由

v2.6.0 引入 成本感知路由器（Cost-Aware Router）。当多个 Key 都可用时，路由器会综合考虑单价、配额余量和健康分数，优先选择性价比最优的 Key。

评分公式

// 综合评分（越高越优先被选中）
score = health_score × 0.4
      + (1 - normalized_cost) × 0.3
      + quota_remaining_ratio × 0.2
      + success_rate × 0.1
                    

如何激活成本感知路由

为 Provider Key 关联供应商并填写单价
在路由策略中选择 comprehensive（综合评分）策略
系统将自动在路由决策中纳入成本因素

供应商管理 API

方法	端点	说明
GET	/api/v1/suppliers	获取供应商列表
POST	/api/v1/suppliers	创建供应商
GET	/api/v1/suppliers/{id}	获取单个供应商详情
PUT	/api/v1/suppliers/{id}	更新供应商信息
DELETE	/api/v1/suppliers/{id}	删除供应商（不可删除系统预置）
POST	/api/v1/provider-keys/{id}/supplier	为 Key 关联供应商及单价
POST	/api/v1/provider-keys/{id}/quota	设置 Key 配额
GET	/api/v1/provider-keys/{id}/quota/status	查询 Key 配额使用状态

# 获取供应商列表示例
curl https://api.poeti.ai/api/v1/suppliers \
  -H "Authorization: Bearer $ADMIN_KEY"

// 响应
{
  "code": 200,
  "data": [
    {
      "id": 1,
      "name": "OpenAI Official",
      "type": "official",
      "is_active": true,
      "is_system": true,
      "key_count": 3,
      "monthly_cost_usd": 145.32
    }
  ]
}
                