Provider 管理

WesCraft 的 AI 能力依赖 LLM Provider 驱动。本文介绍如何配置和管理 AI 模型。

三种模型来源

WesCraft 支持三种 Provider 来源：

来源优先级

个人版默认 Provider 策略为 own_only（仅使用自有密钥），团队版可配置策略：

BYOK 配置步骤

第一步：编辑配置文件

打开 config.yaml 文件，添加 Provider 配置：

providers:
  - name: my-openai
    type: openai
    base_url: https://api.openai.com/v1
    api_key_ref:
      source: inline
      value: sk-xxxxxxxxxxxxx
    models:
      - name: gpt-4o
        context_window: 128000
        supports_vision: true
      - name: gpt-4o-mini
        context_window: 128000

第二步：声明模型能力

每个模型必须声明 context_window（引擎不含模型 catalog，INV-DS-01）：

models:
  - name: claude-sonnet-4-20250514
    context_window: 200000
    supports_vision: true     # 可选：声明 Vision 支持

第三步：测试连通性

# 测试 Chat 模式
POST /cells/{cellID}/providers/test
{
  "mode": "chat"
}

# 测试 Embedding 模式
POST /cells/{cellID}/providers/test
{
  "mode": "embedding"
}

# 测试 Vision 模式
POST /cells/{cellID}/providers/test
{
  "mode": "vision"
}

支持的 Provider 类型

WES 模型

WES 平台模型登录即用，无需额外配置：

1. 在 WesCraft 中登录 WES 账号
2. 系统自动获取可用模型列表
3. 模型规格由 catalog.yaml 自动补齐

NormalizeProvider

wesapp 的 NormalizeProvider() 自动从 catalog.yaml 补齐模型信息：

// 自动补齐 ContextWindow 等配置
provider.NormalizeProvider(providerConfig)

catalog 数据的唯一来源是 weisyn.git/catalog.yaml（INV-DS-01），引擎本身不含 LLM 模型知识。

连通性测试

三种测试模式

通过 UI 测试

1. 进入 设置 → AI 模型
2. 找到要测试的 Provider
3. 点击 测试连接
4. 查看测试结果

常见测试失败原因

Vision 能力

Vision 能力声明

Vision 是模型级能力，不是 Provider 级能力（v1.0.1 变更）：

models:
  - name: gpt-4o
    context_window: 128000
    supports_vision: true      # ← 在模型级别声明

Vision 行为

当请求包含图片但模型未声明 SupportsVision=true 时，引擎返回 ErrVisionNotSupported 硬错误——不再静默剥离图片。

使用 Vision

在 Sidebar Chat 中可以直接发送图片：

[粘贴截图]
请分析这张图片中的表格内容
→ AI 使用 Vision 能力分析图片

Embedding 模型配置

知识库的语义搜索和记忆系统需要 Embedding 模型支持：

providers:
  - name: my-embedding
    type: openai
    base_url: https://api.openai.com/v1
    api_key_ref:
      source: inline
      value: sk-xxxxxxxxxxxxx
    embedding_model: text-embedding-3-small

生成 Embedding

# Cell 级 Embedding 生成
POST /cells/{cellID}/embeddings
{
  "input": "文本内容",
  "model": "text-embedding-3-small"
}

LLM Catalog 契约

唯一来源

LLM 模型市场化数据（名称、上下文窗口、最大输出、能力、价格）的唯一权威来源是 catalog.yaml。

契约规则

Provider 测试 ≠ Billing 状态

Provider 测试返回"余额不足"是 Provider 自身的限制，不等同于 WES 平台的 billing.active=false。两者独立判定。

配置最佳实践

1. 先配后用：先配置好 Provider 并测试通过，再开始使用 AI 功能
2. 声明 ContextWindow：必须为每个模型声明 context_window，否则引擎无法正确管理上下文
3. 本地模型无需 catalog：Ollama/vLLM 等本地部署模型不列入 catalog，用户自行声明
4. 多 Provider 备选：配置多个 Provider 时，设置合理的 fallback 策略
5. 定期测试：API Key 过期或额度用完时 Provider 会失效，建议定期测试