模型配置 models.yml

models.yml 管理 AI 模型的 API 密钥、默认模型和自定义提供商。

API 密钥配置

三种配置方式

api-keys:
  # 方式 1：直接填写（不推荐，有泄露风险）
  anthropic: "sk-ant-api03-xxxx"

  # 方式 2：引用环境变量（推荐）
  openai: "${OPENAI_API_KEY}"

  # 方式 3：留空，自动查找同名环境变量
  google: ""

方式 2 和 3 都需要在服务器启动脚本中设置环境变量。

API Key 解析优先级

当 AI 请求需要密钥时，按以下顺序查找：

1. 自定义提供商的 apiKey 字段
2. api-keys.{provider} 中的配置
3. {PROVIDER}_API_KEY 环境变量
4. 全部未找到 → 报错

内置提供商

以下提供商无需额外配置，只需填写 API Key 即可使用：

提供商	模型示例	说明
anthropic	anthropic:claude-sonnet-4-5	Anthropic Claude 系列
openai	openai:gpt-4.1	OpenAI GPT 系列
google	google:gemini-2.5-flash	Google Gemini 系列
deepseek	deepseek:deepseek-chat	DeepSeek（性价比之选）
minimax	minimax:minimax-m2.5	MiniMax

默认模型设置

defaults:
  model:
    primary: "anthropic:claude-sonnet-4-5"
    fallbacks:
      - "deepseek:deepseek-chat"
  temperature: 0.7
  maxTokens: 2048
  thinkingLevel: "off"

字段	类型	默认值	说明
model.primary	string	—	主模型，格式 provider:modelId
model.fallbacks	list	[]	备选模型，主模型不可用时依次尝试
temperature	float	0.7	采样温度（0.0-2.0），越高越有创意
maxTokens	int	2048	最大输出 token 数
thinkingLevel	string	"off"	思维链级别

模型引用格式

{provider}:{modelId}

示例：

• anthropic:claude-sonnet-4-5
• openai:gpt-4.1
• my-proxy:claude-3-opus（自定义提供商）

思维链级别

部分模型支持深度推理（thinking / extended thinking）。

级别	说明
off	关闭（默认）
minimal	最小推理
low	低级推理
medium	中级推理
high	高级推理
xhigh	最高级推理

注意

启用思维链会显著增加 token 消耗和响应时间。

Failover 机制

请求时按顺序尝试：primary → fallbacks[0] → fallbacks[1] → ...

全部失败后向玩家发送错误消息。建议至少配置一个 fallback。

自定义提供商

接入任意 OpenAI / Anthropic 兼容的 API 端点。适用于中转站、私有部署、第三方代理等场景。

完整示例

providers:
  # 提供商名称（小写，用于模型引用）
  my-proxy:
    # API 端点地址（必填）
    baseUrl: "https://api.my-proxy.com/v1"
    # API 密钥（必填，支持 ${ENV}）
    apiKey: "${MY_PROXY_KEY}"
    # API 协议（可选，默认 openai-completions）
    api: "openai-completions"
    # 可用模型列表（必填）
    models:
      - id: "claude-3-opus"
        name: "Claude 3 Opus (Proxy)"
        contextWindow: 200000
        maxTokens: 4096
        reasoning: false
        inputTypes: ["text"]
      - id: "gpt-4-turbo"
        name: "GPT-4 Turbo (Proxy)"
        contextWindow: 128000
        maxTokens: 4096

提供商字段

字段	必填	类型	说明
baseUrl	✅	string	API 端点 URL
apiKey	✅	string	支持 ${ENV_VAR}
api	❌	string	协议类型，默认 openai-completions
models	✅	list	至少包含一个模型

API 协议类型

值	说明
openai-completions	OpenAI Chat Completions API（默认）
openai-responses	OpenAI Responses API
anthropic-messages	Anthropic Messages API

模型字段

字段	必填	类型	默认值	说明
id	✅	string	—	模型 ID
name	❌	string	同 id	显示名称
contextWindow	❌	int	128000	上下文窗口
maxTokens	❌	int	4096	最大输出
reasoning	❌	bool	false	是否推理模型
inputTypes	❌	list	["text"]	输入类型

使用自定义提供商

配置完成后，在助手配置或默认模型中引用：

# models.yml
defaults:
  model:
    primary: "my-proxy:claude-3-opus"

# 或在助手配置中
# assistants/player-helper/config.yml
model:
  primary: "my-proxy:gpt-4-turbo"