Provider 管理

wescode 的 AI 模型配置——三种来源、连通性测试、Vision 与 Embedding 支持。

三种模型来源

来源	标识前缀	配置方式	费用承担
WES	`wes:`	登录 weisyn 平台即用	平台计费
Org	`org:`	组织管理员统一配置	组织统一结算
BYOK	`byok:`	用户手动添加 API Key	用户自付

单一数据源原则（INV-PROVIDER-VIEW-01）

所有可用模型通过单一 RPC sidebar/availableModels 统一返回：

// Chat 面板模型选择器只消费 availableModels
const models = await rpc('sidebar/availableModels')
// 返回 WES + Org + BYOK 所有可用模型

禁止前端从多个 RPC 合并模型列表。

BYOK 配置

配置步骤

打开设置 → Provider
点击「添加 Provider」
填写配置信息

配置字段

字段	必填	说明
Name	✅	Provider 名称（如 `my-openai`）
Type	✅	Provider 类型（`openai` / `azure_openai` / `anthropic` / ...）
Base URL	✅	API 端点
API Key	✅	API 密钥
Models	✅	支持的模型列表

配置示例

# BYOK 配置
name: my-openai
type: openai
base_url: https://api.openai.com/v1
api_key_ref:
  source: inline
  value: sk-proj-xxx...
models:
  - name: gpt-4o
    context_window: 128000
    max_output: 16384
    supports_vision: true
  - name: gpt-4o-mini
    context_window: 128000

模型必须声明 ContextWindow

引擎不含 LLM 模型 catalog（INV-DS-01）。如果配置中未声明 context_window：

引擎不猜测物理窗口
经济预算走 DefaultEconomicWindow 并 Warn
长对话可能触发 provider context_length_exceeded

WES 模型

使用方式

工作原理

weisyn.ProviderCatalog() → catalog.yaml
  → 模型名称 / 上下文窗口 / 最大输出 / 能力 / 价格
  → 通过 NormalizeProvider() 自动补齐 ContextWindow

WES 计费

通过 weisyn LLM Proxy 转发请求
代理 SettleProxy 自动写入用量
应用层不做 post-run 结算（INV-BILLING-05）

WES 欠费行为（INV-CHAT-02/04）

场景	WES 模型	BYOK 模型	发送
余额充足	可选	可选	正常
欠费 + 有 BYOK + 选 BYOK	`disabled`	可选	正常
欠费 + 有 BYOK + 选 WES	`disabled`	可选	阻断
欠费 + 无 BYOK	`disabled`	—	阻断

Org 组织托管模型

组织管理员在 weisyn 控制台统一配置模型，成员通过 IdentityAccessToken 访问：

组织管理员配置 → weisyn 控制台
  → 成员登录后自动获取 org: 前缀模型
  → 使用 IdentityAccessToken 认证

Org 模型不走个人钱包计费（INV-BILLING-03）。

连通性测试

测试端点

POST /cells/{cellID}/providers/test

三种测试模式

模式	参数	测试内容
`chat`	`mode: "chat"`	基础对话能力
`embedding`	`mode: "embedding"`	向量化能力（CKG 语义搜索）
`vision`	`mode: "vision"`	图像理解能力

测试示例

curl -X POST http://localhost:9091/cells/ws-a1b2/providers/test \
  -H "Content-Type: application/json" \
  -d '{"provider": "my-openai", "model": "gpt-4o", "mode": "chat"}'

Vision 多模态支持

按 Model 声明（INV-VIS-01~04）

Vision 能力声明在 Models[].SupportsVision——Vision 是 Model 的能力，不是 Provider 的能力：

models:
  - name: gpt-4o
    supports_vision: true   # ← 支持 Vision
  - name: gpt-4o-mini
    supports_vision: false   # ← 不支持

Vision 行为

情况	行为
请求含图片 + Model 声明 Vision	正常处理
请求含图片 + Model 未声明 Vision	`ErrVisionNotSupported` 硬错误
无图片请求	正常处理，无需 Vision

不再静默剥离图片——明确告知用户模型不支持。

Embedding 配置

CKG 的语义搜索依赖 Embedding 模型：

# Provider 配置中声明 Embedding Model
name: my-openai
type: openai
embedding_model: text-embedding-3-small
models:
  - name: gpt-4o

Embedding 用于：

CKG 语义搜索（代码含义相近的符号）
Knowledge 知识库文件检索

SecretRef 密钥管理

API Key 通过 SecretRef 管理，支持三种来源：

来源	说明	适用场景
`inline`	AES-256-GCM 封套加密后存入 DB	个人用户 BYOK
`env`	从环境变量读取	服务端部署
`live`	运行时动态获取（JWT）	WES / Org

inline 加密流程

用户输入 API Key
  → config.MapSecretValues(spec, box.Seal)
  → AES-256-GCM 加密
  → 密文存入 hypervisor.db
  → 密钥文件: {DataDir}/secrets/spec.key (0600)

安全保障

exec 子进程通过 SanitizeEnv 清理敏感环境变量（INV-SEC-03/04）
出网脱敏只有一个执行点 config.RedactSecrets（INV-SEC-02）
SecretRef.MarshalJSON 吐的是含明文的 storage view（落盘要值）

模型选择不变量

INV-MODEL-01

AppRunRequest.Model 为空时引擎拒绝执行：

// 空 Model → ErrModelRequired
// 用户必须始终知道"我在和哪个模型对话"

INV-MODEL-02

所有可用模型对用户可见。引擎能用的所有 provider，前端都必须展示。禁止"幽灵 provider"。

前端发送门控

// 发送按钮在 selectedModel == "" 时 disabled
<Button disabled={!selectedModel} onClick={handleSend}>发送</Button>

最佳实践

BYOK 必须声明 ContextWindow：否则长对话可能失败
使用连通性测试验证配置：配置后立即测试
WES 欠费时配置 BYOK 备用：确保持续可用
Vision 按模型声明：不是所有模型都支持图像