跳转到内容

模型与设置

aidy 通过 AI SDK 的服务商包调用语言模型。你提供一条模型链:按顺序尝试的端点列表,某个服务商出错、余额不足或被限流时自动换到下一个。配置中的模型链是默认值,管理员可以在运行时替换,无需重新部署。

createAidy({
// ...
models: {
chain: [
{
id: 'qwen',
provider: 'openai-compatible',
model: 'qwen3-max',
baseURL: 'https://dashscope.aliyuncs.com/compatible-mode/v1',
apiKey: process.env.DASHSCOPE_API_KEY,
providerOptions: { 'openai-compatible': { enable_thinking: false } },
},
{
id: 'claude',
provider: 'anthropic',
model: 'claude-sonnet-4-5',
apiKey: process.env.ANTHROPIC_API_KEY,
vision: true,
},
],
},
});

每个端点的字段:

字段 含义
id 必填,在链中唯一,1 到 64 个字符。设置按它保存条目的 API 密钥。
provider openai-compatible、openai 或 anthropic。
model 服务商的模型 id。
baseURL openai-compatible 必填;其他服务商可选(用于代理或网关)。
apiKey 服务商密钥。省略时,openai 和 anthropic 包会读取 OPENAI_API_KEY 和 ANTHROPIC_API_KEY。
vision 模型支持图片。带图片的轮次优先发给视觉端点(见视觉)。
temperature 每次调用该端点时都会带上;未设置则不传。
maxOutputTokens 每次调用该端点时都会带上。
cooldownSeconds { quota?, rateLimit?, error? }:出错端点的休眠时长(见回退与休眠)。
providerOptions 原样传给服务商,以服务商名称为键。
  • openai-compatible 适用于任何兼容 OpenAI chat API 的端点:通过 DashScope 使用通义千问(https://dashscope.aliyuncs.com/compatible-mode/v1)、DeepSeek、vLLM、LiteLLM 网关等。必须提供 baseURL。
  • openai 即 OpenAI 官方服务。
  • anthropic 即 Claude。

providerOptions 会原样传给服务商。对于通义千问的推理模型,{ 'openai-compatible': { enable_thinking: false } } 可以关闭思考模式,让工具调用轮次更快。aidy 从不把服务商的原始推理内容发给客户端。

内嵌 aidy 时,模型链的条目也可以是任意 AI SDK 语言模型,例如通过 agents 包使用 Workers AI:

import { createAI } from 'agents/models/ai-sdk';
createAidy({
// ...
models: {
chain: [{ id: 'workers-ai', languageModel: createAI({ binding: env.AI })('@cf/zai-org/glm-4.7-flash') }],
},
});

自定义条目为 { id, languageModel },同样可以设置 vision、temperature、maxOutputTokens 和 cooldownSeconds;id 用于在设置中标识它。自定义条目只能写在代码中,设置 API 只接受服务商端点。

每个模型步骤,aidy 调用链中第一个不在休眠中的端点:

  • 超时、408、5xx、网络错误和不可用的回答(调用未知工具、空回答)会在同一端点上重试,最多 4 次。
  • 其他失败(如 400、401、403、404、额度类响应、429),以及上述重试的最后一次失败,会把这一步交给下一个端点,出错的端点进入休眠:
失败 休眠
额度类:402,或状态、响应体中含有 quota、insufficient、exhausted 或服务商的额度错误码(如 401008) 6 小时
429(限流) 60 秒
其他 5 分钟

不可用的回答会换到下一个端点,但不会让端点休眠。休眠时长可以按端点覆盖:

{ id: 'qwen', provider: 'openai-compatible', /* … */ cooldownSeconds: { quota: 3600, rateLimit: 30, error: 120 } }

休眠中的端点会被跳过。没有可用端点时,运行以 RUN_ERROR 结束,code 为 model_unavailable。每次失败的尝试都会产生一个 aidy.model.retry 事件,其中 endpoint 是这次调用的端点,下一次尝试换到另一个端点时 fallback 为 true(侧边栏显示“模型繁忙,正在重试”);失败尝试产生的部分文本通过 aidy.message.discard 丢弃。事件详情见事件参考。

每个 aidy 实例只有一条模型链,由运行和宿主任务共用。休眠状态保存在实例内存中(一个进程或一个 Workers isolate)。

消息中带图片的轮次会按链的顺序优先发给 vision: true 的端点。没有视觉端点能回答时,其他端点只收到文本,每张图片的位置换成一条说明;链中根本没有视觉端点时,aidy 不会去获取图片。如果用户会附上截图,链中要有一个视觉模型;把纯文本模型放在前面可以让普通轮次更便宜。图片如何交给模型,见 AG-UI:用户消息。

任何已登录用户都可以读取当前生效的模型链。身份中带有 aidy:admin scope 的用户可以在运行时替换它。

GET /aidy/v0/settings
{
"models": {
"chain": [
{
"id": "qwen",
"provider": "openai-compatible",
"model": "qwen3-max",
"baseURL": "https://dashscope.aliyuncs.com/compatible-mode/v1",
"hasApiKey": true
}
]
}
}

GET 从不返回 API 密钥,只返回 hasApiKey。自定义条目显示为 { id, provider: "custom", model, vision?, hasApiKey: false },其中 model 是该语言模型的 id。

PUT /aidy/v0/settings
Content-Type: application/json
{
"models": {
"chain": [
{ "id": "qwen", "provider": "openai-compatible", "model": "qwen3-max", "baseURL": "https://dashscope.aliyuncs.com/compatible-mode/v1" },
{ "id": "gpt", "provider": "openai", "model": "gpt-5", "apiKey": "sk-…", "vision": true }
]
}
}
  • PUT 需要 aidy:admin,会替换整条链。链中至少要有一个条目,未知字段会被拒绝。
  • 未带 apiKey 的端点保留同一 id 条目原有的密钥。只有设置或更换密钥时才需要发送它。
  • provider 必须是 openai-compatible、openai 或 anthropic:自定义条目无法回传,因此保存后会被替换掉。
  • 保存后,这些设置优先于配置中的 models(包括其中的自定义条目)。响应是新的模型链,格式与 GET 相同。
DELETE /aidy/v0/settings

DELETE 需要 aidy:admin。它删除已保存的设置,让配置中的模型链重新生效,并按 GET 的格式返回该链。

保存的设置在写入存储前,用从实例 secret(至少 32 字节)派生的密钥做 AES-GCM 加密。要轮换它,传入一个列表:第一个用于加密,每一个都可用于解密,用旧密钥加密的设置在读取时会改用第一个重新加密。

createAidy({ secret: [process.env.AIDY_SECRET!, process.env.AIDY_PREVIOUS_SECRET!], /* … */ });

aidy-server 从 AIDY_SECRET 和 AIDY_PREVIOUS_SECRET 读取同样的两个值。如果保存的设置是用 aidy 已经没有的密钥加密的,请求会返回 503 settings_unreadable,管理员可以用 DELETE 删除它们。见部署。

@aidy-dev/react 提供了管理表单:

import { ModelSettings } from '@aidy-dev/react';
export function AdminModelsPage() {
return <ModelSettings />;
}

它列出模型链,管理员可以添加、删除和调整端点顺序,选择服务商,设置模型、Base URL、密钥、temperature、最大输出 token 数以及是否支持图片。密钥只写不读:表单只显示是否已保存密钥,密钥栏留空则保留原密钥。新增的行会得到 id model-N。代码中配置的模型(provider 为 custom)只读显示;保存会替换掉它们,表单会提示这一点。恢复默认会先请求确认,然后调用 DELETE /aidy/v0/settings 并显示配置中的模型链。把它放在 AidyProvider 内、只有管理员能访问的页面上;无论如何,服务端都会校验 aidy:admin。见 React。