模型选择

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

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

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

​

固定模型

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

from qoder_agent_sdk import query, QoderAgentOptions

options = QoderAgentOptions(model="performance")

async for msg in query(prompt="Analyze this code", options=options):
    print(msg)

​

动态选择

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

from qoder_agent_sdk import query, QoderAgentOptions
from qoder_agent_sdk.types import ModelPolicyContext, ModelPolicyResult, ModelPolicyProvider

resolve_model: ModelPolicyProvider = lambda context: {"model": "performance"}

options = QoderAgentOptions(resolve_model=resolve_model)

async for msg in query(prompt="Analyze this code", options=options):
    print(msg)

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

​

按用途路由

不同用途用不同模型：

def resolve_model(context: ModelPolicyContext) -> ModelPolicyResult:
    match context.get("purpose"):
        case "main":     return {"model": "performance"}
        case "subagent": return {"model": "efficient"}
        case "compact":  return {"model": "lite"}
        case _:          return {"model": "auto"}

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

​

返回模型参数

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

def resolve_model(context: ModelPolicyContext) -> ModelPolicyResult:
    return {
        "model": "ultimate",
        "parameters": {
            "contextWindow": 200000,
            "reasoningEffort": "high",
        },
    }

这些值应选择当前模型支持的配置。可用的上下文窗口和思考深度元数据会通过 context["availableModels"] 暴露在 ModelInfo.context_config 和 ModelInfo.thinking_config 中。

​

超时

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

options = QoderAgentOptions(
    resolve_model=resolve_model,
    resolve_model_timeout_ms=800,
)

​

BYOK：使用自己的 API Key

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

import os

def resolve_model(context: ModelPolicyContext) -> ModelPolicyResult:
    return {
        "model": {
            "provider": "bailian",
            "model": "qwen3.5-plus-cp",
            "api_key": os.environ["MY_API_KEY"],
        },
    }

可用的 provider / model 目录可通过运行时方法拉取，前端据此渲染选择器和 API Key 输入框。

​

运行时操作

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

from qoder_agent_sdk import query, QoderAgentOptions

options = QoderAgentOptions(...)

async with QoderSDKClient(options=options) as client:
    models = await client.get_available_models()
    for m in models:
        print(f"{m['value']}\t{m['displayName']}\t{m.get('isEnabled', True)}")

也可以在固定模型模式下切换当前模型，或拉取 BYOK provider 目录；具体方法签名见 SDK References。

​

错误处理

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

async def resolve_model(context: ModelPolicyContext) -> ModelPolicyResult:
    try:
        policy = await fetch_remote_policy(context)
        return {"model": policy["model"]}
    except Exception:
        return {"model": "auto"}  # fallback, must be non-empty

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