夜雨聆风学习资料网

ARTICLE · 1366581

Claude Code 源码-API 请求构造与模型路由

Claude Code 源码-API 请求构造与模型路由

Claude Code 源码解析系列

第 7 讲:API 请求构造与模型路由

基于 Claude Code 源码快照 · 2026-11-17

💡 本讲一句话:第 6 讲讲 QueryEngine 怎么"收"事件流,这一讲讲请求是怎么"发"出去的——services/api/claude.ts(3419 行)里的 queryModel() 把每次模型调用组装成一条 HTTP 请求:15 个 body 字段、四道 provider 路由门(first-party / Bedrock / Vertex / Foundry)、一套不能乱动的 beta flags。每一处代码都是成本、稳定性与缓存命中率的权衡。

一、请求体骨架:一个 return 里的 15 个字段

所有模型调用最终都汇聚到 queryModel()(claude.ts 第 1017 行)。它不直接拼请求体,而是定义了一个闭包函数 paramsFromContext(retryContext)——每次尝试(含重试)都会重新执行一遍。先看它的返回值,这就是发出去的 JSON body 的完整骨架:

📄 src/services/api/claude.ts (第 1699-1728 行)

return { // 请求体对象开始  model: normalizeModelStringForAPI(options.model), // 发送前剥掉 [1m] 上下文窗口后缀,API 只认干净模型名  messages: addCacheBreakpoints(                    // 给消息历史插 cache_control 断点(第 12 讲细讲)    messagesForAPI,                                 // 已归一化 + 修复的消息数组    enablePromptCaching,                            // prompt caching 总开关    options.querySource,                            // querySource 决定能否用 1h TTL    useCachedMC,                                    // cached microcompact 开关    consumedCacheEdits,                             // 待消费的缓存编辑(只消费一次)    consumedPinnedEdits,                            // 固定位置的缓存编辑    options.skipCacheWrite,                         // 本次请求是否跳过写缓存  ), // messages 参数列表结束  system,                                           // 系统提示词块数组(带 cache_control)  tools: allTools,                                  // 工具 schema + advisor 服务端工具  tool_choice: options.toolChoice,                  // 强制选某工具,通常 undefined = auto  ...(useBetas && { betas: betasParams }),          // beta 列表非空才挂上  metadata: getAPIMetadata(),                       // 归因信息:设备 + 账号 + 会话 ID  max_tokens: maxOutputTokens,                      // 输出上限(重试上下文可覆盖)  thinking,                                         // 思考配置:adaptive 或 budget_tokens  ...(temperature !== undefined && { temperature }),// 只在 thinking 关闭时才发送  ...(contextManagement &&                          // 上下文管理策略    useBetas &&                                     // 需要 beta header 支持    betasParams.includes(CONTEXT_MANAGEMENT_BETA_HEADER) && { // 且对应 beta 已挂载才生效      context_management: contextManagement,        // 例如 clearAllThinking    }), // context_management 条件块结束  ...extraBodyParams,                               // 用户 CLAUDE_CODE_EXTRA_BODY + 反蒸馏等  ...(Object.keys(outputConfig).length > 0 && {     // output_config 非空才挂(effort/task_budget/format)    output_config: outputConfig,                    // 输出配置块  }), // output_config 条件块结束  ...(speed !== undefined && { speed })             // fast mode 标记

为什么这样设计:三个细节值得注意。其一,参数是"每次尝试现算"的函数而不是固定对象——重试时 retryContext.maxTokensOverride 可以覆盖输出上限(上下文溢出后升到 64k),fastMode 也可能在两次尝试之间变化,闭包让每次 attempt 基于自己的 RetryContext 重新求值。其二,...extraBodyParams 放在展开链的靠后位置——用户通过环境变量注入的字段优先级最高,是官方留的逃生舱(escape hatch)。其三,所有可选字段都用 ...(cond && {...}) 条件展开:不满足就整个键消失,而不是传 undefined/空值——Anthropic API 对未知或空字段会直接 400,"少发"永远比"错发"安全。

下表汇总这个 body 里每个字段的来源与门控条件——后面几节逐个展开:

请求字段
来源函数
门控条件
model
normalizeModelStringForAPI
恒发;剥 [1m] 后缀
messages
addCacheBreakpoints
断点取决于 caching 开关 + querySource
system
buildSystemPromptBlocks
cache_control 取决于 caching 开关
tools
toolToAPISchema × N
defer_loading 取决于 tool search
betas
getMergedBetas + 会话锁存
非空才发送;provider 决定放哪
metadata
getAPIMetadata
恒发(归因)
max_tokens
getMaxOutputTokensForModel
重试上下文可覆盖;env 可夹逼
thinking
adaptive / budget 二选一
模型支持 + env 开关
temperature
options.temperatureOverride ?? 1
仅 thinking 关闭时发送
output_config
configureEffortParams / TaskBudget
模型支持 + first-party
speed
fastMode 判定链
开关 + 可用 + 非冷却期 + 模型支持

二、Provider 路由:同一个 client,四道门

paramsFromContext 算出参数后,真正发请求的是 anthropic.beta.messages.create()(claude.ts 第 1822-1831 行)。但 anthropic 这个 client 是谁?答案是 getAnthropicClient()(client.ts 第 88 行)——一个按环境变量分流的工厂:Bedrock、Foundry(Azure)、Vertex 各走一条分支,都不满足才落到 first-party。先看所有分支共享的默认头:

📄 src/services/api/client.ts (第 104-116 行)

const customHeaders = getCustomHeaders() // 解析 ANTHROPIC_CUSTOM_HEADERS(curl 风格 "Name: Value" 行)const defaultHeaders: { [key: string]: string } = { // 默认请求头对象  'x-app': 'cli',                                    // 标记客户端类型是 CLI,服务端统计用  'User-Agent': getUserAgent(),                      // 版本 + 平台信息  'X-Claude-Code-Session-Id': getSessionId(),        // 会话 ID:服务端日志能关联到本地会话  ...customHeaders,                                  // 用户自定义头(如代理鉴权)  ...(containerId ? { 'x-claude-remote-container-id': containerId } : {}), // 远程容器标记  ...(remoteSessionId                                // 远程会话 ID    ? { 'x-claude-remote-session-id': remoteSessionId } // 有值才挂这个头    : {}), // 无值则不挂  ...(clientApp ? { 'x-client-app': clientApp } : {}),// SDK 消费方的应用名,后端分析用

再看 first-party 分支的鉴权选择(client.ts 第 300-315 行)——这是"你是谁"的最终裁决:

📄 src/services/api/client.ts (第 300-315 行)

const clientConfig: ConstructorParameters<typeof Anthropic>[0] = { // first-party 客户端配置对象  apiKey: isClaudeAISubscriber() ? null : apiKey || getAnthropicApiKey(), // 订阅用户不用 API key,避免双鉴权  authToken: isClaudeAISubscriber()                                        // 订阅用户走 OAuth 通道    ? getClaudeAIOAuthTokens()?.accessToken                                // 用 OAuth access token    : undefined, // 非订阅用户没有 OAuth token  ...(process.env.USER_TYPE === 'ant' &&                                  // 仅内部 ant 用户  isEnvTruthy(process.env.USE_STAGING_OAUTH)                              // 且显式开了 staging    ? { baseURL: getOauthConfig().BASE_API_URL }                          // 指向 staging OAuth 端点    : {}), // 否则不改 baseURL  ...ARGS,                                                                // defaultHeaders / timeout / 代理 fetch 等} // 配置对象结束return new Anthropic(clientConfig)                                        // 返回 first-party client

为什么这样设计:四道门的鉴权方式完全不同——Bedrock 用 AWS SigV4 凭证或 Bearer token(client.ts 第 172-187 行),Vertex 用 GoogleAuth 服务账号(第 266-297 行,还专门处理了 GCE metadata server 的 12 秒超时陷阱:只有用户没配任何 project 发现方式时才注入 projectId 兜底),Foundry 用 Azure AD bearer token(第 195-210 行)。但对外暴露的调用面是统一的 Anthropic 类型——三个分支都靠 as unknown as Anthropic 强转(源码注释自嘲 "we have always been lying about the return type"),上层代码完全无感。另外两个细节:主请求路径上 client 的 maxRetries: 0(claude.ts 第 1781 行)——刻意关掉 SDK 自动重试,因为重试需要重建参数(换模型、改 max_tokens),SDK 的黑盒重试做不到;x-client-request-id 关联头只在 first-party + 官方 baseURL 时注入(client.ts 第 364-376 行)——超时时服务端没有 request ID,客户端自己生成 UUID 才能和日志对上,而第三方 provider 不记录这个头、严格代理还可能拒绝未知头。

🔑 模型名路由:发给 API 的模型名还要过两道加工。Bedrock 上 application-inference-profile 是逻辑别名,必须先解析成真实 backing model(claude.ts 第 1057-1062 行);所有 provider 都要剥掉 [1m]/[2m] 上下文窗口后缀——normalizeModelStringForAPI 全文就一行:model.replace(/\[(1|2)m\]/gi, '')(utils/model/model.ts 第 616-618 行)。用户写 claude-sonnet[1m] 是本地语义,API 只认裸模型名。

三、Beta flags:一份不能乱动的动态清单

Anthropic API 的新特性(thinking、tool search、structured outputs……)都要靠 beta header 解锁。但 beta header 同时参与服务端缓存 key 的计算——中途加一个或删一个,整个会话前缀缓存作废。所以这份清单的组装被拆成三层:基础层按模型合并、动态层按特性追加、锁存层保证"发过就一直在"。

第一层,getMergedBetas()(utils/betas.ts 第 397-428 行):

📄 src/utils/betas.ts (第 397-428 行)

export function getMergedBetas( // 合并某模型 + 查询类型的 beta 清单  model: string, // 目标模型名  options?: { isAgenticQuery?: boolean }, // 是否 agentic 查询(可选)): string[] { // 返回值:beta header 列表  const baseBetas = [...getModelBetas(model)] // 按模型的基础 beta 列表(带缓存),拷贝防污染  if (options?.isAgenticQuery) {              // agentic 查询需要额外两个头    if (!baseBetas.includes(CLAUDE_CODE_20250219_BETA_HEADER)) { // claude-code 头还没加过?      baseBetas.push(CLAUDE_CODE_20250219_BETA_HEADER) // 补上:启用服务端工具语义    } // claude-code 头检查结束    if ( // 第二个附加头(仅内部)      process.env.USER_TYPE === 'ant' &&      // 仅内部用户      process.env.CLAUDE_CODE_ENTRYPOINT === 'cli' && // 且是官方 CLI 入口      CLI_INTERNAL_BETA_HEADER &&             // 且配置了内部头常量      !baseBetas.includes(CLI_INTERNAL_BETA_HEADER) // 且尚未添加过    ) { // 条件全部满足,准备追加      baseBetas.push(CLI_INTERNAL_BETA_HEADER) // cli-internal:内部专属特性    } // 内部头检查结束  } // agentic 查询附加头逻辑结束  const sdkBetas = getSdkBetas()              // SDK 注入的 betas(已按白名单过滤)  if (!sdkBetas || sdkBetas.length === 0) {   // 没有 SDK beta    return baseBetas                          // 原样返回基础列表  } // 空判断结束  return [...baseBetas, ...sdkBetas.filter(b => !baseBetas.includes(b))] // 合并去重后返回

第二层,会话锁存(claude.ts 第 1405-1429 行)——这是本讲最反直觉的一段代码:

📄 src/services/api/claude.ts (第 1405-1429 行)

let afkHeaderLatched = getAfkModeHeaderLatched() === true // 读锁存:本会话是否已发过?if (feature('TRANSCRIPT_CLASSIFIER')) {                    // feature flag 门控  if ( // afk header 锁存条件检查    !afkHeaderLatched &&                                   // 还没锁上    isAgenticQuery &&                                       // 仅 agentic 查询    shouldIncludeFirstPartyOnlyBetas() &&                   // 仅 first-party    (autoModeStateModule?.isAutoModeActive() ?? false)      // auto mode 当前激活  ) { // 条件全部满足,执行锁存    afkHeaderLatched = true                                 // 本地标记为已锁    setAfkModeHeaderLatched(true)                            // 写入会话状态:之后每次请求都带  } // 锁存逻辑结束} // TRANSCRIPT_CLASSIFIER 门控块结束let fastModeHeaderLatched = getFastModeHeaderLatched() === true // 读 fast mode 锁存状态if (!fastModeHeaderLatched && isFastMode) {                 // fast mode 首次激活  fastModeHeaderLatched = true                               // 本地标记为已锁  setFastModeHeaderLatched(true)                             // 之后即使进冷却期也不撤 header(避免 bust cache)

为什么这样设计:源码注释说得很直白:每个 beta header "once first sent, keeps being sent for the rest of the session so mid-session toggles don't change the server-side cache key and bust ~50-70K tokens"(第 1405-1410 行)。注意锁存的是 header,不是行为——fast mode 的 speed='fast' body 字段仍然是动态判定的(冷却期照样压制实际请求),只是 header 不撤。这样"功能开关抖动"和"缓存 key 稳定"解耦了。锁存会在 /clear 和 /compact 时统一清除(clearBetaHeaderLatches())——那时会话前缀本来就要重建,缓存作废是预期内的。

第三层藏在 getExtraBodyParams()(claude.ts 第 272-331 行)里——用户逃生舱 + 一个安全特性:

📄 src/services/api/claude.ts (第 301-331 行,节选)

// Anti-distillation: send fake_tools opt-in for 1P CLI only // 反蒸馏:仅 first-party CLI 开启假工具水印if ( // 四重门控检查开始  feature('ANTI_DISTILLATION_CC')                              // 编译期 feature flag 门控    ? process.env.CLAUDE_CODE_ENTRYPOINT === 'cli' &&          // 仅官方 CLI 入口      shouldIncludeFirstPartyOnlyBetas() &&                    // 仅 first-party API      getFeatureValue_CACHED_MAY_BE_STALE(                     // 远程配置(允许读到旧值)        'tengu_anti_distill_fake_tool_injection',             // 实验 key 名        false,                                                 // 默认关      ) // 条件表达式结束    : false                                                    // flag 未编译进 → 恒为 false) { // 门控全部通过,启用水印  result.anti_distillation = ['fake_tools']                    // 告知服务端注入假工具(反蒸馏水印)} // 反蒸馏块结束if (betaHeaders && betaHeaders.length > 0) {                   // 调用方传入了额外 betas  if (result.anthropic_beta && Array.isArray(result.an)) {     // 用户 env 里已设过且是数组    const existingHeaders = result.anthropic_beta as string[]  // 取出已有列表做类型断言    const newHeaders = betaHeaders.filter(                      // 去重:只保留尚未存在的头      header => !existingHeaders.includes(header), // 过滤谓词结束    ) // filter 调用结束    result.anthropic_beta = [...existingHeaders, ...newHeaders] // 合并写回  } else { // 没有现成的 anthropic_beta 值    result.anthropic_beta = betaHeaders                         // 直接整体使用传入列表  } // beta 合并分支结束} // 函数体结束

为什么这样设计:anti_distillation: ['fake_tools'] 是服务端反蒸馏机制的客户端开关——让 API 在响应里注入"假工具"作为水印,事后可以识别哪些模型是用 Claude Code 流量蒸馏出来的。四重门控(编译期 flag + CLI 入口 + first-party + 远程实验位)说明它是个灰度中的安全特性,任何一层不满足都静默关闭。而 beta 合并逻辑里有个容易踩的坑被注释点破了:safeParseJSON 带 LRU 缓存、同一字符串返回同一个对象引用——所以第 286 行必须浅拷贝 { ...(parsed as JsonObject) },否则往 result 里写 beta 会"毒化"缓存,后续所有解析同串的用户都拿到被改过的值。

📊 四道 provider 门对照(鉴权 / 区域 / beta 放置)

First-party(api.anthropic.com)

鉴权方式 OAuth token(订阅用户)或 ANTHROPIC_API_KEY区域处理 无Beta 放置 body.betas 数组特殊点 x-client-request-id 关联头只在此注入

Bedrock(AWS)

鉴权方式 AWS SigV4 凭证,或 Bearer token区域处理 按模型 region env;small/fast model 可单独覆盖Beta 放置 tool-search header 放 extraBodyParams,不进 betas 数组特殊点 inference profile 需先解析成 backing model

Vertex(GCP)

鉴权方式 GoogleAuth 服务账号区域处理 getVertexRegionForModel;projectId 兜底防 12s metadata 超时Beta 放置 同 first-party(tool-search-tool 头)特殊点 凭证按需刷新;mock GoogleAuth 供测试/代理场景

Foundry(Azure)

鉴权方式 Azure AD bearer token,或 ANTHROPIC_FOUNDRY_API_KEY区域处理 无(endpoint 决定)Beta 放置 同 first-party特殊点 支持 mock token provider(测试/代理场景)

四、Prompt caching 控制:谁配得上 1 小时 TTL

cache_control 是告诉服务端"把到这里为止的前缀缓存起来"的断点。两个问题:断点插在哪、TTL 给多长。Anthropic 对 1h TTL 的缓存写入收费更高,所以资格判定被做成了双重门控 + 会话锁存(claude.ts 第 393-434 行):

📄 src/services/api/claude.ts (第 393-434 行)

function should1hCacheTTL(querySource?: QuerySource): boolean { // 判定是否使用 1 小时缓存 TTL  if ( // Bedrock 特殊路径检查    getAPIProvider() === 'bedrock' &&                           // provider 是 Bedrock    isEnvTruthy(process.env.ENABLE_PROMPT_CACHING_1H_BEDROCK)   // env opt-in,无需远程配置  ) { // 条件满足,直接放行    return true                                                 // Bedrock 用户自管账单,允许 1h TTL  } // Bedrock 分支结束  let userEligible = getPromptCache1hEligible()                 // 读会话锁存(null = 未判定)  if (userEligible === null) { // 首次判定资格    userEligible =                                              // 资格:内部用户,或没超额的订阅者      process.env.USER_TYPE === 'ant' ||                         // 内部 ant 用户直接合格      (isClaudeAISubscriber() && !currentLimits.isUsingOverage) // 或订阅中且未进入超额计费    setPromptCache1hEligible(userEligible)                      // 锁存:防会话中途 overage 翻转改 TTL  } // 资格判定结束  if (!userEligible) return false                               // 没资格,短路返回  let allowlist = getPromptCache1hAllowlist()                   // 读白名单锁存  if (allowlist === null) { // 首次读取白名单    const config = getFeatureValue_CACHED_MAY_BE_STALE<{        // GrowthBook 远程配置(泛型指定形状)      allowlist?: string[]                                      // 形如 ["repl_main_thread*", "sdk"]    }>('tengu_prompt_cache_1h_config', {}) // 配置 key + 默认空对象    allowlist = config.allowlist ?? []                          // 取白名单,缺省为空列表(谁都不给)    setPromptCache1hAllowlist(allowlist)                        // 锁存:防磁盘缓存中途更新导致 TTL 混杂  } // 白名单判定结束  return ( // 最终判定:来源标签必须命中白名单    querySource !== undefined &&                                // 必须有来源标签    allowlist.some(pattern =>                                   // 任一模式匹配即通过      pattern.endsWith('*') // 通配符模式?        ? querySource.startsWith(pattern.slice(0, -1))          // "repl_main_thread*" 命中所有主线程来源        : querySource === pattern,                               // 无通配符 = 精确相等    ) // some 匹配结束  ) // return 表达式结束} // 函数体结束

为什么这样设计:注释点破了锁存的动机:"prevents mid-session overage flips from changing the cache_control TTL, which would bust the server-side prompt cache (~20K tokens per flip)"(第 403-405 行)。资格和白名单都"首次判定后冻结到会话结束"——宁可让一个刚超额的订阅者继续享受 1h TTL,也不愿为了省那点缓存费把整个会话前缀打碎。Bedrock 用户单独走 env opt-in:他们自管账单、没有 GrowthBook 配置,远程门控对他们无意义。

断点插在哪?看 assistant 消息的转换(claude.ts 第 653-668 行)——规则是"只给最后一个块,且跳过不能带 cache_control 的类型":

📄 src/services/api/claude.ts (第 653-668 行)

return { // assistant 消息转换结果  role: 'assistant', // 角色固定为 assistant  content: message.message.content.map((_, i) => ({ // 逐个处理每个内容块,i 是下标    ..._,                                                       // 原块浅拷贝    ...(i === message.message.content.length - 1 &&             // 只有最后一个块有资格    _.type !== 'thinking' &&                                    // thinking 块不能带 cache_control    _.type !== 'redacted_thinking' &&                            // redacted_thinking 同理    (feature('CONNECTOR_TEXT') ? !isConnectorTextBlock(_) : true) // connector text 块也排除      ? enablePromptCaching                                      // 且 caching 开启        ? { cache_control: getCacheControl({ querySource }) }    // 挂断点(ephemeral 或 1h)        : {} // caching 关闭,不挂断点      : {}), // 该块类型无资格挂断点  })), // map 处理结束} // return 对象结束

为什么这样设计:API 限制每个请求最多 4 个 cache_control 断点,且某些块类型(thinking、redacted_thinking)根本不允许携带——所以策略是"能挂的位置里只挂最后一个":缓存前缀天然单调增长,最靠后的断点覆盖范围最大。配套的 userMessageToMessageParam(第 588-631 行)还藏了一个防御性细节:不挂 cache 时也要把数组 content 浅拷贝一份——因为下游的 insertCacheEditsBlock 会 splice 这个数组,若不克隆,多次调用 addCacheBreakpoints 会共享同一份数组、互相塞进重复的 cache_edits(第 622-624 行注释原话)。

五、归因与验证:服务端怎么知道你是谁

每条请求都带一张"名片"。getAPIMetadata()(claude.ts 第 503-528 行)把三级归因信息塞进 metadata.user_id:

📄 src/services/api/claude.ts (第 503-528 行,节选)

export function getAPIMetadata() { // 构建 API 归因元数据  let extra: JsonObject = {}                                    // 用户自定义 metadata,默认空对象  const extraStr = process.env.CLAUDE_CODE_EXTRA_METADATA       // env 注入点  if (extraStr) { // env 变量已设置    const parsed = safeParseJSON(extraStr, false)               // 解析 JSON(不走 LRU 缓存)    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) { // 解析成功且是纯对象      extra = parsed as JsonObject                               // 采纳为自定义字段    } else { // 格式不对(数组/标量)      logForDebugging(                                           // 仅记 debug 日志,不炸请求        `CLAUDE_CODE_EXTRA_METADATA env var must be a JSON object...`, // 错误提示文案        { level: 'error' }, // 日志级别为 error      ) // logForDebugging 调用结束    } // 格式检查分支结束  } // env 变量处理块结束  return { // 返回值:user_id 字段    user_id: jsonStringify({                                     // API 要求 user_id 是字符串 → 整体序列化      ...extra,                                                  // 自定义字段在前(可被后续固定字段覆盖)      device_id: getOrCreateUserID(),                            // 稳定设备 ID(首次运行生成并持久化)      account_uuid: getOauthAccountInfo()?.accountUuid ?? '',    // OAuth 账号 UUID(非 OAuth 登录为空串)      session_id: getSessionId(),                                // 当前会话 ID,服务端按会话聚合    }), // user_id 序列化结束  } // return 对象结束} // 函数体结束

归因其实有三处落点:metadata.user_id(设备/账号/会话三级)、请求头 X-Claude-Code-Session-Id、以及系统提示词里的 attribution header——getAttributionHeader(fingerprint) 在拼 system prompt 时注入(claude.ts 第 1358-1369 行),fingerprint 由第一条真实用户消息计算,且必须在注入合成消息之前算好(第 1322-1324 行注释:否则指纹反映的是机器生成的内容而非用户输入)。这套设计服务于滥用检测与流量归因——在泄露快照的背景下尤其值得注意:服务端能精确区分"官方 CLI 的哪个会话、哪台设备、哪个账号"发出的请求。

API key 验证则是另一头:verifyApiKey()(claude.ts 第 530-586 行)用一次尽可能便宜的调用探活:

📄 src/services/api/claude.ts (第 543-567 行,节选)

return await returnValue( // 从重试生成器中提取最终值  withRetry( // 用重试逻辑包裹整个验证流程    () => // client 工厂:需要时才创建      getAnthropicClient({        apiKey,                                                 // 待验证的 key        maxRetries: 3,                                          // SDK 级重试(此路径不走手动重试环)        model,                                                  // Haiku——最便宜的模型        source: 'verify_api_key',                               // 标记请求来源,服务端统计用      }), // client 配置结束    async anthropic => {                                        // 真正的验证调用(回调函数体)      const messages: MessageParam[] = [{ role: 'user', content: 'test' }] // 最小消息体      await anthropic.beta.messages.create({ // 发出验证请求(beta messages API)        model,                                                  // small fast model:Haiku 4.5        max_tokens: 1,                                          // 只要 1 token——只为验证 key 有效        messages,                                               // 上面的测试消息        temperature: 1,                                         // 固定值,无需采样        ...(betas.length > 0 && { betas }),                     // 带上模型要求的 beta(否则 400)        metadata: getAPIMetadata(),                             // 归因信息        ...getExtraBodyParams(),                                // 用户 extra body 参数      }) // 请求参数结束      return true                                               // 请求成功 = key 有效    }, // 重试回调函数结束    { maxRetries: 2, model, thinkingConfig: { type: 'disabled' } }, // 比正常请求更少重试;关思考省成本  ), // withRetry 调用结束) // returnValue 调用结束

为什么这样设计:验证调用刻意选 Haiku + max_tokens: 1——这是能走通完整鉴权链路的最便宜请求(第 540 行注释警告:换成非 Haiku 模型,1P 环境会因缺少 CLI sysprompt prefix 而失败)。错误处理上有个精确匹配:只有响应体里出现 "invalid x-api-key" 这个确切字符串才返回 false(key 无效),其他异常一律 rethrow——网络抖动不该被误判成"key 错了"。另外 queryModel() 入口还有一道远程 kill switch(第 1028-1049 行):tengu-off-switch 只对非订阅的 Opus 用户生效,且先做两个廉价判断、都通过才 await GrowthBook 初始化(约 10ms 阻塞)——"便宜的检查放前面"是贯穿这个文件的性能纪律。

六、输出参数:思考预算与槽位预留

body 的最后三个旋钮:想多久(thinking)、写多长(max_tokens)、什么形态(output_config)。thinking 的选择逻辑在 paramsFromContext 里(claude.ts 第 1604-1630 行):

📄 src/services/api/claude.ts (第 1604-1630 行)

if (hasThinking && modelSupportsThinking(options.model)) {      // thinking 开启且模型支持  if ( // adaptive thinking 条件检查    !isEnvTruthy(process.env.CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING) && // env 未禁用    modelSupportsAdaptiveThinking(options.model)                 // 模型支持 adaptive thinking  ) { // 条件满足,走自适应模式    thinking = {                                                 // adaptive:让模型自己决定想多少      type: 'adaptive',                                          // 不设预算、不固定 token 数    } satisfies BetaMessageStreamParams['thinking']              // 类型断言:符合 thinking 参数形状  } else { // 回退到固定预算模式    let thinkingBudget = getMaxThinkingTokensForModel(options.model) // 按模型的默认预算    if ( // 调用方是否显式指定了预算?      thinkingConfig.type === 'enabled' &&                       // thinking 配置为 enabled      thinkingConfig.budgetTokens !== undefined                  // 且预算值非空    ) { // 是,用调用方的值覆盖默认      thinkingBudget = thinkingConfig.budgetTokens               // 采纳显式指定的预算    } // 预算覆盖检查结束    thinkingBudget = Math.min(maxOutputTokens - 1, thinkingBudget) // 必须小于 max_tokens(API 硬约束)    thinking = {                                                 // budget 模式:固定 token 数      budget_tokens: thinkingBudget,                             // 思考 token 上限      type: 'enabled',                                           // 显式启用    } satisfies BetaMessageStreamParams['thinking']              // 类型断言:符合参数形状  } // 预算模式分支结束} // thinking 配置逻辑结束

为什么这样设计:新模型走 adaptive(模型自决思考深度),老模型走固定预算——但预算被 Math.min(maxOutputTokens - 1, ...) 夹住,因为 API 要求 thinking budget 严格小于 max_tokens。配套的 temperature 规则同样微妙:thinking 开启时 API 强制 temperature=1(本来就是默认值),所以干脆不发这个字段(第 1691-1695 行)——少发一个字段就少一种冲突可能。

max_tokens 的默认值则藏着一个容量经济学决策(claude.ts 第 3398-3417 行):

📄 src/services/api/claude.ts (第 3398-3417 行)

export function getMaxOutputTokensForModel(model: string): number { // 计算某模型生效的最大输出 token  const maxOutputTokens = getModelMaxOutputTokens(model)         // 按模型的默认值 + 上限表  // Slot-reservation cap: drop default to 8k for all models. BQ p99 output // 槽位预留上限:把默认压到 8k(BQ 统计 p99 实际输出仅 ~4,911 token)  // = 4,911 tokens; 32k/64k defaults over-reserve 8-16× slot capacity.     // 32k/64k 默认值会让服务端槽位被超额预留 8-16 倍  const defaultTokens = isMaxTokensCapEnabled()                  // 远程开关(3P 默认关)    ? Math.min(maxOutputTokens.default, CAPPED_DEFAULT_MAX_TOKENS) // 压到 8k;原生默认更低的模型保持原值    : maxOutputTokens.default                                    // 开关关 → 用模型原生默认  const result = validateBoundedIntEnvVar(                       // env 覆盖 + 范围校验    'CLAUDE_CODE_MAX_OUTPUT_TOKENS',                             // 变量名(报错信息用)    process.env.CLAUDE_CODE_MAX_OUTPUT_TOKENS,                   // 用户设的值    defaultTokens,                                               // 未设置/非法时的兜底    maxOutputTokens.upperLimit,                                  // 硬上限:不能超过模型上限  ) // env 校验调用结束  return result.effective                                        // 返回最终生效值

为什么这样设计:注释里的数据是核心:BQ(BigQuery)统计 p99 实际输出只有 4,911 token,而 32k/64k 的默认值会让服务端为每个请求预留 8-16 倍的推理槽位——把默认压到 8k 能释放大量容量给其他用户;真正需要长输出的请求命中上限后,由 query.ts 的 max_output_tokens_escalate 用 64k 干净重试一次。这是典型的"按 p99 定默认、给尾部留升级通道"的容量策略。同属 output_config 的还有 effort(第 440-466 行,数值型 override 仅 ant 内部用户可用)和 task_budget(第 479-501 行,EAP beta:把 token 预算告诉模型让它自己 pacing——与客户端的 +500k auto-continue 是两回事,一个在服务端、一个在 agentic loop)。

七、一条请求的完整旅程

把这一讲的九个环节串起来,就是 queryModel() 从入口到 wire 的数据流:

queryModel():从参数到 wire

① Kill switch:tengu-off-switch

仅非订阅 Opus 用户;廉价判断在前,避免白等 GrowthBook 初始化(~10ms)。

▼

② 模型解析:inference profile → backing model

Bedrock 逻辑别名先解析;所有 provider 剥 [1m] 后缀。

▼

③ Beta 组装:getMergedBetas + 会话锁存

基础层按模型合并;afk/fastMode/cacheEditing 发过即锁定,缓存 key 稳定优先。

▼

④ 工具 schema:defer_loading 动态加载

只发已发现的 deferred tools;MCP 工具标记可延迟,解除数量上限。

▼

⑤ 消息修复:normalize → pairing → strip

tool_use/tool_result 配对修复;advisor 块剥离;媒体裁到 100 条内。

▼

⑥ System prompt:attribution + CLI prefix + cache blocks

fingerprint 在注入合成消息前计算;splitSysPromptPrefix 切块挂 cache_control。

▼

⑦ 参数定稿:paramsFromContext(每次 attempt)

thinking 预算、max_tokens(重试可覆盖)、output_config 在此收敛。

▼

⑧ Provider 路由:getAnthropicClient

🔹 firstParty / Bedrock / Vertex / Foundry 四道门,鉴权各异、调用面统一。

▼

⑨ 发出:anthropic.beta.messages.create(stream:true)

first-party 附 x-client-request-id;raw stream 避免 O(n²) 增量 JSON 解析。

本讲要点:

🔹 请求体是"每次尝试现算"的函数:重试可以换模型、改 max_tokens,SDK 黑盒重试做不到——所以主路径 maxRetries: 0,手动 withRetry 环接管。

🔹 Beta header 发过即锁存:缓存 key 稳定性 > 功能开关灵活性;锁的是 header,行为字段(speed、useCachedMC)保持动态。

🔹 1h TTL 双重门控 + 会话冻结:用户资格 × querySource 白名单,两者都首次判定后锁死——宁可多付缓存费,不打碎 20K token 的前缀。

🔹 归因三落点:metadata.user_id(设备/账号/会话)、X-Claude-Code-Session-Id 头、system prompt 里的 fingerprint——服务端能精确到"哪个会话的哪台设备"。

🔹 容量经济学:max_tokens 默认压到 8k(p99 实际输出仅 ~4.9k),长输出靠一次 64k 干净重试兜底。

下一讲进入 claude.ts 下段:SSE 事件流怎么逐 token 解析、超时/限流时指数退避怎么算、错误如何分类——"发出去之后"的故事。

📚 系列导航

← 第 6 讲:QueryEngine 流式事件循环与错误恢复

→ 第 8 讲:SSE 流式解析与重试退避

关注公众号「AI技术推荐官」获取更多源码解析内容

📌 每天 30 条,挑出真能用的 AI 东西

UnitAI 每天从 GitHub / Hacker News / Hugging Face 抓一遍 AI 热榜,还收录了 50+ 个上过榜的项目,能按分类、星级、上榜天数筛。免费看,不用注册。

长按识别二维码打开 · 或点左下角「阅读原文」

回首页,搜索你想要的文档

在首页搜索框输入关键词,快速定位资料

文库首页搜索指引 立即搜索

相关学习资料