Provider 配置

wesgine 支持多种 LLM Provider 的灵活配置，包括共享池、私有密钥和按需路由策略。

Provider 归属

三种归属

归属说明管理者
SharedHypervisor 级共享池平台管理员
NamedHypervisor 级命名平台管理员
Private (BYOK)Cell 私有Cell 用户

Provider 策略

策略含义
own_only仅使用私有 Provider
shared_only仅使用共享池
own_first优先私有，fallback 共享
shared_first优先共享，fallback 私有

自动推导

单侧池非空时自动推导策略：

情况自动推导结果
只有私有own_only
只有共享shared_only
两侧都有必须显式声明
两侧都空可不声明

密钥管理

SecretRef 三源

来源说明适用场景
inlineAES-256-GCM 加密存储个人桌面
env环境变量引用容器部署
live运行时注入平台 WES/org 代理

inline 加密

个人桌面最常用的方式——API Key 在磁盘上加密存储：

api_key_ref:
  source: inline
  value: "sk-xxx..."  # 经 AES-256-GCM 加密后存储

密钥文件：{DataDir}/secrets/spec.key（0600 权限）。

环境变量

容器部署推荐方式：

api_key_ref:
  source: env
  name: OPENAI_API_KEY

运行时注入

平台级 WES/org 代理使用：

api_key_ref:
  source: live

需要 ProviderLiveKeyFn 回调注入。

Vision 能力

声明方式

Vision 是 Model 的能力，不是 Provider 的能力：

models:
  - name: gpt-4o
    supports_vision: true

行为

场景行为
请求含图片 + model 声明 vision正常处理
请求含图片 + model 未声明 visionErrVisionNotSupported 硬错误

不再静默剥离图片。

模型配置

ContextWindow

每个模型必须配置上下文窗口：

models:
  - name: gpt-4o
    context_window: 128000
    max_output_tokens: 16384

引擎不含 LLM 模型知识（INV-DS-01），窗口信息来自 catalog.yaml。

LogicalModelGroups

同款模型多个入口时使用：

logical_model_groups:
  - name: fast
    models: [gpt-4o-mini, claude-sonnet]
  - name: strong
    models: [gpt-4o, claude-opus]

健康检查

per-Cell 健康追踪

每次调用带 cellID，实现 per-cell 的：

维度说明
健康状态最近请求的成功率
速率限制per-cell 限速
使用量统计per-cell token 计数

连通性测试

POST /cells/{id}/providers/test
{
  "mode": "chat"  # chat | embedding | vision
}

Token 用量查询

细粒度查询

GET /cells/{id}/observe/token-usage
    ?group_by=model,day
    &from=2026-09-01
    &to=2026-09-14

支持 GroupBy：model / agent / session / day / tag:actor。

聚合摘要

GET /cells/{id}/observe/token-summary

Billing 集成

不变量

ID规则
INV-BILLING-01WES 模型访问权 = UserStatus + LLM Proxy
INV-BILLING-02Token refresh 检查 UserStatus
INV-BILLING-03LLM Proxy 转发前检查 UserStatus
INV-BILLING-04JWT 过期后 fallback 到 BYOK
INV-BILLING-05应用层不做 billing pre-check

注意事项