模型选择 - Qoder

query() 提供两种模型选择模式：

固定模型（默认）：整个会话用一个模型。
动态选择：每次 LLM 请求前调用回调函数返回模型。可以按用途（主对话、子代理、上下文压缩等）路由不同模型，或返回 BYOK 凭证用自己的 API Key。

两种模式互斥：传入回调即进入动态选择模式，固定模型设置被忽略。

固定模型

通过模型选项指定，省略时使用账号默认：

import { qodercliAuth, query } from '@qoder-ai/qoder-agent-sdk';

const q = query({
  prompt: 'Analyze this code',
  options: {
    auth: qodercliAuth(),
    model: 'performance',
  },
});

动态选择

提供一个回调函数，每次 LLM 请求前都会被调用：

import { qodercliAuth, query, type ModelPolicyProvider } from '@qoder-ai/qoder-agent-sdk';

const resolveModel: ModelPolicyProvider = (context) => {
  return { model: 'performance' };
};

const q = query({
  prompt: 'Analyze this code',
  options: {
    auth: qodercliAuth(),
    resolveModel,
  },
});

回调入参可读取本次请求的用途、会话信息和当前可用模型列表。

按用途路由

不同用途用不同模型：

const resolveModel: ModelPolicyProvider = (context) => {
  switch (context.purpose) {
    case 'main':       return { model: 'performance' };
    case 'subagent':   return { model: 'efficient' };
    case 'compact':    return { model: 'lite' };
    default:           return { model: 'auto' };
  }
};

用途涵盖主对话、子代理、上下文压缩、WebFetch、图像生成等场景，完整值见 SDK References。

超时

回调有默认超时（毫秒级），回调内做远程调用时可以放宽：

{ resolveModel, resolveModelTimeoutMs: 800 }

BYOK：使用自己的 API Key

回调返回的也可以是 BYOK 凭证对象——本次请求会路由到第三方 provider：

const resolveModel: ModelPolicyProvider = () => ({
  model: {
    provider: 'bailian',
    model: 'qwen3.5-plus-cp',
    api_key: process.env.MY_API_KEY!,
  },
});

可用的 provider / model 目录可通过运行时方法拉取，前端据此渲染选择器和 API Key 输入框。在把用户提供的 BYOK 凭证放进 resolveModel 之前，可以先通过 CLI 校验 provider / model / API-key 组合：

const q = query({
  prompt: 'Validate BYOK configuration',
  options: { auth: qodercliAuth() },
});

const ok = await q.validateByokModel({
  provider: 'openai',
  model: 'gpt-4o',
  api_key: process.env.MY_API_KEY!,
  url: 'https://api.openai.com/v1',
  style: 'openai',
});

if (ok === false) {
  throw new Error('Invalid BYOK configuration');
}

当当前 CLI 不支持 BYOK 校验时，该方法返回 null。

运行时操作

会话进行中可以拉取当前账号实时可用的模型列表：

import { qodercliAuth, query } from '@qoder-ai/qoder-agent-sdk';

const q = query({
  prompt: '...',
  options: { auth: qodercliAuth() },
});

const models = await q.getAvailableModels();
for (const m of models) {
  console.log(`${m.value}\t${m.displayName}\t${m.description}`);
}

ModelInfo 还会在后端返回时携带可用状态、context_config、thinking_config 等更丰富的模型元数据。也可以在固定模型模式下切换当前模型、拉取 BYOK provider 目录，或校验 BYOK 模型配置；具体方法签名见 SDK References。

错误处理

动态选择模式下没有自动降级——回调超时、抛异常、返回空模型都会让 query 失败。回调内部建议自己兜底：

const resolveModel: ModelPolicyProvider = async (context) => {
  try {
    const policy = await fetchRemotePolicy(context);
    return { model: policy.model };
  } catch {
    return { model: 'auto' };   // fallback, must be non-empty
  }
};

完整字段、类型定义见 SDK References。

​固定模型

​动态选择

​按用途路由

​超时

​BYOK：使用自己的 API Key

​运行时操作

​错误处理