模型选择 - Qoder CN

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

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

两种模式互斥：传入回调即进入动态选择模式，固定模型设置被忽略。 Java 通过 SessionOptions.Builder.modelSelection(...) 三选一：ModelSelection.staticModel(...) 对应固定模型；动态选择有两种回调，ModelSelection.dynamic(...) 只返回模型 ID，ModelSelection.policy(...) 返回结构化结果，可以附带参数或保留 CLI 当前的模型。回调只在 CLI 需要选择模型时调用，初始化时不会调用。

固定模型

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

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

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

动态选择

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

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

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

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

回调入参可读取本次请求的用途、会话信息和当前可用模型列表。Java 中对应 ModelRequestContext 的 purpose()、sessionId()、availableModels() 等方法，可选字段返回 Optional。

按用途路由

不同用途用不同模型：

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。

返回模型参数

回调可以在选定模型的同时返回 parameters，为本次 LLM 请求覆盖上下文窗口和思考深度。这里是 SDK 控制层字段，参数名使用 camelCase：

const resolveModel: ModelPolicyProvider = (context) => {
  return {
    model: 'ultimate',
    parameters: {
      contextWindow: 200000,
      reasoningEffort: 'high',
    },
  };
};

Java 要返回参数时使用 ModelSelection.policy(...)，parameters(JsonObject) 的内容原样交给 CLI。只想保留 CLI 已选的模型时，返回 ModelPolicyResult.keepCurrent()。这些值应选择当前模型支持的配置。可用的上下文窗口和思考深度元数据会通过回调入参的 availableModels 暴露在 ModelInfo.context_config 和 ModelInfo.thinking_config 中。Java 的 ModelInfo 没有为这些元数据建模，从 ModelInfo.raw() 读取。

超时

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

{ resolveModel, resolveModelTimeoutMs: 800 }

Java 的默认超时是 500 毫秒，0 表示不限时。

运行时操作

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

import { qodercliAuth, query } from '@qodercn-ai/qodercn-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.isEnabled ?? true}`);
}

Java 在 QoderSession 上调用 getAvailableModels()，会话打开后不需要发送输入就能查询；需要显式选择实时读取或缓存时，传入 ModelCatalogOptions。CLI 没有给出 isEnabled 字段时，Java 的 ModelInfo.isEnabled() 返回 false，与上面 TypeScript 示例按 true 处理不同。也可以在固定模型模式下切换当前模型；具体方法签名见 SDK References。Java 没有切换当前模型的方法。

错误处理

动态选择模式下没有自动降级——回调超时、抛异常、返回空模型都会让 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
  }
};

Java 中回调抛出异常、返回异常完成的 stage 或超时，本次模型请求都会失败，不会回退到初始模型。exceptionally(...) 只能兜住回调自己的失败，超过 resolveModelTimeoutMs 的等待仍会失败。这些失败不会以异常交给应用，SDK 只把错误码回给 CLI（超时为 MODEL_RESOLUTION_TIMEOUT，回调失败为 CALLBACK_EXECUTION_FAILED），并发出 inbound_control_request_failed 诊断事件，detail 含 error=<错误码>。需要感知时注册诊断监听器，本轮结果按 ResultMessage.outcome() 处理。完整字段、类型定义见 SDK References。

​固定模型

​动态选择

​按用途路由

​返回模型参数

​超时

​运行时操作